On this page

    Custom email providers with OAuth 2.0

    Identity Engine Early Access

    This guide explains how to configure a custom email provider with OAuth 2.0 authentication and provides some example configurations for Google and Microsoft SMTP services.

    Learning outcomes

    • Learn how to configure custom email providers with OAuth 2.0.
    • Learn how to set up Google and Microsoft SMTP services as custom email providers.

    What you need

    Understand custom email providers and OAuth 2.0

    Okta sends system notifications such as password resets and activation emails using an Okta-managed SMTP server and a default sender address (noreply@okta.com).

    To maintain sender reputation and provide a fully branded experience, you can configure a custom email provider. This routes Okta-generated emails through your organization's mail servers, such as Google Gmail or Microsoft Exchange Online, using your own domain.

    For information about custom email providers, see Use your own email provider (opens new window).

    Secure SMTP with OAuth 2.0

    SMTP with OAuth 2.0 authentication provides a more secure way to connect your org to your email provider.

    Google (opens new window) and Microsoft (opens new window) are deprecating or have already deprecated Basic Authentication (username and password) for their SMTP servers due to limitations of password-based authentication. OAuth 2.0 authentication is the recommended authentication method for those SMTP services.

    Note: Not all email providers support OAuth 2.0 authentication for SMTP. Check with your email provider to confirm that they support OAuth 2.0 for SMTP. This guide only applies to providers that support OAuth 2.0.

    How OAuth 2.0 works with SMTP

    For SMTP, OAuth 2.0 authentication means that Okta doesn’t sign in as a specific user with a password. Instead, Okta authenticates as a secure OAuth 2.0 app (a machine identity) that's authorized to send mail on behalf of your domain.

    Okta obtains an OAuth 2.0 access token from your authorization server and uses that to connect and authenticate with the SMTP server. The authorization server and SMTP server are typically provided by the same company. For example, if you use Google Workspace as your email provider, Google's authorization server issues the OAuth 2.0 access tokens that Okta uses to authenticate with Google's SMTP server.

    In your org, there are two methods for configuring OAuth 2.0 authentication for email providers:

    You can configure either method by using the Email Servers API (opens new window) or by using the Admin Console (opens new window).

    OAuth 2.0 client credentials flow

    The OAuth 2.0 client credentials flow uses a shared secret to authenticate. Your Okta app identifies itself using a client ID and a client secret string. The app acts on its own behalf. It has "Application Permissions" to access specific mailboxes.

    When you use this flow, you create or configure the following settings:

    • You create an OAuth 2.0 app with your email provider that provides a client ID.
    • You create a client secret for the OAuth 2.0 app.
    • You designate a valid user account that the OAuth 2.0 app is authorized to send email from. This is typically the email address used in the "From" field of the email.
    • You assign a scope to your OAuth 2.0 app and account that grants them the authorization to send email.

    OAuth 2.0 JWT bearer token flow

    The OAuth 2.0 JWT bearer token flow uses asymmetric cryptography to authenticate the OAuth 2.0 app without a shared secret. The Okta app uses a private key to sign a JSON Web Token (JWT) that asserts its identity. The provider verifies the signature using a public key.

    The OAuth 2.0 app creates a token that explicitly claims to be a specific user (the sub field). This is known as "impersonation" or "delegation."

    When you use this flow, you create or configure the following settings:

    • You create an OAuth 2.0 app with your email provider that provides a client ID.
    • You create a public/private key pair for the OAuth 2.0 app.
    • You assign a scope that authorizes your OAuth 2.0 app to send email.
    • You create or designate an account that the OAuth 2.0 app can impersonate to send email.

    The public/private key pair generates various properties, including a client ID and private key value.

    Set up your custom email provider for OAuth 2.0

    The following steps explain how to set up a custom email provider and custom domain before you connect your org to your email provider:

    1. Create a custom email domain.
    2. Verify domain ownership.
    3. Set up your email domain with your email provider.

    After you've completed these steps, you can then configure the OAuth 2.0 connection for your custom email provider.

    Create a custom email domain

    Ensure that you have already set up a custom URL domain in your org before creating a custom email domain.

    With your preferred DNS provider, create a custom email domain that matches your org's branding. You can use this domain as the "From" address for system-generated emails that Okta sends. After you've created the custom email domain with your DNS provider, add it to your custom brand and domain in your org. See Configure a custom email address.

    For example, if you have login.mycompany.com as a custom domain in your org, you can create notifications.mycompany.com as a custom email domain. You need the CNAME and TXT records that are generated during this process to verify domain ownership in the next step.

    Verify domain ownership

    Confirm that you can update records for the subdomain that you intend to use as the "From" address for your email provider (notifications.mycompany.com, for example).

    To configure a custom email provider, you must have admin access to your domain's DNS records. You must have the necessary permissions to add and modify TXT and CNAME records.

    DNS records authorize the email provider to deliver email on behalf of your domain. Improper DNS configuration can cause email delivery failures or emails to be marked as spam.

    Set up your email domain with your email provider

    After you've created your custom email domain, configure it with your email provider. This typically involves adding DNS records to authorize the provider to send email on behalf of your domain.

    The process for adding DNS records to your email provider can vary depending on the provider. Refer to your provider's documentation for specific instructions.

    Set up DNS records for your email domain

    If you send email using a default domain provided by your email provider (such as mycompany.google.com), the provider often manages these records automatically. However, when using a custom domain (such as notifications.mycompany.com), you must manually authorize the provider in your DNS settings.

    Set up the following DNS records to authorize your email provider to send email on behalf of your custom email domain:

    • Sender Policy Framework (SPF)
    • DomainKeys Identified Mail (DKIM)
    • Domain-based Message Authentication, Reporting and Conformance (DMARC)

    Note: Major email service providers, such as Google and Yahoo, require DMARC for bulk senders. Without a DMARC record, emails may be rejected and cause delivery failures.

    See Set up additional DNS records.

    Configure the OAuth 2.0 settings for your custom email provider

    At this point, you’ve created and verified a custom email domain. And you’ve configured your email provider to send email on behalf of that domain. Now, you can configure the OAuth 2.0 connection between your org and your email provider.

    The following examples (Microsoft and Google) are based on the two OAuth 2.0 flows for SMTP authentication. The steps are meant to provide a baseline for your configuration. Refer to your email provider's documentation for information about their specific OAuth 2.0 implementation.

    This table highlights common components of each flow and how they're used.

    Component Client credentials flow JWT bearer token flow
    Authentication type This flow uses a shared secret. This flow uses asymmetric cryptography (private/public key).
    Email provider app This flow requires an OAuth 2.0 client app that generates a client ID . This flow requires an OAuth 2.0 client app that generates a client ID.
    Credential This flow uses a client secret as a credential. This flow uses a private key (JSON/certificate) as a credential.
    Permission This flow uses a scope that grants permission to access an email server. This flow uses a scope that grants permission to access an email server.
    Sender identity This flow uses a designated user account. This flow uses an impersonated user account, using the sub claim.

    Microsoft Exchange Online SMTP example

    This example uses the OAuth 2.0 client credentials flow to connect your org to Microsoft Exchange Online SMTP. The following steps summarize the required configuration and provide links to more detailed instructions and information when needed.

    For more information about OAuth 2.0 for Microsoft SMTP, see:

    Create a client ID and client secret

    1. Go to Microsoft Azure (opens new window) and create an App registration. This is your OAuth 2.0 app.
    2. Name the app "Okta SMTP app" and set it as a "Single tenant". See Register an application (opens new window).
    3. Create a client secret for the OAuth 2.0 app. See Add a credential to your application (opens new window).

    Note: Ensure that you follow the steps to create a client secret and not a certificate.

    1. Name the client secret and set an expiration date.
    2. Create the client secret, and then copy the value.
    3. Go to your app's overview page.
    4. Copy the Application (client ID) and the Directory (tenant ID) values from the app overview page.
    5. In Microsoft Azure (opens new window), go to Enterprise applications.
    6. Find your newly created app and open it.
    7. In the app's overview page, copy the Object ID to use it in a later step.

    Grant an email sending scope

    1. In your Microsoft OAuth 2.0 app, add an API permission.
      1. Refer to the steps and the UI navigation in Add the POP, IMAP, or SMTP permissions to your Microsoft Entra application (opens new window).
      2. You must navigate to API Permissions and then follow the steps to add the email sending permission.
    2. Check the SMTP.SendAsApp permission. This enables the OAuth 2.0 app to send email as any user in the organization.
    3. After you've confirmed the permission, ensure that you click Grant admin consent for [your app] to activate the permission.

    Enable your app to send email as a specific user

    1. Go to https://admin.microsoft.com/ and sign in with your admin account.
    2. Open Users > Active users.
    3. Select the user that you want your app to send emails from. The Username is used as the "From" address in Okta system emails and is also used to authenticate the SMTP connection.
    4. In the user's Mail settings, enable SMTP authentication for the user. See Use the Microsoft 365 admin center to enable or disable SMTP AUTH on specific mailboxes (opens new window).

    Connect your app registration to Microsoft Exchange Online

    Creating the app in Microsoft Azure gives it an identity, but it doesn't automatically grant it access to your email system.

    Run these commands to connect the app to Exchange Online and explicitly grant it permission to access the specific mailbox that you want to use. Without this step, the app exists but is locked out of the email account.

    1. Install PowerShell (opens new window).

    2. Open a PowerShell terminal and install the Exchange Online Management module (opens new window) with the following command:

      Install-Module -Name ExchangeOnlineManagement

    3. Then, run the following command to sign in to Microsoft.

      Connect-ExchangeOnline

    4. Connect to Exchange Online using the following command. Replace the placeholders with your values.

    • Client ID: The Application (client ID) value from your app registration.

    • Enterprise Object ID: The Object ID value from your app registration.

    • Sender Email: The email address of the user that you designated in the previous step.

    • App-Name: The display name of your app in Exchange Online.

       # $ClientID = "{YourClientID}"
 # $EnterpriseObjectID = "{YourEnterpriseObjectID}"
 # $SenderEmail = "sender@example.com"

 # Register the app in Exchange Online
 New-ServicePrincipal -AppId $ClientID -ServiceId $EnterpriseObjectID -DisplayName "{App-Name}"

 # Grant permissions
 Add-MailboxPermission -Identity $SenderEmail -User $EnterpriseObjectID -AccessRights FullAccess

    Configure your org's SMTP settings

    After you've created your OAuth 2.0 app registration and granted the necessary permissions, you can connect your org to Microsoft Exchange Online SMTP.

    To connect your org in the Admin Console, follow the steps in Configure a custom email provider (opens new window) and use the OAuth 2.0 client credentials flow settings.

    • Client ID: The Application (client ID) value from your app registration.
    • Client secret: The client secret value that you created for your app registration.
    • Scope: https://outlook.office.com/.default
    • Token endpoint URL: https://login.microsoftonline.com/{TenantID}/oauth2/v2.0/token and replace {TenantID} with your Directory (tenant ID) value.
    • Token endpoint authentication method: Either CLIENT_SECRET_POST or CLIENT_SECRET_BASIC is acceptable for Microsoft Exchange Online SMTP configurations.
    • Hostname: smtp.office365.com
    • Port: 587
    • Username: The email address of the user that you designated in the previous step.

    Google Workspace SMTP example

    This example uses the OAuth 2.0 JWT bearer token flow to connect your org to Google Workspace SMTP. The following steps summarize the required configuration and provide links to more detailed instructions and information when needed.

    For more information about OAuth 2.0 for Google Workspace SMTP, see:

    Create a service account and generate key pair

    1. Go to the Google Cloud Console (opens new window).
    2. Create a project. This is your OAuth 2.0 app.
    3. Enable the Gmail API for your project. See Enabling an API (opens new window) and Enable the Gmail API (opens new window).
    4. Go to APIs & Services > Credentials.
    5. Create a Service Account. See Creating and managing service accounts (opens new window).
    6. Copy the client ID for the service account.
    7. Create a key for the service account. See Create a service account key (opens new window).
    8. Select JSON as the key type.
    9. Click Create to download the JSON key file. Keep this file secure, as it contains your private key.

    Grant email sending scope

    1. Sign in to the Google Admin Console (opens new window) with your admin account.
    2. Go to Domain-wide Delegation. See Set up domain-wide delegation for a client (opens new window)
    3. Enter the service account's client ID.
    4. In the OAuth scopes field, enter https://mail.google.com/.
    5. Click Authorize.

    You have now granted the service account permission to send email on behalf of users in your Google Workspace domain.

    Configure your org's SMTP settings

    After you've created your service account and granted the necessary permissions, you can connect your org to Google Workspace SMTP. Use the information in the private key in the JSON file to configure the SMTP settings in your org.

    Open the JSON file that you downloaded previously. It contains the private key and other necessary information in the following format:

    {
  "type": "service_account",
  "project_id": "{ProjectName}",
  "private_key_id": "XXXXXXXXXXXXXXXXX",
  "private_key": "-----BEGIN PRIVATE KEY-----\\nXXXXXXXXXXX==\n-----END PRIVATE KEY-----\n",
  "client_email": "{username}@{project_id}.iam.gserviceaccount.com",
  "client_id": "{ClientId}",
  "auth_uri": "https://accounts.google.com/o/oauth2/auth",
  "token_uri": "https://oauth2.googleapis.com/token",
  "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
  "client_x509_cert_url": "https://www.googleapis.com/robot/v1/metadata/x509/{username}@{project_id}.iam.gserviceaccount.com",
  "universe_domain": "googleapis.com"
}

    Use these values to connect your org in the Admin Console. Follow the steps in Configure a custom email provider (opens new window) and use the OAuth 2.0 JWT bearer token flow settings.

    • Client ID: The client_id value.
    • Token endpoint URL: The token_uri value.
    • Signing algorithm: RS256
    • Key ID: The private_key_id value.
    • Issuer: The client_email value.
    • Subject: The email address of a user in your Google Workspace domain.
    • Audience: The token_uri value.
    • Private key: The private_key value.
    • Scope: https://mail.google.com/
    • Private key: The private_key value from the JSON file. Ensure that you preserve the line breaks (\n) in the key.
    • Hostname: smtp.gmail.com
    • Port: 587
    • Username: The same email address used in the Subject field.

    Next steps

    You've now configured your org to use a custom email provider with OAuth 2.0 authentication. Customize and then test your email templates to ensure that system-generated emails are sent correctly using your custom email provider. See Customize email notifications.

    See also

    Edit This Page On GitHub