Configuring bearer token authentication for SMTP

By default, the PingDirectory server authenticates to SMTP servers using a username and password. You can instead configure the server to authenticate using a bearer token.

Why use bearer token authentication?

Storing a static password in the server configuration creates a long-term security risk. The credential remains in the configuration indefinitely, and if it is ever compromised, an attacker retains access to the mail system until an administrator manually resets it. Modern enterprise mail platforms, including Microsoft Exchange Online, are actively moving away from basic authentication and may reject static passwords entirely.

Bearer token authentication reduces risk by replacing the static password with access tokens. Tokens are short-lived, which limits the exposure if one is ever intercepted. Token renewal is automatic, so the system maintains its own access with minimal administrator intervention.

Authentication methods

The server supports two authentication methods:

Client credentials bearer token: The server obtains a short-lived access token from an authorization server using the OAuth 2.0 client credentials flow. When the token expires or the SMTP server returns a 401 Unauthorized response, the server automatically requests a new token. This is the recommended method for production environments.
Static bearer token: The server uses a fixed token value stored in the configuration. This method is intended for testing and troubleshooting only. Use the oauth-token-passphrase-provider property to provide the token value when creating the HTTP authorization method.

When bearer token authentication is configured, enter the sender email address in the user-name property of the SMTP external server. Don’t set the password or passphrase-provider properties, because providing a password prevents the connection from working.

Before you begin

Your SMTP server must be configured to accept OAuth 2.0 bearer token authentication. Consult your mail server provider’s documentation for setup instructions.

Steps

Create a passphrase provider to store the client secret. Learn more in Configure passphrase providers.

Create the HTTP authorization method.

Example:

$ bin/dsconfig create-http-authorization-method \
     --method-name "SMTP Bearer Token" \
     --type client-credentials-bearer-token \
     --set enabled:true \
     --set oauth-server-token-endpoint-url:https://idp.example.com/oauth2/token \
     --set oauth-client-id:your-client-id \
     --set "oauth-client-secret-passphrase-provider:SMTP Client Secret" \
     --set "requested-scope:https://outlook.office365.com/.default"

Replace the token endpoint URL, client ID, passphrase provider name, and scope with values from your identity provider.

During testing, set maximum-token-lifetime to a short duration such as 1 s to force the server to request a new token on every attempt. Remove this setting in production.