PingIDM 8.0.0

Outbound email service

The outbound email service sends email from IDM using a script or the REST API.

You can edit the email service over REST at the config/external.email endpoint, or in the external.email.json file in your project’s conf directory.

IDM supports UTF-8 (non-ascii/international) characters in email addresses, such as zoë@example.com. When sending emails to these type of addresses, the configured SMTP server must also support UTF-8.

Email service configuration types

The outbound email service 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, which is only available using the REST API or the filesystem. For more information, refer to smtpProperties sub-properties.

MS Graph API requirements

Use of the MS Graph API email client requires a properly configured Microsoft Azure tenant. The basic 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 mail client

  1. Navigate to Azure Active Directory | App registrations.

  2. Create the IDM client application:

    1. From the menu bar, click + New Registration.

    2. On the Register an application page, enter the application Name, such as idm-email-client.

    3. For Supported account types, select the applicable option for your organization.

    4. Click Register.

    5. On the idm-email-client page, in the main Essentials area, record the Application (client) ID.

      This is the value for clientId in the auth settings of the email configuration. Refer to oauth2 properties.

  3. Add a client secret:

    1. On the idm-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. Refer to 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 outbound email

To configure the outbound email service using the admin UI, click Configure > Email Settings.

  1. Edit the email configuration with the mail server details and account.

  2. Submit the configuration over REST or copy the file to your project’s conf/ directory. For example:

    • REST

    • Filesystem

    curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--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
}' \
"http://localhost:8080/openidm/config/external.email"
    cp /path/to/external.email.json /path/to/openidm/conf/
    IDM encrypts the password.

Storing MS Azure credentials as a secret

You can enable zero-downtime rotation of your clientId and clientSecret credentials by storing those values in a file system based secret store.

To configure an existing IDM external email client with an existing MS Azure tenant to use a file system secret store:

  1. Add a new secret in the Microsoft Azure portal. For more information, refer to the Microsoft identity platform documentation.

  2. Create the idm.email.msgraph.credentials file in your file system-based secret store. The file must contain a JSON object with your secret values, such as:

    {
  "clientId": "myClient",
  "clientSecret": "mySecret"
}

  3. Update the auth property in conf/external.email.json to read the clientId and clientSecret from the secret file using a purpose. You must set a jsonPointer property that identifies the matching field in the secret file:

    {
...
  "auth": {
    "enable": true,
    "type": "oauth2",
      "clientId": {
        "$purpose": {
          "name" : "idm.email.msgraph.credentials",
          "jsonPointer" : "clientId"
        }
      },
      "clientSecret" : {
        "$purpose" : {
          "name" : "idm.email.msgraph.credentials",
          "jsonPointer" : "clientSecret"
        }
      },
      "tokenEndpoint" : "https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token",
      "scope" : [
            "https://graph.microsoft.com/.default"
      ],
      "scopeDelimiter" : " ",
      "grantType" : "client_credentials"
    }
}
If you use a secret that only stores a password, you only need to update the clientSecret value in conf/external.email.json.

Sample email configuration

This sample email configuration sets up the outbound email service:

  • 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"
    ],
    "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
}

External email configuration properties

The msgraph type also supports the External REST configuration properties.

Properties
Property Description Required? /
Type Support

type

The email service 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 host name or IP address of the SMTP server. This can be the localhost, if the mail server is on the same system as IDM.

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

No

Only for smtp type.

from

Specifies a default From: address which displays when users receive emails from IDM.

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. Refer to the authentication sub-properties table for all options.

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. Refer to the SMTP sub-properties table for all options.

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 5 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 5 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 5 minutes. A setting of 0 disables this timeout.

No

Only for smtp type.
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

oauth2 properties

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. To store as a secret, refer to Storing MS Azure credentials as a secret.

Yes

clientSecret

clientSecret used to request an access token from the token endpoint. Obtained during Azure application creation. To store as a secret, refer to Storing MS Azure credentials as a secret.

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
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 UTF8 (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 UTF8 characters.

  • Can only be configured using REST or the filesystem.

No

Only for smtp type.

Email rate limiting

No rate limiting is applied to password reset emails, or any emails sent by the IDM server. This means that 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 a production environment, you must configure email rate limiting through the network infrastructure in which IDM runs. Configure the network infrastructure to detect and prevent frequent repeated requests to publicly accessible web pages, such as the password reset page. You can also handle rate limiting within your email server.