Skip to main content

Magic Links

Magic links are a type of password-less authentication that let your users log in by following a link that is emailed to them, rather than typing a username and password. We wrote a blog post with more details and the advantages and disadvantages in the Magic Links Guide.

Email must be configured before setting up magic links. See the email setup guide if you haven't already done that.

Magic links are provided by the open source keycloak-magic-link extension, which is included on every Phase Two cluster. It provides three authenticators you can use in a browser flow:

AuthenticatorWhat the user does
Magic LinkEnters their email and follows the emailed link. The login completes on the device where the link is opened, so the link can be opened on another device.
Magic Link continuationEnters their email and follows the emailed link. The login completes in the original browser tab, which waits until the link has been opened.
Email OTPEnters their email, then types a 6-digit code that is emailed to them. See One-time Passwords.

For codes sent by text message, we recommend the extension described in SMS OTP. Please contact support for assistance.

New realms include a flow named magic link in the Flows tab of the Authentication section. If your realm doesn't have it, create one as described in Create a magic link flow.

Open the configuration for the Magic Link step by clicking the gear icon on its row. The options are:

  • Alias is a name for this configuration.
  • Force create user creates a new user when an email is entered that doesn't match an existing user. This lets magic links register new users. It is on by default.
  • Update profile on create adds an UPDATE_PROFILE required action if the user was created, so the user fills in other required fields, such as first and last name.
  • Update password on create adds an UPDATE_PASSWORD required action if the user was created.
  • Allow magic link to be reusable lets the link be used more than once until it expires. It is on by default.
  • Token lifespan is how long the link is valid, in seconds. It defaults to one day.

Keycloak Phase Two Magic Link Configuration

Save the configuration and go back to the flow page. In the Action menu in the upper right, select Bind flow, and choose Browser flow.

Login UI​

After binding the magic link flow to the browser flow, reload your login screen. There is only a field for the email address, and the password field is gone.

Keycloak Phase Two Magic Link Login Page

After the user enters a valid email address, a magic link is sent to that email, and the login screen asks the user to click the link to complete the login.

Keycloak Phase Two Magic Link Email Sent

To build the flow yourself, or a variation of it:

  1. In Authentication > Flows, duplicate the browser flow and give it a name, such as browser with magic link.
  2. In the forms sub-flow, delete the Username Password Form and the conditional OTP sub-flow.
  3. Add the Magic Link step to the forms sub-flow, and set it to Required. It renders its own email form, so you don't need a separate username form.
  4. Configure the step as described above, and bind the flow to the browser flow.

Use Magic Link continuation instead of Magic Link if you want the login to complete in the browser where it started. Its configuration has an Expiration time, in minutes, after which the waiting login page resets. It defaults to 10 minutes.

The extension also adds a REST endpoint, POST /auth/realms/<realm>/magic-link, that creates a magic link for a user and either emails it or returns it to your application. The caller needs the manage-users role. Links created this way log the user in directly, without running an authentication flow. The parameters are documented in the keycloak-magic-link README.

Single-page apps

A magic link is an authorization response that your application didn't start. If the link sends users to a single-page app that uses keycloak-js or a similar library, pass "response_mode": "fragment" (or whatever response mode your client uses) together with a random state when you create the link. Without them, Keycloak 26.6.5 and later reject the follow-up login with Invalid parameter: redirect_uri. See Using magic links with a single-page app for the details.

Account activation​

For realms where some users still need to verify their email or set their first password, such as self-registered or migrated users, the extension includes an Activation Gate step. It asks for the email first, then sends users whose accounts still need activation an email with the steps they have to complete, and lets activated users continue to the password form. See Account Activation in the extension's README.