AM 7.4.0

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.

If the user enters an invalid first or last name, username, or email address during the username or password reset flows, AM presents them with a message similar to An email has been sent to the address you entered. Click the link in that email to proceed, but does not actually send an email.

If the user enters an existing username while registering, AM presents them with a message similar to An email has been sent to the address you entered. Click the link in that email to proceed, and then sends an email with a registration link to the address that the user entered. Clicking on the link sends the user to the registration page again, and AM shows a message similar to One or more user account values are invalid.

This is to protect the service against account enumeration attacks.

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

Perform the following 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.

    The Transport Type drop-down menu is empty until a secondary configuration is created.

  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.

    For more information about the different configuration properties, refer to Email service.

  6. Save your changes.

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

  8. To configure an OAuth 2.0 REST-based transport type, select Microsoft Graph API.

    Refer to the details of your Microsoft account to complete these settings.

    • Provide a name for the Microsoft REST transport secondary configuration.

      This name is used later to map the client secret in the secret store.

      The name must include alphanumeric characters only.
    • In the Email Rest Endpoint URL field, enter the URL for the endpoint URL for sending emails.

      The format for this 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.

    • In the OAuth2 Token Endpoint URL field, enter the OAuth 2.0 authentication endpoint.

      The format for this 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.

    • In the OAuth2 Client Id field, enter the ID for the OAuth 2.0 client. This is the client ID or application ID provided by the Microsoft Application Registration portal.

    • In the OAuth2 Scopes field, enter the scopes to be requested as part of the OAuth 2.0 authentication. The value supported by Microsoft Graph API is https://graph.microsoft.com/.default.

    You must also save the client secret obtained from Microsoft in the secret store. This example uses the file system secret store:

    1. Create a file system secret volume if one does not exist already.

    2. Map the secret ID to a file:

      1. Create a file named am.services.email.microsoftrest.TRANSPORT CONFIGURATION NAME.clientsecret; for example, if you named the Microsoft REST transport secondary configuration msrest, create a file named am.services.email.microsoftrest.msrest.clientsecret.txt.

        The filename must use alphanumeric characters only.

      2. Add the secret to the file and save.

  9. To configure an SMTP Basic authentication transport type, select SMTP.

    Note that SMTP Basic authentication is deprecated and you should use the OAuth 2.0 REST-based Microsoft Graph API transport configuration instead where possible.

    • Provide a name for the SMTP transport secondary configuration.

    • In the Mail Server Host Name field, enter the hostname of the mail server. If you are using the Google SMTP server, you must also configure the Google Mail settings to enable access for less secure applications.

    • In the Mail Server Authentication Username field, enter the username to authenticate to the mail server. If you are testing on a Google account, you can enter a known Gmail address.

    • In the Mail Server Authentication Password field, enter the password corresponding to the username used to authenticate to the mail server.

    • Select Create.

    • Configure additional properties in the email service as needed.

You can configure different realms to use different email transport configuration types.
Copyright © 2010-2023 ForgeRock, all rights reserved.