PingOne Advanced Identity Cloud

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:

Setup process

Email provider configuration changes made in one realm are applied to both realms.
  1. Create a new email template.

  2. 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.

  3. 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.

  4. Promote your configuration changes to your tenant staging environment.

  5. 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.

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

  1. Navigate to Azure Active Directory | App registrations.

  2. 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.
  3. Add a client secret:

    1. On the my-email-client page, in the main Essentials area, click Add a certificate or secret.

      Show Me
      Azure app - add a secret link
    2. On the Certificates & secrets page, select the Client secrets tab, and click + New client secret.

      Show Me
      Azure app - add a new client secret
    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.
  4. 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
      Azure app - Request API permissions

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.

Using the UI

  1. In the Advanced Identity Cloud admin UI, go to Email > Provider.

  2. On the Email Provider page, enable Use my own email provider.

  3. 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.

  4. 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.

  5. 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.

  6. 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

Table 4. smtpProperties sub-properties
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.

No

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.

No

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.

No

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:

  1. In the Advanced Identity Cloud admin UI, go to Email > Provider.

  2. On the Email Provider page, disable Use my own email provider.

  3. Click Save.

The built-in SMTP server does not support: