News
Abstract
IBM i Simple Mail Transfer Protocol (SMTP) extends authentication capabilities to include OAuth 2.0 tokens with Gmail and Office 365.
Content
You are in: IBM i Technology Updates > IBM i Security > IBM i SMTP support for OAuth 2.0
- Open-standard protocol that uses access tokens rather than username and password
- The access token grants scoped and time-limited permissions to access user data on another service
- Implemented as Service Account with Domain-Wide Delegation
- A single service account impersonates users within an organizational domain, requiring administrative setup and domain-wide delegation permissions
- Supports Gmail (Google Workspace) and Office 365 (Microsoft 365) providers
- Configuration through Change SMTP Attributes (CHGSMTPA) and Navigator for i
- Administrator performs out-of-band setup with the provider’s cloud instance
- Administrator creates an IFS file with provider‑specific OAuth 2.0 authentication information in JSON format
- SMTP uses the JSON file to obtain information used to connect to provider and obtain tokens
- Send email is the same after initial configuration
This feature is available by installing PTFs:
SJ09506
SJ09647 - Navigator
SJ09788
SJ09652 - Navigator
SJ09772
SJ09653 - Navigator
Learn more on setting up Office365 here.
Learn more on setting up Gmail here.
Learn more about Navigator here: Navigator SMTP OAUTH Configuration Documentation
1. Microsoft Entra ID — App Registration
portal.azure.com → Microsoft Entra ID → App registrations → New registration
• Name: ibmi-smtp
• Supported account types: Single tenant
• Click Register
Note down:
• Application (client) ID
• Directory (tenant) ID
2. Create Client Secret
App registration → Certificates & secrets → New client secret
• Description: ibmi-smtp-secret
• Expiry: 24 months
• Click Add — copy the Value immediately
3. API Permissions
App registration → API permissions → Add a permission
• Microsoft Graph → Application permissions:
• Mail.Send
• Mail.ReadWrite
• Click Grant admin consent
• ⚠️ Do NOT add SMTP.SendAsApp from Office 365 Exchange Online
4. Exchange Online — Enable SMTP AUTH
admin.exchange.microsoft.com → Recipients → Mailboxes → select sender mailbox → Mail flow settings
• Authenticated SMTP: Enable
admin.exchange.microsoft.com → Settings → Mail flow
• Turn off SMTP AUTH protocol: must be unchecked
5. Assign Exchange Online License
admin.microsoft.com → Users → Active users → select sender user → Licenses and apps
• Check Microsoft 365 Business Standard (or any plan with Exchange Online)
• Click Save
6. IBM i — DCM Certificate Setup
IBM i → STRMNG → Digital Certificate Manager
Application ID: QIBM_QTMS_SMTP_CLIENT
Required CA Certificates (import into *SYSTEM store):
DigiCert Global Root G2
GTS Root R1
GTS Root R4
How to get certificates:
Download from: https://www.digicert.com/kb/digicert-root-certificates.htm
Import via DCM: DCM → Manage Certificates → Import Certificate → CA Certificate
• Import each certificate above
• Certificate type: *CA
Assign to Application: DCM → Manage Applications → Update Certificate Assignment
• Application: QIBM_QTMS_SMTP_CLIENT
• Assign the imported CA certificates
Verify: DCM → Manage Applications → Validate Application
• Should show: No errors
7. RBAC Setup — PowerShell Required ⚠️
powershell
Connect-ExchangeOnline
New-ServicePrincipal -AppId "<client_id>" -ObjectId "<service_principal_object_id>" -DisplayName "ibmi-smtp"
New-DistributionGroup -Name "IBMi-SMTP-Senders" -Type Security
Add-DistributionGroupMember -Identity "IBMi-SMTP-Senders" -Member sender@domain.com
Note: <service_principal_object_id> is the Service Principal's Object ID (Entra ID → Enterprise applications → ibmi-smtp → Object ID) — not the App registration's Object ID. To fetch it directly in PowerShell:
powershell
(Get-MgServicePrincipal -Filter"appId eq '<client_id>'").Id
Get the full DN of the distribution group (needed for the next command):
powershell
Get-DistributionGroup -Identity "IBMi-SMTP-Senders"|Format-List DistinguishedNameCreate the scope and role assignment using that DN:
powershell
New-ManagementScope -Name "RBAC Scope" -RecipientRestrictionFilter "MemberOfGroup -eq '<full DN>'"
New-ManagementRoleAssignment -Name "IBMi-SMTP-RBAC" -Role "Application SMTP.SendAsApp" -App "<client_id>" -CustomResourceScope "RBAC Scope
8. Verify RBAC
powershell
Test-ApplicationAccessPolicy -Identity "sender@domain.com" -AppId "<client_id>"
Expected: AccessCheckResult: Granted
9. IBM i SMTP Configuration
Credentials JSON (/oauth/office365.json) — sample for referral:
office365 json
{
"type": "microsoft_app",
"tenant_id": "<tenant_id>",
"client_id": "<client_id>",
"client_secret": "<client_secret>",
"scope": "https://outlook.office365.com/.default",
"domain": "yourdomain.onmicrosoft.com"
}
Note: The domain field is required. It must match the authoritative domain verified in Exchange Online and should line up with the ALIASDMN value in the client setup below. If it's missing or doesn't match, SMTP won't obtain a usable token and mail won't relay — even when every other field is correct.
Client setup:
ENDTCPSVR *SMTP
CHGSMTPA FWDHUBSVR('outlook.office365.com') AUTOSTART(*YES) ALIASDMN('your_microsoft_domain')
ADDUSRSMTP USRPRF(your_user_profile) ALIAS(your_microsoft_account_name) DOMAIN(001 *DFT) ORIGINATOR(*NONE)
ADDENVVAR ENVVAR(QIBM_SMTP_SERVER_PORT) VALUE('587') LEVEL(*SYS)
ADDENVVAR ENVVAR(QIBM_SMTP_MAILHUB_PORT) VALUE('587') LEVEL(*SYS)
ADDENVVAR ENVVAR(OAUTH_LOG_LEVEL) VALUE('INFO') LEVEL(*SYS)
ADDENVVAR ENVVAR(OAUTH_LOG_DEST) VALUE('FILE') LEVEL(*SYS)
ADDENVVAR ENVVAR(OAUTH_LOG_FILE) VALUE('/tmp/oauth.log') LEVEL(*SYS) <-- only for debug purpose
ADDENVVAR ENVVAR(QIBM_SMTP_RLY_TLS_FIRST) VALUE(YES_STARTTLS) LEVEL(*SYS)
STRTCPSVR *SMTP
Enable the credentials:
CHGSMTPA OAUTH('/oauth/office365.json' *ENABLE)
Send email:
SNDSMTPEMM RCP(('some_account@somewhere.com' *PRI)) SUBJECT('Test Subject') NOTE('Test message body')
Verify the environment variables anytime with:
WRKENVVAR LEVEL(*SYS)
Key Requirements Summary
Requirement | Detail |
Exchange Online license | Required for sender mailbox |
Authoritative domain | Must be verified in Exchange |
No SMTP.SendAsApp in token | RBAC handles authorization |
Scope | https://outlook.office365.com/.default |
DCM certificates | DigiCert Root G2 + Microsoft TLS CA |
IBM i SMTP AUTH | QIBM_SMTP_RLY_TLS_FIRST=YES_STARTTLS |
1. Google Cloud Console — Project Setup
console.cloud.google.com → New Project
• Name: ibmi-smtp
• Click Create
• Select the new project
2. Enable Gmail API
APIs & Services → Library → search "Gmail API" → Enable
3. Create Service Account
APIs & Services → Credentials → Create Credentials → Service Account
• Name: ibmi-smtp-service
• Click Create and Continue
• Role: Owner (or Editor)
• Click Done
Create Key:
• Click on the service account → Keys tab
• Add Key → Create new key → JSON
• Download the JSON file — this is your credential file
Note down from JSON:
• client_email
• private_key_id
4. Google Workspace Admin — Domain-Wide Delegation
admin.google.com → Security → Access and data control → API controls → Manage Domain Wide Delegation
• Click Add new
• Client ID: paste the client_id from service account JSON
• OAuth Scopes:
https://mail.google.com/
• Click Authorize
5. Google Workspace Admin — Enable SMTP
admin.google.com → Apps → Google Workspace → Gmail → Settings for Gmail
• SMTP relay service: Enable
• Hosts: Add smtp.gmail.com
6. IBM i — DCM Certificate Setup
IBM i → Digital Certificate Manager
Application ID: QIBM_QTMS_SMTP_CLIENT
Required CA Certificates:
DigiCert Global Root G2
GTS Root R1
GTS Root R4
How to get certificates:
Download from: https://pki.goog/repository/
Import via DCM: DCM → Manage Certificates → Import Certificate → CA Certificate
• Import each certificate above
• Certificate type: *CA
Assign to Application: DCM → Manage Applications → Update Certificate Assignment
• Application: QIBM_QTMS_SMTP_CLIENT
• Assign the imported CA certificates
Verify: DCM → Manage Applications → Validate Application
• Should show: No errors
Another way to verify the certificates.
QSH CMD('/QOpenSys/usr/bin/openssl s_client -connect smtp.gmail.com:587 -starttls smtp -servername smtp.gmail.com > /tmp/ssl_test.txt 2>&1')
Then browse /tmp/ssl_test.txt — This will show the exact chain being offered.
In DCM:
Manage Applications → Application Definitions → Client → find SMTP client
Confirm it points to the store containing the GTS (Google Trust Services) certs.
7. IBM i SMTP Configuration
Credentials JSON (/oauth/gmail.json) — sample gmail json file:
gmail json file
{
"type": "service_account",
"project_id": "<project_id>",
"private_key_id": "<private_key_id>",
"private_key": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n",
"client_email": "ibmi-smtp-service@<project>.iam.gserviceaccount.com",
"client_id": "<client_id>",
"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/...",
"universe_domain": "googleapis.com",
"domain": "yourdomain.com"
}
Note: The downloaded service account JSON file does not include a domain entry — you must add it yourself. Set its value to your Google Workspace domain (the one configured for Domain-Wide Delegation); it should also line up with the ALIASDMN value in the client setup below. Without this manually added domain field, SMTP won't obtain a usable token and mail won't relay — even when every other field is correct.
Client setup:
ENDTCPSVR *SMTP
CHGSMTPA FWDHUBSVR('smtp.gmail.com') AUTOSTART(*YES) ALIASDMN('your_gmail_domain')
ADDUSRSMTP USRPRF(your_user_profile) ALIAS(your_gmail_account_name) DOMAIN(001 *DFT) ORIGINATOR(*NONE)
ADDENVVAR ENVVAR(QIBM_SMTP_SERVER_PORT) VALUE('587') LEVEL(*SYS)
ADDENVVAR ENVVAR(QIBM_SMTP_MAILHUB_PORT) VALUE('587') LEVEL(*SYS)
ADDENVVAR ENVVAR(OAUTH_LOG_LEVEL) VALUE('INFO') LEVEL(*SYS)
ADDENVVAR ENVVAR(OAUTH_LOG_DEST) VALUE('FILE') LEVEL(*SYS)
ADDENVVAR ENVVAR(OAUTH_LOG_FILE) VALUE('/tmp/oauth.log') LEVEL(*SYS) <-- only for debug purpose
ADDENVVAR ENVVAR(QIBM_SMTP_RLY_TLS_FIRST) VALUE(YES_STARTTLS) LEVEL(*SYS)
STRTCPSVR *SMTP
Enable the credentials:
CHGSMTPA OAUTH('/oauth/gmail.json' *ENABLE)
Send email:
SNDSMTPEMM RCP(('some_account@somewhere.com' *PRI)) SUBJECT('Test Subject') NOTE('Test message body')
Verify the environment variables anytime with:
WRKENVVAR LEVEL(*SYS)
Key Requirements Summary
Requirement | Detail |
Google Workspace account | Required (not free Gmail) |
Domain-Wide Delegation | Required for service account |
Gmail API enabled | Required in Google Cloud Console |
Scope | https://mail.google.com/ |
DCM certificates | Google Trust Services Root CA |
IBM i SMTP AUTH | QIBM_SMTP_RLY_TLS_FIRST=YES_STARTTLS |
Sender mailbox | Must be Google Workspace user |
Was this topic helpful?
Document Information
Modified date:
18 June 2026
UID
ibm17267763