🚀 Try it for free in the new Phase Two keycloak managed service. See the announcement and demo video for more information.

keycloak-magic-link

Magic link implementation. Inspired by the experiment by @stianst.

There is also a simple Email OTP authenticator implementation here. This extension is used in the Phase Two cloud offering, and is released here as part of its commitment to making its core extensions open source. Please consult the license for information regarding use.

Quick start

The easiest way to get started is our Docker image. Documentation and examples for using it are in the phasetwo-containers repo. The most recent version of this extension is included.

Magic link

This implementation differs from the original in that it creates an ActionToken that is sent as the link. This is convenient, as it does not require the user to click on the link from the same device. A common use case we heard was users entering their email address on the desktop, but then clicking on the link on their mobile, so we wanted to solve for that case.

This contains two pathways to get a Magic Link:

Authenticator

An Authenticator that can run as a form in your login flow. This takes an email, and can optionally create a user if none exists. This implementation sends the email using a theme-resources template, which you can override. Installation can be achieved by duplicating the Browser flow, and replacing the normal Username/Password/OTP forms with the Magic Link execution type (@tstec-polypoly provides a great step-by-step guide for setting it up #6 (comment)). Note that you aren't required to use a Username form with this, as it extends UsernamePasswordForm and renders the username form page for you:

The authenticator can be configured to create a user with the given email address as username/email if none exists. It is also possible to force UPDATE_PROFILE and UPDATE_PASSWORD required actions when the user is created by this Authenticator:

Resource

A Resource you can call with manage-users role, which allows you to specify the email, clientId, redirectUri, tokenExpiry and optionally if the email is sent, or the link is just returned to the caller.

Parameters:

Sample request (replace your access token):

curl --request POST https://keycloak.host/auth/realms/test/magic-link \
 --header "Accept: application/json" \
 --header "Content-Type: application/json" \
 --header "Authorization: Bearer <access_token>" \
 --data '{"email":"[email protected]","client_id":"account-console","redirect_uri":"https://keycloak.host/auth/realms/test/account/","expiration_seconds":3600,"force_create":true,"update_profile":true,"update_password":true,"send_email":false}'

Sample response:

{
  "user_id": "386edecf-3e43-41fd-886c-c674eea41034",
  "link": "https://keycloak.host/auth/realms/test/login-actions/action-token?key=eyJhbG...KWuDyE&client_id=account-console",
  "sent": false
}

Email OTP

There is a simple authenticator to email a 6-digit OTP to the users email address. This implementation sends the email using a theme-resources template, which you can override. It is recommended to use this in an Authentication flow following the Username form. An example flow looks like this:

Installation

1. Build the jar:

mvn clean install

2. Copy the jar produced in target/ to your providers directory (for Quarkus) or standalone/deployments directory (for legacy) and rebuild/restart keycloak.

Releases

Releases are tagged and published to Maven Central after each merge to main. Jars can be downloaded from there.

If you are depending on the library in your own Maven-built project, or using a bundling tool in Maven, you can add the dependency like this:

    <dependency>
      <groupId>io.phasetwo.keycloak</groupId>
      <artifactId>keycloak-magic-link</artifactId>
      <version>VERSION</version>
    </dependency>

Implementation Notes

This is a rough outline of the implementation:

• Given an email address
  • see if the email is already associated with a user
    • if yes, use that one
    • if not, create a user (this is configurable)
  • check to see if the redirectUri is valid for the client
    • if yes, continue
    • if not, throw an error
  • create an action token that encodes the user, expiry, clientId and redirectUri
  • action token handler needs to
    • invalidate the action token after single use
    • set the redirectUri
    • make sure to continue the login session after the handler

Demo

User contributed POC using Jupyter: https://github.com/tstec-polypoly/explore-keycloak

All documentation, source code and other files in this repository are Copyright 2023 Phase Two, Inc.