Email provider

Overview

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, 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 configure the email provider with values to connect to your own external SMTP server.

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. Configure the email provider to use your own external SMTP server.
2. Verify that your email templates work with the external SMTP server.
Promote your configuration changes to your tenant staging environment.
(Optional) 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 SMTP server 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. Identity Cloud provides this ready-to-use server for testing purposes only.

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 SMTP server using the UI or the API.

Using the UI

In the 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, but required.

From Name

Name of sending organization.

Host

Hostname or IP address of your SMTP server.

When no hostname is specified, 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 Identity Cloud times out due to unsuccessful socket connection to the SMTP server. A setting of 0 disables this timeout.

Default is 300000 ms (5 minutes).

Socket Write Timeout (ms)

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

Default is 300000 (5 minutes).

Socket Timeout (ms)

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

Default is 300000 (5 minutes).

Use STARTTLS

If enabled, and if the SMTP server supports the STARTTLS command, then 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, Identity Cloud uses SSL to connect to the SMTP server.

Disabled by default.

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 see 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 <access-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"
    ],
    "threadPoolSize" : 20
}' \
"https://<tenant-env-fqdn>/openidm/config/external.email"

Email provider configuration properties

host

The hostname or IP address of the SMTP server.

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.

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 mail server.

auth

The authentication details for the mail account from which emails will be sent.

enable—indicates whether you need login credentials to connect to the SMTP server.
If "enable" : false,, you can leave the entries for "username" and "password" empty:

"enable" : false, "username" : "", "password" : ""
username—the account used to connect to the SMTP server.
password—the password used to connect to the SMTP server.

Identity Cloud encrypts the password.

from (optional)

Specifies a default From: address users see when they receive emails from Identity Cloud.

Although from is optional, the email service requires this property to send email. If you do not specify a from address in the email provider 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).

timeout (integer, optional)

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.

writetimeout (integer, optional)

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.

connectiontimeout (integer, optional)

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.

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 SMTP server does not support STARTTLS, the connection continues without the use of TLS.

ssl

Set "enable" : true to use SSL to connect to the SMTP server.

smtpProperties

Specifies the SSL protocols that will be enabled for SSL connections. Protocols are specified as a whitespace-separated list. The default protocol is TLSv1.2.

threadPoolSize (optional)

Sets the number of concurrent emails that can be handled at a specific time. Emails are sent in separate threads managed by a thread pool. The default thread pool size (if none is specified) is 20.

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