Instructions for

On this page

Email Magic Links overview

Identity Engine

Enable a user to enter a one-time passcode (OTP) in a single step by clicking an embedded email link.

Introduction

When using email to prove their identity, a user can copy an OTP from an email into the application they want to use. Email Magic Links (EML) provide a second option, which allows the user to click a hyperlink in the email rather than use the OTP. This results in a quicker, more user-convenient, and still secure experience. However, applications based on the Embedded Sign-In Widget or an Embedded SDK must be adapted to make use of EML.

A simple diagram showing a cursor clicking a magic link in an email and beign signed in successfully


Learning outcomes

  • Understand the differences between EML and OTP
  • Integrate EML into applications using the Embedded Sign-In Widget or a supported Embedded SDK.

Note: Email Magic Links are only supported in OIDC-based app integrations.

The Okta email authenticator provides a simple way for a user to authenticate themselves or recover their accounts. It supports two methods for them to validate their credentials as part of those processes. In both methods, an email is sent to their primary email address and either:

  1. They copy an OTP from the email to their application and submits it to Identity Engine for authentication.
  2. They click a link in the email that submits the OTP to Identity Engine for authentication on their behalf.

If a valid OTP is submitted within a set time, either the user is authenticated or they continue their authentication process. The following diagram illustrates the user's experience with the two options.

Flow diagrams showing the difference in user experience between using OTP and using magic links for authentication

The OTP experience involves an extra step for the user — copying the OTP into the application — but it does ensure that they return to the same browser to continue their authentication process. The magic link experience, on the other hand, has fewer steps. Clicking the magic link opens a new tab in the user's browser and their authentication process continues.

Same device, same browser only

Magic links only work when there is complete assurance that the person who started the request is the same one who clicked the magic link. For this reason, a user who starts signing in to your application in a web browser must be in the same browser on the same device when they click the magic link. If their browser or device is different, the magic link is disabled. They must either return to the original browser to use the magic link or use the OTP instead. The following flowchart illustrates this logic.

Flow diagram showing when and how the magic link flow falls back to the OTP flow

This same browser enforcement also ensures that a user doesn't sign in to applications from non-managed devices. For example, should they start the sign-in process on a company laptop, and then click the magic link from their personal device, they must return to the company laptop to complete the process.

Pros and cons of EML

When you evaluate whether to support magic links in addition to OTPs in the email authenticator, consider the following:

  • A user has a better sign-in experience from magic links than OTP if they sign in from the same browser on the same device.
  • If a user signs in from a different browser or device, the process falls back to using an OTP.
  • A user can only access an application by clicking a magic link on a device that already has access to that application.
  • Okta provides support for both OTP and Magic Links in their Embedded Sign-In Widget and Identity Engine SDKs.

Integrating Email Magic Links into your application is a two-step process.

  1. Create an endpoint for your magic link. This endpoint checks the validity of the OTP and sends it to Identity Engine for validation.
  2. Set that endpoint as the callback URL for magic links for your application with the Admin Console for your org.

Any magic link URL pointing to your application contains two query parameters:

  • The OTP that validates the user (otp)
  • A state token that uniquely identifies the current authentication process and its state (state)

For example, http://${yourOktaDomain}?otp=726009&state=1b31fa98b34c45d9a.

You must create an endpoint for your application that:

  1. Retrieves otp and state values from the query parameters
  2. Matches the state token with the current state in your user's browser session
  3. Makes any other checks you deem necessary to ensure that the user is working in the same browser on the same device
  4. Requests that the user enter the otp value manually if steps 2 or 3 fail
  5. Sends the otp value to Identity Engine for validation if steps 2 and 3 pass
  6. Redirects the user to a page that continues their authentication process

If your application uses the Embedded Sign-In Widget to authenticate the user, pass otp and state to it as you instantiate it on the page.

var searchParams = new URL(window.location.href).searchParams;
var signIn = new OktaSignIn({
   baseUrl: '${yourOktaDomain}',
   baseUrl: '${yourOktaDomain}',
   clientId: '${yourClientId}',
   redirectUri: '${yourSignInRedirectUrl}',
   otp: searchParams.get('otp'),
   state: searchParams.get('state')
});

Important: In Okta Sign-In Widget version 7+, Identity Engine is enabled by default. If you are using an earlier version than 7, you must explicitly enable Identity Engine features by setting useInteractionCodeFlow: true in the OktaSignIn() constructor call shown above. If you are using version 7+ and you want to use Okta Classic Engine rather than Identity Engine, specify useClassicEngine: true in OktaSignIn().

The code for your endpoint will also need to check the user is working from the same device and browser. The Sign-In Widget takes care of the rest. The sign in with email only guide covers how to do this.

Use the

and guides to implement these steps with your Embedded SDK.

There are two ways to set your application's magic links to the endpoint that you created:

  • You can set your application's Email Verification Experience (EVE) value to the endpoint's URL.
  • You can customize each of the email templates used by the email authenticator to include the endpoint's URL.

Changing the EVE provides a quick way to enable and test magic links. Customizing the email templates requires more work but results in fewer roundtrips to Identity Engine and a faster user experience.

Use the Email Verification Experience

To enable magic links in your application using the email verification experience (EVE) setting:

  1. Open the Admin Console for your Okta org.
  2. Choose Applications > Applications to show the app integrations that you have already created.
  3. Click the application that you previously created.
  4. In the General Settings section on the General tab, click Edit.
  5. Under EMAIL VERIFICATION EXPERIENCE enter the URL for the endpoint you created. For example, https://example.com/magiclink/callback.
  6. Click Save to save your changes.

When required, Identity Engine sends an email similar to this one containing an OTP and a link:

A sample email sent by the Identity Engine with OTP and magic link highlighted


When a user clicks the magic link from the email authenticator, a request is sent to Identity Engine to validate the user. The link has a token parameter and looks something like this:

https://${yourOktaDomain}/email/verify/0oa1esny76wdQqjsg697?token=ftlNKCIYA_4WvR6BPbYhyKisVYIF-QLp2t

Authentication continues at an Okta-hosted page if the EVE setting doesn't have a value. If there is a value, Identity Engine builds a new URL based on the EVE setting and the current otp and state values. Then it redirects the user's browser to that URL. For example:

https://example.com/magiclink/callback?state=1ed1d4de1a50b8f30d87e720bcc1b6a3&otp=439246

After validating the otp and state parameters, the authentication process continues for the user.

Flow diagram showing the interaction between application and Identity Engine when using the Verification Experience setting

The EVE setting offers a quick way to redirect magic links to your application, but it does require a round trip to the Identity Engine to retrieve the correct URL for the endpoint you have created. Unless you are willing to customize the email templates the email authenticator uses, the user receives only Okta-branded emails.

If your user base is multilingual, consider that the Okta-branded email templates support many languages by default. After you customize an email template, you must create a copy of that template in each language you support.

Use custom email templates

Creating custom authentication email templates allows you to send a fully-branded email to a user that skips the round-trip to Identity Engine and redirects them straight to your endpoint.

All Okta email templates are written using Velocity Templating Language (VTL) (opens new window) and use predefined variables to insert relevant values into that email. For example, Okta defines three VTL variables specific to the Email Challenge template:

Variable Contains
${verificationToken} The one-time passcode that Identity Engine generated for the user
${request.relayState} The OIDC/OAuth2 state parameter for the current authorization request
${emailAuthenticationLink} The Okta-hosted URL that continues the password recovery flow

By default, the magic link in the template is set to ${emailAuthenticationLink}. If you're using the Email Verification Experience setting for your redirects, you don't need to change this. The magic link works as explained in the Use the Email Verification Experience section.

To point the magic link directly to the endpoint in your application, you must replace ${emailAuthenticationLink} with your custom URL that includes otp and state as query parameters:

  1. In the Admin Console, go to Customizations > Emails.

  2. On the Emails page, find the Other category on the template menu.

  3. Under Other, click Email Challenge.

  4. On the Email Challenge email template page, click Edit.

  5. Under Default Email, click Edit.

  6. In the Message field, locate the magic link in the field's HTML. The link is located in the href attribute of an <a> tag with the id of email-authentication-button. It looks like this:

    <a id="email-authentication-button"
    href="${emailAuthenticationLink}"
    style="text-decoration: none;">
       <span style="padding: 9px ...;">
          Sign In
       </span>
    </a>
    
  7. Replace the ${emailAuthenticationLink} variable with the URL for your endpoint. You must append the ${verificationToken} and ${request.relayState} variables as query parameter values. For example:

    <a id="email-authentication-button"
    href="https://example.com/magiclink/callback?otp=${verificationToken}&state=${request.relayState}"
    style="text-decoration: none;">
       <span style="padding: 9px ...;">
          Sign In
       </span>
    </a>
    
  8. Click Save and close the dialog.

You can customize four email templates this way. These are listed in the table below.

  • All support redirects through EVE and custom templates.
  • All are compatible with applications based on either the Embedded Sign-In Widget or a supported Embedded SDK.
  • To add otp and state variables to the magic link, find the template that you are editing in the table, and:
    • Replace the VTL variable in the magic link variable name column with your custom endpoint URL.
    • Set your otp query string variable to the VTL variable in the OTP variable name column for the template.
    • Set your state query string variable to ${request.relayState} for all templates.
Template name Use case Magic link variable name OTP variable name
Email challenge Sign in with email - challenge ${emailAuthenticationLink} ${verificationToken}
Forgot Password Self-service password recovery ${resetPasswordUrl} ${oneTimePassword}
Registration - Activation Self-service registration ${registrationActivationLink} ${oneTimePassword}
Email factor verification Sign in with email - enrollment ${verificationLink} ${verificationToken}
Self-Service Unlock Account Self-service unlock account ${unlockAccountLink} ${oneTimePassword}

When a user clicks the magic link based on a customized email template, their browser is redirected straight to your application's endpoint:

Flow diagram showing the interaction between application and Identity Engine when using custom email templates

Comparing the options

EVE + Default email templates EVE + Custom email templates Custom email templates
Set-up + Maintenance Requires one change in the Admin Console Requires editing every email template that uses magic links to point to your new endpoint. Requires editing every email template that uses magic links to point to your new endpoint.
Speed of redirection Magic link sends a request to Identity Engine for the callback URL. The user is then redirected to the callback URL. Magic link sends a request to Identity Engine for the callback URL. The user is then redirected to the callback URL. Magic link sends browser directly to the callback URL
Branding Default Okta-branded email templates You can add your brand to a custom email template You can add your brand to a custom email template
Multi-language support Default email templates support multiple languages You must create and maintain a version of each custom template in each required language. You must create and maintain a version of each custom template in each required language.

See also