PingAM 7.5.1

Configure the email service

The user self-service feature lets you send confirmation emails to users who are registering on your site or resetting forgotten passwords. Mails are sent using AM’s SMTP or OAuth 2.0 REST-based email service. You can configure the email service by realm or globally.

Each user must have a unique email address to use the email features of user self-service.

  • If a user enters an invalid first or last name, username, or email address during the username or password reset flows, AM doesn’t send an email but still presents the user with a message similar to:

    An email has been sent to the address you entered. Click the link in that email to proceed.

  • If a user enters an existing username while registering, AM sends an email with a registration link to the address that the user entered and presents the user with a message similar to:

    An email has been sent to the address you entered. Click the link in that email to proceed.

    Clicking that link redirects the user to the registration page, and AM shows a message similar to:

    One or more user account values are invalid.

This behavior protects the service against account enumeration attacks.

Follow these steps to configure the email service:

  1. In the AM admin UI, go to Realms > Realm Name > Services.

  2. Select Add a Service and choose Email Service from the list of available services.

  3. In the Email From Address field, enter the email address from which to send email notifications; for example, no-reply@example.com.

    For Microsoft Graph API transport configurations, this address must exist in the Microsoft Exchange administration center.

    You can’t select anything in the Transport Type drop-down menu at this stage.

  4. Click Create.

  5. Configure the generic attributes that apply to both types of email service, such as the profile attribute for the user’s email address, the subject, and content for notification messages.

    Learn more about the different configuration properties in Email service.

    You can’t select anything in the Transport Type drop-down menu at this stage.

  6. Save your changes.

  7. On the Secondary Configurations tab, click Add a Secondary Configuration.

  8. Select one of the following:

    • Microsoft Graph API to configure an OAuth 2.0 REST-based transport type email service.

    • SMTP to configure an SMTP basic authentication transport type email service.

You can configure different realms to use different email transport configuration types.

Microsoft Graph API

  1. Refer to your Microsoft account to complete the following settings on the New microsoftRestTransports configuration screen:

    Property Value Notes

    Name

    A unique name for this MS Graph API service.

    The name must include alphanumeric characters only.

    You’ll use this name later to map the client secret in the secret store.

    Email Rest Endpoint URL

    The REST endpoint URL for sending emails through the MS Graph API.

    The format of this URL is https://graph.microsoft.com/v1.0/users/user ID/sendMail, for example: https://graph.microsoft.com/v1.0/users/bjensen@xftq8.onmicrosoft.com/sendMail.

    OAuth2 Token Endpoint URL

    The OAuth 2.0 authentication endpoint.

    The format of this URL is https://login.microsoftonline.com/tenant ID/oauth2/v2.0/token, for example: https://login.microsoftonline.com/d258d3da-98a2-492b-875e-059a6abfbdf9/oauth2/v2.0/token.

    OAuth2 Client Id

    The ID for the OAuth 2.0 client.

    This is the client ID or application ID provided by the Microsoft Application Registration portal.

    OAuth2 Scopes

    The scopes to be requested as part of the OAuth 2.0 authentication.

    The only value supported by the Microsoft Graph API is https://graph.microsoft.com/.default.

  2. Click Create.

  3. Obtain the client secret from the Microsoft Application Registration portal and map it to a secret label in the secret store.

    Use one of the following methods:

    1. Dynamic secret label (all secret stores):

      1. Set a value in the Secret Label Identifier field.

        AM uses this identifier to generate a specific secret label for this email service.

        The secret label has the format am.services.mail.microsoftrest.identifier.clientsecret where identifier is the value of the Secret Label Identifier field.

        The Secret Label Identifier can only contain characters a-z, A-Z, 0-9, and periods (.). It can’t start or end with a period.

      2. Store the client secret obtained from the Microsoft Application Registration portal in a secret in a secret store.

      3. Map the secret to the generated secret label.

      4. For improved security, rotate this secret periodically.

    2. Secret label based on a filename (file system secret stores only):

      1. Create a file system secret volume if one doesn’t exist.

      2. Create a file named am.services.email.microsoftrest.service-name.clientsecret; for example, if you named this MS Graph API service msrest, create a file named am.services.email.microsoftrest.msrest.clientsecret.txt.

        The filename must use alphanumeric characters only.

      3. Add the client secret obtained from the Microsoft Application Registration portal to the file and save.

      4. Map the secret label am.services.email.microsoftrest.service-name.clientsecret to the file system secret you created in the previous step.

If you set a Secret Label Identifier, the secret mapped to the generated secret label takes precedence over the secret mapped to am.services.mail.microsoftrest.service-name.clientsecret.

SMTP

SMTP Basic authentication is deprecated. Where possible, use the OAuth 2.0 REST-based Microsoft Graph API transport type instead.

  1. On the New smtpTransports configuration screen, complete the following settings:

    Property Value Notes

    Name

    A name for the SMTP transport secondary configuration.

    Mail Server Host Name

    The hostname of the mail server.

    If you’re using the Google SMTP server, configure the Google Mail settings to enable access for less secure applications.

    Mail Server Authentication Username

    The username to authenticate to the mail server.

    If you’re testing with a Google account, you can enter a known Gmail address.

    Mail Server Authentication Password

    The password of the username who authenticates to the mail server.
    For improved security, set a Secret Label Identifier to store the password in the secret store instead. If you set a Secret Label Identifier and AM finds a matching secret in the secret store, it ignores this password field.

    Secret Label Identifier

    AM uses this identifier to generate a specific secret label for this email service.

    The secret label has the format am.services.email.smtp.identifier.secret where identifier is the value of Secret Label Identifier.

    The Secret Label Identifier can only contain characters a-z, A-Z, 0-9, and periods (.). It can’t start or end with a period.

    If you set a value in this field, AM ignores the Mail Server Authentication Password.

  2. Click Create.

  3. Map a secret in the secret store to the generated secret label.