Skip to main content

Setting Up Outlook/Microsoft 365 OAuth Authentication

This guide will walk you through creating a Microsoft Azure application for OAuth authentication with Outlook/Microsoft 365. OAuth provides a more secure way to access your Outlook account compared to traditional password authentication.

Prerequisitesโ€‹

  • A Microsoft account (personal or Microsoft 365/Office 365)
  • Access to Azure Portal
  • Your Perfex CRM installation URL (for redirect URI configuration)
info

For Microsoft 365 organizations, you may need admin approval.

Step-by-Step Setupโ€‹

Step 1: Register an Application in Azure Portalโ€‹

  1. Go to Azure Portal
  2. Sign in with your Microsoft account
  3. Navigate to "Azure Active Directory" (or search for it)
  4. Click on "App registrations" in the left menu
  5. Click "+ New registration"
  6. Fill in the application details:
    • Name: Enter a name (e.g., "Perfex CRM Mailbox")
    • Supported account types: Choose "Accounts in any organizational directory and personal Microsoft accounts" for maximum compatibility
    • Redirect URI:
      • Platform: Web
      • URI: https://your-domain.com/admin/mailbox/oauth/callback?provider=outlook
      • Replace your-domain.com with your actual Perfex CRM domain
  7. Click "Register"

Step 2: Configure API Permissionsโ€‹

  1. In your app registration, click "API permissions" in the left menu
  2. Click "+ Add a permission"
  3. Select "Microsoft Graph"
  4. Select "Delegated permissions"
  5. Add the following permissions:
    • Mail.Read - Read mail in all mailboxes
    • Mail.ReadWrite - Read and write mail in all mailboxes
    • Mail.Send - Send mail as the user
    • offline_access - Maintain access to data you have given it access to (for token refresh)
  6. Click "Add permissions"
  7. IMPORTANT: Click "Grant admin consent for [Your Organization]" if you see this button
warning

This is required for organization accounts. This requires admin privileges.

Step 3: Create Client Secretโ€‹

  1. In your app registration, click "Certificates & secrets" in the left menu
  2. Click "+ New client secret"
  3. Enter a description (e.g., "Perfex Mailbox Secret")
  4. Choose an expiration period: 24 months (recommended for production)
  5. Click "Add"
  6. IMPORTANT: Copy the Value immediately (you won't be able to see it again) - this is your Client Secret

Step 4: Get Application (Client) IDโ€‹

  1. In your app registration, go to "Overview"
  2. Copy the Application (client) ID - this is your Client ID

Step 5: Configure Redirect URI (Verify)โ€‹

  1. In your app registration, click "Authentication" in the left menu
  2. Under "Redirect URIs", verify your redirect URI is listed:
https://your-domain.com/admin/mailbox/oauth/callback?provider=outlook
  1. If not present, click "+ Add a platform" > "Web" and add it
  2. Under "Implicit grant and hybrid flows", ensure "Access tokens" is checked (if available)
  3. Click "Save"

Step 6: Configure in Perfex CRMโ€‹

  1. Go to your Perfex CRM admin area
  2. Navigate to Mailbox > Configuration
  3. Select "OAuth2" as your authentication method
  4. Select "Outlook" as your provider
  5. Enter your Client ID (Application ID from Azure)
  6. Enter your Client Secret (the secret value you copied)
  7. For Microsoft 365 organizations: Enter your Tenant ID (found in Azure AD > Overview). Leave blank for personal Microsoft accounts.
  8. Click "Save Configuration"
  9. Click the "Connect Outlook" button
  10. Authorize the application in the Microsoft popup window
  11. You should see a success message confirming the connection

Important Limitations & Considerationsโ€‹

Microsoft Azure App Restrictionsโ€‹

These limitations are imposed by Microsoft, not by our software.

  1. Admin Consent Requirements - Organization accounts (Microsoft 365/Office 365) require admin consent for certain permissions. Admin must approve the app before users can use it.

  2. Account Type Restrictions:

    • "Accounts in this organizational directory only" - Only users in your organization
    • "Accounts in any organizational directory" - Users from any Microsoft 365 organization
    • "Accounts in any organizational directory and personal Microsoft accounts" - Maximum compatibility
    • "Personal Microsoft accounts only" - Only personal @outlook.com, @hotmail.com accounts

  3. Tenant ID Requirements - Organization accounts require Tenant ID for proper authentication. Personal accounts can leave it blank.

App Verification & Publishingโ€‹

  • Unverified Apps can be used immediately for personal accounts but may show warning messages to users.
  • Verified Apps require submission to Microsoft App Store (optional) and provide better user experience (no warnings).
  • Admin Consent Workflow - For organization accounts, admin must grant consent. Admin sees what permissions the app requests.

Token Refreshโ€‹

Our module automatically handles token refresh:

  • Refresh tokens: Automatically obtained with offline_access permission
  • Token expiry: Typically 1 hour for access tokens, 90 days for refresh tokens
  • Automatic refresh: Our module refreshes tokens automatically before expiry

Multi-Tenant vs Single-Tenantโ€‹

  • Multi-Tenant: App can be used by any Microsoft account (requires admin consent per organization)
  • Single-Tenant: App can only be used within your organization

Notesโ€‹

  • The redirect URI must match exactly what you configured in Azure Portal
  • Keep your Client Secret secure - never share it publicly
  • If you change your domain, update the redirect URI in Azure Portal
  • For organization accounts, ensure admin consent is granted
  • Tenant ID is only needed for Microsoft 365/Office 365 accounts
  • The OAuth flow is handled entirely by Microsoft - our module only initiates and receives the callback

Troubleshootingโ€‹

"AADSTS50011: Redirect URI mismatch" error:

  • Ensure the redirect URI in Azure Portal matches exactly: https://your-domain.com/admin/mailbox/oauth/callback?provider=outlook
  • Check for trailing slashes or HTTP vs HTTPS mismatches
  • Verify the URI is listed under "Web" platform type

"Admin consent required" error:

  • This is expected for organization accounts (Microsoft's policy)
  • Contact your Microsoft 365 administrator to grant consent
  • Admin can grant consent in Azure Portal > Enterprise applications

"Invalid client secret" error:

  • Client secrets expire - create a new one in Azure Portal
  • Ensure you copied the "Value" (not the Secret ID)
  • Check that the secret hasn't expired

"AADSTS700016: Application not found" error:

  • Verify the Client ID is correct
  • Ensure you're using the Application (client) ID, not the Object ID
  • Check that the app registration exists in the correct Azure AD tenant

"Token refresh failed" error:

  • Ensure offline_access permission is granted
  • Verify admin consent was granted (for organization accounts)
  • Check that the client secret hasn't expired

Additional Resourcesโ€‹

info

Admin consent requirements, account type restrictions, and token policies are Microsoft's security policies for Azure applications. These limitations are not imposed by our software.