This guide provides step-by-step instructions for configuring a "Bring Your Own (BYO) SMTP" server using OAuth 2.0 authentication. Okta recommends OAuth 2.0 over basic authentication to ensure higher security and maintain compatibility, as many email providers are phasing out support for legacy connection methods.
- Configuring Google/Gmail as a custom email provider using OAuth 2.0
- Okta Identity Engine (OIE)
- Okta Classic Engine
- Configuring Bring Your Own (BYO) SMTP Server with OAuth2
Configuring BYO SMTP for Gmail with OAuth 2.0
Okta recommends using OAuth 2.0 (JWT Bearer Token Flow) over basic authentication for higher security and long-term compatibility.
Phase 1: Google Cloud Console Configuration
Before heading to Okta, ensure the Google environment is prepared:
-
Enable Gmail API:
- In the Google Cloud Console, navigate to APIs & Services > Library.
- Search for "Gmail API" and ensure it is Enabled.
-
Service Account & JSON Key:
- Go to APIs & Services > Credentials.
- Select a Service Account (or create one) and copy the
Unique ID. This will be needed for Domain-Wide Delegation. - Go to the Keys tab > Add Key > Create new key.
- Select JSON and click Create. Save this file securely; it contains the private key.
-
Domain-Wide Delegation:
- Log in to the Google Admin Console.
- Navigate to Security > Access and data control > API controls.
- On the next page, click on Manage Domain Wide Delegation > Add new.
- Client ID: Paste the Unique ID copied in step 2.
- OAuth Scopes: Enter
https://mail.google.com/. - Click AUTHORIZE.
Phase 2: Enable the Feature in Okta
The OAuth option for email providers is often behind an Early Access (EA) flag.
- In the Okta Admin Console, go to Settings > Features.
- Locate and enable OAuth 2.0 support for custom email providers.
Phase 3: Connect Okta to Gmail
Navigate to Customizations > Email Provider and click Add Custom Email Provider.
| Field | Value / Action |
| Connection Type | Select > OAuth 2.0 - JWT Bearer token flow |
| Client ID | Use the Unique ID saved earlier, client_id from the JSON file |
| Token endpoint URL |
The |
| Signing algorithm | RS256 |
| Key ID | The private_key_id from the JSON file |
| Issuer |
The This will be the Servica Account Email |
| Subject |
A valid Google Workspace user email (the "sender" account). This is not the service account JSON email |
| Audience |
The |
| Scopes | https://mail.google.com/ |
| Private Key | Paste the entire private_key string from the JSON file. |
| Hostname | smtp.gmail.com |
| Port | 587 |
| Username | Same as the Subject email address. |
After successful configuration, a search in the system logs for "Email Sent" events using the below search query will display these details in the event's DebugData:
eventType eq "system.email.delivery"
