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. At the start of your onboarding process, this lets you quickly create and test email-dependent journeys using the ready-to-use email templates.

During your onboarding process, you need to update the email provider configuration to use your own external email service in order to provide robust email delivery to your end users.

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

Built-in SMTP server

The built-in SMTP server is preconfigured in Advanced Identity Cloud and enabled by default in your tenant development and sandbox[1] environments.

The built-in SMTP server is for testing purposes only and has the following limitations:

  • Outbound email is rate-limited to 10 messages per minute.

  • All emails are sent from a standard address in the format noreply@<tenant-fqdn>, which overrides any sender address set in email templates or API calls. It provides consistent delivery and helps ensure messages are sent securely.

  • It doesn’t support OTP Email Sender nodes in password journeys.

  • It doesn’t support non-ASCII characters in email addresses.

In your staging, UAT[2], and production tenant environments, you must update the email provider configuration to use your own external email provider.

External email services

Advanced Identity Cloud supports two external email service types:

SMTP

  • Send emails through your own SMTP server or a third-party email service such as Amazon SES.

  • Can only be configured in mutable environments:

    • Use the admin console or API to set literal values for testing.

    • Use the API to set ESV placeholders to make the configuration compatible with promotion.

  • Use this configuration type for sending email to international email addresses.

MS Graph API

  • Send emails using the MS Graph API sendMail endpoint.

  • Can only be configured in mutable environments:

    • Not configurable using the admin console.

    • Use the API to set literal values for testing or set ESV placeholders to make the configuration compatible with promotion.

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.

Configure an email provider across your tenant environments

The high-level process to set up an email provider across your tenant environments is as follows:

  1. In your development environment:

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

    2. When you’re satisfied with your test results:

      1. Configure the email provider configuration to use an SMTP or MS Graph API external email service. Use the instructions in Configure a mutable environment to use an email provider.

      2. Verify that your email templates work with the external email service.

    3. When you’re satisfied that your external email provider is working correctly:

      1. Insert ESV placeholders into the email provider configuration to make it compatible with the promotion process.

      2. Restart Advanced Identity Cloud services.

      3. Verify that your email templates work with the updated ESV configuration.

  2. Determine the promotion order of your tenant environments. This will depend on whether you have a standard promotion group of environments or whether you also have additional UAT environments.

  3. In promotion order, for each of the tenant environments in your promotion group, perform the following steps:

    1. Create the same ESVs in the tenant environment as you created in step 1c. Ensure the ESV values are correct for the tenant environment.

    2. Run a promotion to move the configuration changes to the tenant environment from its respective lower tenant environment. Learn more in:

  4. (Optional) If you have sandbox[1] environments, repeat steps 1b and 1c for each sandbox environment.

Configure a mutable environment to use an email provider

In your development or sandbox[1] tenant environments, configure the email provider to use your own external email service:

  • For SMTP, you can use the admin console or API.

  • For MS Graph API, you can only use the API.

Using the admin console

  1. In the Advanced Identity Cloud admin console, 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.

    From Name

    Name of sending organization.

    Host

    Hostname or IP address of your 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 <access-token>" \(1)
--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"
1 Replace <access-token> with an access token that has the fr:idm:* scope. Learn more in Get an access token.

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
}

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

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

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

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

  3. Click Save.

The built-in SMTP server is for testing purposes only and has the limitations noted at the top of this page.