Magic Link login: Authenticator and Resource

Tips and tricks
,
1

Hi All,

I’ve open sourced an extension that I thought the community could use. I often see posts here asking about “Magic Link” login. I know there are a few sample and experimental implementations out there, and this is my addition.

This implementation differs from others 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, nor for the same authentication session to be active when the user clicks on the link

In my extension, there are two ways to generate a Magic Link:

  1. An Authenticator that can run in your login flow. This has a form that takes an email, looks up the User by that email, and can optionally create a user if none exists. It 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.
  2. 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. This is useful if you are building something that wants to deliver the Magic Link in another way, or simply wish to build the email in a way that Keycloak templating doesn’t support.

A variation of this code has been used in production for several months. I made a few changes in the process of preparing the code for open source, so please let me know if you find any problems.

Enjoy!

6 Likes
2

Hey there. This looks like a great implementation of this feature, but I’m having a problem with it. I seem to have everything set up as you describe, but I am getting a “401 unauthorized” error when I try to run the curl command. The only significant difference may be the version of keycloak we are running. I’m running 18 locally to test this, but you never mentioned the version you were running.

curl --location --request POST 'http://localhost:8080/realms/MagicLink_Test/magic-link' \
 --header 'Accept: application/json' \
 --header 'Content-Type: application/json' \
 --header 'Authorization: Bearer' \
 --data '{"email":"xxx@xxx.com","client_id":"magiclink-app","redirect_uri":"http://localhost:8080/realms/MagicLink-Test/account/","expiration_seconds":3600,"force_create":true,"update_profile":true,"send_email":false}'

{"error":"HTTP 401 Unauthorized"}%

Am I supposed to put something in that Bearer token spot? That would seem unintuitive given what we are trying to accomplish here, but maybe I’m missing something. Looking forward to hearing back! Thanks.

3

You must include an access token from a user with manage-users role.

Authorization: Bearer <access_token_goes_here>
4

That did it! Thank you, sir!

5

@xgp One more question. Do you think it would be possible for this magic link registration/login to take place with only a phone number rather than an email? Or would Keycloak’s internals prevent such a solution? Is my boss asking the impossible? (wouldn’t be the first time :wink: ). Thanks in advance!

6

This extension was not designed to be used with phone number. A few issues:

  1. you would have to extend Keycloak to create and lookup users based on phone number alone

  2. this extension uses an action token in the link url that would be longer than the maximum SMS length (usually 160 characters)

7

Gotcha. Thanks for the input!

8

Hi All,

Quick update on this extension. We’ve also released an Email OTP Authenticator in the same package that allows login to occur based on a 6-digit code sent to the user’s email address.

image

image

Updated documentation on how it works and how to install it in an Authentication Flow are in the Email OTP section of the README.

Templates for the emails and code form can be customized to fit your brand and messaging https://github.com/p2-inc/keycloak-magic-link/tree/main/src/main/resources/theme-resources/templates

Enjoy!

1 Like
9

Hi @xgp

You have a great implementation in the above post. I’m trying to do the same that you’ve done but cannot find the Execution type: Magic Link when creating a flow in keycloak. Can you or someone else please help me with this?

10

Please share how you have installed, configured and started Keycloak, and we will try to help you debug.

11

Hi @xgp thanks for your reply. I downloaded keycloak zip, unzipped it, and ran the standalone file in the bin directory. I’ve tried this for different versions of keycloak and still have the same issue.

12

You should probably start with this guide: OpenJDK - Keycloak

13

Hi getting error like this
{
“error”: “redirectUri http://localhost:4200/ disallowed by client.”
}

14

Provide some more context on how you got that error. What was the request you used?

If the redirect_uri you are trying isn’t registered with the client, that is an expected result.

15

it’s working. my bad. sorry

16

Hey @xgp , I am really impressed by your work and it really helped. I do have one question here - can we add the username in the token that is being generated in the magiclink url?

Thanks in advance.

17

Why do you need the username?

Post bugs and requests for enhancements here: Issues · p2-inc/keycloak-magic-link · GitHub

18

@xgp , thanks for your reply. I need the username because in my application, we are using username as unique identifier. From there all the logic begins so that is like the starting point of how our application works. We are currently using Salesforce/Google/Microsoft login and extracting the username for the JWT.

19

As I posted in the issue, I see no argument for adding it. The action token is built exclusively for the action token handler. If you’re using that token for something else, I think you should reevaluate your use of the extension.

1 Like
20

I get it. Thanks for clarifying.