Customize a forgotten password recovery email

Okta can send an email notification to an end user who has forgotten their password. They must follow the provided link to complete the forgot password process.

If you’re using an embedded authentication deployment model for your application's sign-in flow, you can create a customized email magic link for your Forgot Password email template.

The option to send a forgotten password recovery email with a custom link is available only to OIDC applications on Identity Engine organizations.

You can customize any default email template. However, when you edit a default template, Okta stops sending the default message in other languages. Adding translations of your customized message is your responsibility.

The custom link for forgotten passwords has several required elements:

  • <app endpoint>: The Sign-in redirect URI for your app integration where users reset their password. This value depends on the app integration but is generally of the form: https://example.com/login/callback
  • otp: This value is generated by a macro called ${oneTimePassword}
  • state: This value is generated by a macro named ${request.relayState}. It contains the OAuth state parameter defined by the client in the original call to the interact endpoint.

You can also include any relevant macro from the Velocity Template Language

For example, in an Identity Engine org, you could compose the ${resetPasswordLink} statement for the forgot password email template as:

Copy 
https://example.com/login/callback?otp=${oneTimePassword}&state=${request.relayState}&location=
    ${request.location}&ip=${request.ipAddress}&browser=${request.browser}

After you create your custom statement for the forgot password link, you need to modify the Forgot Password email template:

  1. In the Admin Console, go to CustomizationsBrands.
  2. Select a brand.
  3. Click Emails.
  4. Click Forgot Password in the list of email templates.
  5. Click Edit to open the message in HTML. If you see Add Translation instead of Edit then the template has already been customized. You must edit the default language copy.
  6. Locate the following code: id="reset-password-link" href="${resetPasswordLink}". Replace ${resetPasswordLink} with your custom statement.
  7. Click Save. The default language copy of your edited message appears in the Custom Email table. You also need to edit any templates outside of the default language copy. See the Add translations section inside the Customize an email template topic.