Email provider

PingOne Advanced Identity Cloud uses email provider configuration to support email-dependent end-user journeys. For example, registration and password reset end-user journeys usually include an email component.

By default, Advanced Identity Cloud configures the email provider with default values to connect to a built-in SMTP server. This lets you quickly create and test email-dependent journeys in your tenant development environment using the ready-to-use email templates. No rate limiting is applied to password reset emails or any emails sent by the built-in SMTP server. This means an attacker can potentially spam a known user account with an infinite number of emails, filling that user’s inbox. In the case of password reset, the spam attack can obscure an actual password reset attempt.

In your staging and production tenant environments, you must update the email provider configuration with values to connect to something other than the built-in SMTP server.

Additionally, the built-in SMTP server does not support:

OTP Email Sender nodes in password journeys.
Non-ASCII characters in email addresses (international email addresses).

Setup process

Email provider configuration changes made in one realm are applied to both realms.

Create a new email template.
In your tenant development environment, create and test a journey that uses an email node. By default, the email provider uses the built-in SMTP server to test the email node.
When you’re satisfied with your test results:
1. Edit the email provider configuration to use your own external email provider.
2. Verify that your email templates work with the external provider.
Promote your configuration changes to your tenant staging environment.
Optionally, you can revert the email provider to use the built-in SMTP server for testing purposes. Be sure to reconfigure the email provider to use your own external service before promoting configuration changes to your tenant staging environment.

Do not use the email provider with the built-in SMTP server in a tenant production environment. Advanced Identity Cloud provides this ready-to-use server for testing purposes only.

Email service configuration types

Advanced Identity Cloud supports two email service configuration types:

SMTP - Email service that uses the Simple Mail Transfer Protocol. Can be configured using the UI or API.
MS Graph API - Email service that uses the MS Graph API sendMail endpoint. Can only be configured using the API.

International email addresses

To use international email addresses, you must:

Use SMTP as the provider type.
The SMTP provider must support international email addresses.
Configure mail.mime.allowutf8=true using the REST API or the UI.

Learn more in smtpProperties sub-properties.

MS Graph API requirements

Use of the MS Graph API email client requires a properly configured Microsoft Azure tenant. The steps for configuring an Azure tenant should be used as an outline, as the specific options, menus, and features may have changed.

Microsoft Sandbox

If you need a sandbox for testing only, check out the Microsoft developer sandbox subscription. Although the sandbox accepts sendMail requests, the Microsoft Exchange service prevents messages from being delivered. The messages do show up in the sender’s "sent" box, which should be sufficient for manual testing purposes.

Configure Azure for MS Graph API email client

Navigate to Azure Active Directory | App registrations.
Create the Advanced Identity Cloud client application:
1. From the menu bar, click + New Registration.
2. On the Register an application page, enter the application Name, such as my-email-client.
3. For Supported account types, select the applicable option for your organization.
4. Click Register.
5. On the my-email-client page, from the main Essentials area, record the Application (client) ID.
  
  This is the value for clientId in the auth settings of the email configuration. Learn more in oauth2 properties.
Add a client secret:
1. On the my-email-client page, in the main Essentials area, click Add a certificate or secret.
  
  Show Me
2. On the Certificates & secrets page, select the Client secrets tab, and click + New client secret.
  
  Show Me
3. In the Add a client secret window, enter the details, and click Add.
4. Copy the Value and Secret ID to a secure place before leaving the Certificates & secrets page.
  
  Use the secret Value for clientSecret in the auth settings of the email configuration. Learn more in oauth2 properties.
Add API permissions:
1. From the side menu, click API permissions.
2. On the API permissions page, click + Add a permission.
3. In the Request API permissions windows, select the Microsft APIs tab, and click Microsoft Graph.
4. In the What type of permissions… area, click Application permissions.
5. In the Select permissions search bar, type send.
6. Expand the Mail node, and select Mail.Send.
7. Click Add permissions.
  
  Show Me

Configure the email provider

Email provider configuration changes made in one realm are applied to both realms.

In your staging and production tenant environments, configure the email provider to use your own external service:

For SMTP, you can use the UI or API.
For MS Graph API, you can only use the API.

For the complete list of configuration options, learn more in Email provider configuration properties.
For sample email configurations, learn more in Sample email configuration.

Using the UI

In the Advanced Identity Cloud admin UI, go to Email > Provider.
On the Email Provider page, enable Use my own email provider.

Enter details in the following fields:

From Address

Email address of the organization or individual sending the email.

Example: mycompany@example.com.

Not set by default.

Although from is optional in the email configuration, the email service requires this property to send email. If you do not specify a from address in the email configuration, you must provide one in another way, for example:

From an email template.
As a parameter in the email service request (from or _from).

From Name

Name of sending organization.

Host

Hostname or IP address of your SMTP server.

When no hostname is specified, Advanced Identity Cloud uses the built-in SMTP server.

Port

Port number of your SMTP server.

Many SMTP servers require the use of a secure port such as 465 or 587. Many ISPs flag email from port 25 as spam.

Default value is 587.

Username

Username for your SMTP server account.

Password

Password for your SMTP server account.

Click Show advanced settings, and edit the options and fields:

Socket Connection Timeout (ms)

Elapsed time before Advanced Identity Cloud times out due to unsuccessful socket connection to the SMTP server. A setting of 0 disables this timeout.

The default is 300000 ms (5 minutes).

Socket Write Timeout (ms)

Elapsed time before Advanced Identity Cloud times out because client can’t write to the SMTP server. A setting of 0 disables this timeout.

The default is 300000 (5 minutes).

Socket Timeout (ms)

Elapsed time before Advanced Identity Cloud times out due to inactivity. A setting of 0 disables this timeout.

The default is 300000 (5 minutes).

Use STARTTLS

If enabled, and if the SMTP server supports the STARTTLS command, then Advanced Identity Cloud switches to a TLS-protected connection before issuing any login commands.
If the SMTP server does not support STARTTLS, the connection continues without the use of TLS.

Enabled by default.

Use SSL

If enabled, Advanced Identity Cloud uses SSL to connect to the SMTP server.

Disabled by default.

Allow UTF-8

If enabled, adds support for UTF-8 (Non-ASCII) characters in the local part of email addresses (everything before the @ character).

Disabled by default.

Do not set this property unless your SMTP provider supports UTF-8 characters. Learn more in International email addresses.

To test your configuration, click Send Test Email.
1. In the Send Test Email dialog box, enter your own email address.
2. Click Send.
If the test is successful, you’ll get a test email in your email inbox.
To save the email provider configuration, click Save.

Using the API

You can edit the email service over REST at the openidm/config/external.email endpoint. The following example submits an email configuration over REST:

curl \
--header "Authorization: Bearer <token>" \
--header "Accept-API-Version: resource=1.0" \
--header "Content-Type: application/json" \
--request PUT \
--data '{
    "host" : "smtp.gmail.com",
    "port" : 587,
    "debug" : false,
    "auth" : {
        "enable" : true,
        "username" : "admin",
        "password" : "Passw0rd"
    },
    "from" : "admin@example.com",
    "timeout" : 300000,
    "writetimeout" : 300000,
    "connectiontimeout" : 300000,
    "starttls" : {
        "enable" : true
    },
    "ssl" : {
        "enable" : false
    },
    "smtpProperties" : [
        "mail.smtp.ssl.protocols=TLSv1.2",
        "mail.smtps.ssl.protocols=TLSv1.2",
        "mail.mime.allowutf8=true"
    ],
    "threadPoolSize" : 20
}' \
"https://<tenant-env-fqdn>/openidm/config/external.email"

Sample email configuration

This sample email configuration sets up the email provider:

SMTP
MS Graph API

{
    "host" : "smtp.gmail.com",
    "port" : 587,
    "debug" : false,
    "auth" : {
        "enable" : true,
        "username" : "xxxxxxxx",
        "password" : "xxxxxxxx"
    },
    "timeout" : 300000,
    "writetimeout" : 300000,
    "connectiontimeout" : 300000,
    "starttls" : {
        "enable" : true
    },
    "ssl" : {
        "enable" : false
    },
    "smtpProperties" : [
        "mail.smtp.ssl.protocols=TLSv1.2",
        "mail.smtps.ssl.protocols=TLSv1.2",
        "mail.mime.allowutf8=true"
    ],
    "threadPoolSize" : 20
}

{
    "type" : "msgraph",
    "mailEndpoint" : "https://graph.microsoft.com/v1.0/users/example@myTenant.onmicrosoft.com/sendMail",
    "from" : "example@myTenant.onmicrosoft.com",
    "auth" : {
        "enable" : true,
        "type" : "oauth2",
        "clientId" : "clientId",
        "clientSecret" : "clientSecret",
        "tokenEndpoint" : "https://login.microsoftonline.com/myTenant.onmicrosoft.com/oauth2/v2.0/token",
        "scope" : [
            "https://graph.microsoft.com/.default"
        ]
    },
    "timeout" : 300000,
    "writetimeout" : 300000,
    "connectiontimeout" : 300000,
    "threadPoolSize" : 20
}

Email provider configuration properties

The msgraph type also supports the External REST configuration properties.

Table 1. Properties
Property	Description	Required? / Type Support
`type`	The email service configuration type, `smtp` or `msgraph`. When no type is specified, the default value is `smtp`.	No
`mailEndpoint`	The URI for the MS Graph API `sendMail` endpoint. Typical format: `https://graph.microsoft.com/v1.0/users/{user}@{tenant}.onmicrosoft.com/sendMail`	Yes Only for `msgraph` type.
`host`	The hostname or IP address of the SMTP server.	Yes Only for `smtp` type.
`port`	SMTP server port number, such as 25, 465, or 587. Many SMTP servers require the use of a secure port such as 465 or 587. Many ISPs flag email from port 25 as spam.	Yes Only for `smtp` type.
`debug`	When set to `true`, this option outputs diagnostic messages from the JavaMail library. Debug mode can be useful if you are having difficulty configuring the external email endpoint with your email server.	No Only for `smtp` type.
`from`	Specifies a default From: address which displays when users receive emails from Advanced Identity Cloud. Although `from` is optional in the email configuration, the email service requires this property to send email. If you do not specify a `from` address in the email configuration, you must provide one in another way, for example: From an email template. As a parameter in the email service request (`from` or `_from`).	No
`auth`	Contains authentication detail sub-properties. Learn more about authentication sub-properties.	Yes Required sub-properties vary based on `type`.
`starttls`	If `"enable" : true`, enables the use of the STARTTLS command (if supported by the server) to switch the connection to a TLS-protected connection before issuing any login commands. If the server does not support STARTTLS, the connection continues without the use of TLS.	No Only for `smtp` type.
`ssl`	Set `"enable" : true` to use SSL to connect, and use the SSL port by default.	No Only for `smtp` type.
`smtpProperties`	SMTP options. Learn more about SMTP sub-properties.	No Only for `smtp` type.
`threadPoolSize`	Emails are sent in separate threads managed by a thread pool. This property sets the number of concurrent emails that can be handled at a specific time. The default thread pool size (if none is specified) is `20`.	No
`connectiontimeout`	The socket connection timeout, in milliseconds. The default connection timeout (if none is specified) is `300000` milliseconds, or five minutes. A setting of 0 disables this timeout.	No
`timeout`	The socket read timeout, in milliseconds. The default read timeout (if none is specified) is `300000` milliseconds, or five minutes. A setting of 0 disables this timeout.	No Only for `smtp` type.
`writetimeout`	The socket write timeout, in milliseconds. The default write timeout (if none is specified) is `300000` milliseconds, or five minutes. A setting of 0 disables this timeout.	No Only for `smtp` type.

Table 2. `auth` sub-properties
Property	Description	Required? / Type Support
`enable`	Whether you need login credentials to connect to the server/API. If `"enable" : false,`, you can leave the entries for `"username"` and `"password"` empty: `"enable" : false, "username" : "", "password" : ""`	Yes
`username`	Account used to connect to the server/API.	No
`password`	Password used to connect to the server/API.	No
`type`	Authentication type used to connect to the server/API: `basic`—basic authentication using a username and password. Default value. `oauth2`—OAuth2 authentication. Requires additional `oauth2` properties. The `msgraph` configuration type only supports `oauth2`.	Yes

Table 3. `oauth2` properties
Property	Description	Required? / Type Support
The following properties are only applicable when the `auth/type` is `oauth2`.
`clientId`	clientId used to request an access token from the token endpoint. Obtained during Azure application creation.	Yes
`clientSecret`	clientSecret used to request an access token from the token endpoint. Obtained during Azure application creation.	Yes
`tokenEndpoint`	OAuth2 token endpoint. Typical format: `https://login.microsoftonline.com/{tenant}.onmicrosoft.com/oauth2/v2.0/token`	Yes
`scope`	Requested OAuth2 scopes in a JSON array of strings.	Yes
`scopeDelimiter`	Scope delimiter to use. Defaults to space.	No
`grantType`	The only supported grant type is `client_credentials`.	No

Property Description Required? /
Type Support

mail.smtp.ssl.protocols

The enabled SMTP SSL connection protocols. Protocols are specified as a whitespace-separated list. The default protocol is TLSv1.2.

Only for smtp type.

mail.smtps.ssl.protocols

The enabled SMTPS SSL connection protocols. Protocols are specified as a whitespace-separated list. The default protocol is TLSv1.2.

Only for smtp type.

mail.mime.allowutf8

Adds support for UTF-8 (Non-ASCII) characters in the local part of email addresses (everything before the @ character) if set to true.

Do not set this property unless your SMTP provider supports UTF-8 characters. Learn more in International email addresses.

Only for smtp type.

Revert the email provider to use the built-in SMTP server

Email provider configuration changes made in one realm are applied to both realms.

If you need to revert the email provider to use the built-in SMTP server:

In the Advanced Identity Cloud admin UI, go to Email > Provider.
On the Email Provider page, disable Use my own email provider.
Click Save.

The built-in SMTP server does not support:

OTP Email Sender nodes in password journeys.
Non-ASCII characters in email addresses (international email addresses).