Use your own email provider

Use an external email provider if you want to send Okta notification emails through a third-party provider rather than an Okta-managed SMTP server. Adding a custom email provider lets you satisfy business and regulatory requirements:

  • Fulfill data residency requirements by choosing an email provider that stores data in a certain geographical location.
  • Control the IP addresses used for your emails.
  • Get detailed metrics and insights into the emails that you send, like email delivery and usage status.

Okta makes multiple attempts to deliver messages through your custom email provider. If the first attempt fails, Okta queues the message and reattempts the delivery later. If the second attempt fails, the message is requeued with longer delays. When the maximum limit for retries is exceeded, a FAILURE delivery event is recorded in the System Log. In these cases, the message delivery doesn't fall back to the Okta default email service. A SUCCESS delivery event is recorded in the System Log when the delivery is successful.

Connection types

Okta supports custom email providers with basic SMTP and OAuth 2.0 authentication.

Basic SMTP authentication uses a username and password to authorize requests to an SMTP server. Because admin credentials are transmitted and stored in these requests, some email providers (including Microsoft and Google Workspace) are deprecating support for basic SMTP authentication.

Okta offers two OAuth 2.0 authentication choices for orgs using these custom email providers: a client credentials flow (which supports Microsoft's requirements) and a JWT bearer token flow (which supports Google's).

Before you begin

  • Set up your external email provider. See Custom SMTP.

  • Gather the following details of your provider's SMTP server:
    • Host: Hostname or IP address of your SMTP server. For example, your.smtp.host.com.
    • Port: Port used by your SMTP server. By default, Okta supports 465, 587, and 2587. If your org uses a non-standard port, contact Okta Support for assistance.
    • Username: Your SMTP username.
    • SMTP password: Your SMTP password or Google app password.

Add a custom email provider using OAuth 2.0

Early Access release. See Enable self-service features.

You can configure OAuth 2.0 authentication with client credentials or JWT bearer tokens.

Client credentials

This option supports orgs that currently use Microsoft for basic SMTP authentication. After you create an OAuth 2.0 provider with client credentials, the client secret isn't returned in API responses.

  1. In the Admin Console, go to CustomizationsEmail provider.
  2. Click Add custom email provider.
  3. In the Connection type dropdown menu, select OAuth 2.0 - client credentials flow.
  4. Enter the details of your OAuth 2.0 client credentials flow:
    • Client ID
    • Client secret
    • Scope
    • Token endpoint URL
    • Token endpoint authentication method
  5. Enter the details of your SMTP: Host, Port, and Username.
  6. Click Save. The new provider is added.
  7. Send a test email to ensure that it works correctly.
  8. Toggle on Use custom email provider.

Your OAuth 2.0 configuration stops working if the client secret expires. Okta records this as an event in the System Log but doesn't prompt you to update. Remember to generate a new one and update your configuration before this date.

JWT bearer tokens

This option supports orgs that currently use Google Workspace for basic SMTP authentication. After you create an OAuth 2.0 provider with client credentials, the private key won't be returned in API responses.

  1. In the Admin Console, go to CustomizationsEmail provider.
  2. Click Add custom email provider.
  3. In the Connection type dropdown menu, select OAuth 2.0 - JWT bearer tokens flow.
  4. Enter the details of your OAuth 2.0 client credentials flow:
    • Client ID
    • Token endpoint URL
    • Signing algorithm
    • Key ID (kid)
    • Issuer (iss)
    • Subject (sub)
    • Audience (aud)
    • Scope
    • Private key
  5. Enter the details of your SMTP: Host, Port, and Username.
  6. Click Save. The new provider is added.
  7. Send a test email to ensure that it works correctly.
  8. Toggle on Use custom email provider.

Your OAuth 2.0 configuration stops working if the private key expires. Okta records this as an event in the System Log but doesn't prompt you to update. Remember to generate a new one and update your configuration before this date.

Add a custom email provider with basic SMTP authentication

Some email providers (including Microsoft and Google Workspace) are deprecating support for basic SMTP authentication. Okta recommends using OAuth 2.0 authentication with your custom email provider if possible.

Add a custom email provider (non-Google Workspace)

  1. In the Admin Console, go to CustomizationsEmail provider.
  2. Click Add custom email provider.
  3. In the Connection type dropdown menu, select Basic authentication.
  4. Enter the details of your SMTP: Host, Port, Username, and SMTP password.
  5. Click Save. The new provider is added.
  6. Send a test email to ensure that it works correctly.
  7. Toggle on Use custom email provider.

Add Google Workspace as a custom email provider

Google doesn't allow username and password to access its services from external products, like Okta and others. Instead, you generate an app password in Google Workspace, which is a kind of OAuth token, and then use that token as the SMTP password in Okta.

  1. Create an app password in Google Workspace. See Google's support article Create & use app passwords.
  2. Copy the app password and store it in a secure location.
  3. In the Okta Admin Console, go to CustomizationsEmail provider.
  4. Click Add custom email provider.
  5. In the Connection type dropdown menu, select Basic authentication.
  6. Enter the details of your SMTP: Host, Port, and Username.
  7. Paste the app password in the SMTP password field.
  8. Click Save.
  9. Send a test email to ensure that it works correctly.
  10. Toggle on Use custom email provider.

See Google's support article Transition from less secure apps to OAuth.

Send a test email

Send a test email to confirm that your email provider has been configured correctly.

  1. In the Admin Console, go to CustomizationsEmail provider.
  2. Click Send test email under the SMTP server.
  3. Enter the From address. Use a valid, working email address. The SMTP server verifies it as part of this test.
  4. Enter the To address. This is the address where you're sending the test email. Ensure that you have access to this email address in an email client.
  5. Click Send test email.
  6. A notification appears when the email is sent.
  7. In an email client, access the To address and verify that the test email arrived.

Add a custom email domain to a brand

Add the custom email domain to each of your brands.

  1. In the Admin Console, go to Brands.
  2. Click the brand where you want to add the custom email domain.
  3. Go to BrandDomainsEmail domain.
  4. Click Add email domain next to the default okta.com domain.
  5. Add the email address and name of the email sender. Your users see this information in their inbox.
  6. Click Next.
  7. Configure an email provider if you haven't already. See the previous tasks.
  8. Click Verify. The email provider is added to the brand and appears in the list under DomainsEmail domain.
  9. Repeat for each brand.

Remove a custom email provider

Remove the custom email provider for your org. If you remove the provider, it's no longer used by any brands in the org. Emails are then sent from the default okta.com email provider.

  1. In the Admin Console, go to CustomizationsEmail provider.
  2. Click the Delete icon next to the email provider. The Remove email provider page appears.
  3. Click Remove email provider.

Edit a custom email provider

  1. In the Admin Console, go to CustomizationsEmail provider.
  2. Click the Edit icon next to the email provider. The Edit custom email provider page appears.
  3. Edit the email provider information.
  4. Click Save.

Related topics

Branding

Configure a custom domain