Phone-OTP registration and login, out of the box #27152

Nefcanto · 2024-02-20T08:12:36Z

Nefcanto
Feb 20, 2024

Idea

Since phone-OTP login is becoming so widespread, why not have it available out of the box instead of teams spending money and time on it?

Backstory

We chose Keycloak a couple of years ago and everything is awesome now.
Now we want to add phone-OTP to it. Our team is a React/dotnet developer mix; nobody knows Java.
We can't afford to hire a Java developer only to create that phone-OTP plugin.

We tried to outsource it as a project two times and both times we failed. Once they gave us a code written for Keycloak 14 (while we're always updated) and refused to update it, the other did not help us install it and we could not use it at last.

So we decided that maybe we can give it a shot, and we're stuck at building a plugin for it. The reason is that it has its own ecosystem of almost everything, the build tool becomes Maven, the language becomes Java, the IDE of tutorials is not VS Code, and many more differences.

So now we do need this feature, and yet we can't make it work unless we spend more resources than we can afford.

Expected behavior

Users go to example.com and navigate the site.
They want to go to a private part which is behind login
The example.com redirects them to accounts.example.com, which is an instance of the Keycloak
What they see is a form, with a single field. It's called "Phone number". A hint might say "Please enter your phone number
". There is no validation other than the characters should be numbers or the plus sign.
They enter their phone numbers.
They hit the "Send Code" button.
The Keycloak receives the phone number and checks the database. The phone number should be treated as the "username"
An OTP or TOTP should be created. That OTP should be sent to an API that is configured via the Keycloak's Admin Panel.
That OTP should be stored for the current user in the database.
That API would deliver the OTP to the owner of that phone number (this part is on developers to implement)
The UI goes to the next form. It's a form with one field called "Code" and a hint that says "Please enter the code you received". It shows the recipient number and has a way to change the number. It also shows a timer to enable re-sending the code.
They enter the code they have received and hit "Sign in".
If no user exists for this phone number, a user will be created (with a null password)
Keycloak receives the code. Keycloak knows the current user from the context (maybe via a Cookie, or the phone number is also sent again, or in any other form).
Keyclaok checks the OTP. If it's valid, it signs the user in.
The user would be redirected to example.com, and the rest of the flow is like other flows

This is an example of the first form:

This is an example of the second form:

Solution

I guess the phone part is very easy. It's just similar to email.
However, the OTP part is not similar to SMTP configuration, as there are a lot of different SMS providers each with its own API contract.
So, for the second part, I think it could be a very reasonable solution to create a middle API.

In other words, the Keycloak would be configured to send the OTP (or TOTP) to a middle API which we write and pass all the necessary data to that API, and then we can easily call our own SMS providers from that API.

This way all we have to do is to give it a URL and specify an HTTP method (GET or POST, and POST by default).

Some notes

A phone number can be entered in multiple ways. With or without the initial plus sign, with or without spaces, and sometimes with or without the prefix code. And since each means a different user, having a normalization is a MUST. The E.164 standards can be a good standard for this purse. Yet the UX should not be diminished. The user should be able to enter his phone number however he wants, as long as it's valid for sending the code.
The phone/code login is similar to the upsert commands in databases and frameworks. If new records exist, they will be inserted, otherwise, they will be updated. There is no difference in UI and UX between "sign-up" and "sign-in" forms.
Since sending codes through SMS incurs costs, companies might choose to allow phone/password flow too.
Since there are myriads of SMS providers out there, it's impossible for Keycloak to deliver the code. Instead, Keycloak can call an external API that is configured via the admin panel. The call could be a GET or a POST, with two parameters; The phone number, and the code. Example configured URLs could be:

https://api.external-domain.tld/sendCode?phoneNumber=+1111111&code=2323
https://example.com/api/deliverOtp?phone=+111111&otp=2323
https://subdomain.example.info/some/long/path/sms?number=+111111&token=2323

The whole purpose of phone/code login is to simplify entry at the cost of accepting risks. I know Telegram has it because I use it. But if I'm not wrong, Whatsapp, Viber, Uber, TikTok, and some other well-known apps have phone/code login. So adding a captcha anywhere reduces this simplicity and would act counterproductively. However, measures should be taken to prevent brute-force attacks for entering codes.
The length of the code can be configured via the admin panel. The code should be only numeric. No alphabetical characters in the code. Just numbers. And it should be limited to the average memory capacity for human begins (5 to 9 I guess)

darius-m · 2024-02-20T15:04:39Z

darius-m
Feb 20, 2024

Does phone-OTP mean sending OTPs through SMS? If so, it's not implemented by default in Keycloak since SMS is inherently insecure (there is no encryption taking place, SIM cards can be stolen through various attack vectors such as user impersonation when interacting with the phone company, and so on) and its use has been discouraged for quite some time. I think that there are some plugins that are publicly available that could take care of sending OTPs through either SMTP or SMS, but I have not tested them myself. Other means of authentication such as OTP applications and various forms of WebAuthn (including passkeys, which can be set up using a phone) are more secure and are supported.

0 replies

Nefcanto · 2024-02-20T17:05:59Z

Nefcanto
Feb 20, 2024
Author

@darius-m, I didn't know that. So, are you telling me that Telegram is insecure for having this type of login? Or is Google insecure for SMSing its OTP as an option?
I'm not a security expert. However, I've seen countless examples of applications (big ones) sending OTP via SMS.

0 replies

darius-m · 2024-02-20T23:03:18Z

darius-m
Feb 20, 2024

Of course, you need to consider who your clients are, what attack vectors are possible, what would be the use-case of the application. Sending OTPs through SMS is less secure than OTPs generated locally or WebAuthn, over all, but some applications may not require enforcing such best practices.

In some cases it does make sense to provide a solution that trades security for accessibility, such as Google's. Since Google offer their services to masses of users, it does make sense for them to offer SMS as an option, assuming not all users may not have easy access to smartphones, for example. And while I have not verified this, I assume that SMS OTPs have also been implemented for quite some time, and have been kept in place for legacy reasons (among other reasons).

Overall, SMS OTPs are better than using single-factor authentication, but I don't think it's something newer applications would normally strive to add. It does make sense to implement in some cases, and that's why Keycloak offers the option to extend its functionality through SPIs.

0 replies

Nefcanto · 2024-02-21T05:05:22Z

Nefcanto
Feb 21, 2024
Author

@darius-m, thank you for the explanation. Are you a member of the Keycloak team?

I think just as you mentioned that use cases are different, a built-in SMS OTP provider would be much better than a third-party or homemade SMS OTP provider. At least the guys in Keycloak are masters in security and make it as secure as they can.

I searched for third-party plugins, and I found https://github.com/FX-HAO/keycloak-phone-authenticator. The last commit was 3 years ago. That's a big problem right there.

You want to help secure the community and you have done a great job. Yet for a small business that wants security and needs to send OTP via SMS to facilitate customer acquisition to reduce marketing costs, it's better to have an out-of-the-box option rather than letting them create it themselves with less security and more costs.

Don't you agree?

2 replies

darius-m Feb 21, 2024

I'm not a member of the team. I have stated what I have gathered as reasons against using SMS codes in modern SSO deployments from various sources. There have been some discussions (e.g. #20859, #11562, #11762) that have either provided similar reasons or have not been addressed. I do agree that having an official implementation would be better from a security standpoint, but even apparently simple features introduce quite a bit of overhead in both implementation and maintenance.

Nefcanto Feb 21, 2024
Author

@darius-m, thank you for the links. I read them and realized that there is an attack called SIM Swap in which the attacker tries to redirect the network connection to his mobile phone and it possibly requires convincing the Cell Phone Operator by direct talk.

I know that for a president this attack can be deadly. But for a simple online shop, nope. Our customers want this feature and we can't deliver. We would be able of course, but with a lot of time and effort and a lot of resources spent on this.

So, Keycloak can provide it out of the box with warnings about its lower security and we would use it at our own risk. That's much better than a widespread of insecure vulnerable tries by each team and each person.

Nefcanto · 2024-02-21T05:39:36Z

Nefcanto
Feb 21, 2024
Author

@darius-m, I found another repository full of examples:

https://github.com/thomasdarimont/keycloak-extension-playground

Yet again, see the last commit. It was 2 years ago. This, in my opinion, is a higher risk than SMS. A stale codebase is very bad. We have a rule in our team that we update every week, 4 times per month. We constantly apply security patches and keep staying on LTS versions. I don't feel OK for a code that has not been updated for 2 years.

0 replies

codespearhead · 2024-10-12T16:54:12Z

codespearhead
Oct 12, 2024

In my opinion, this discussion should remain open because requests for SMS and Email 2FA/MFA come up quite often, so it's a good idea to centralize and catalog the use cases here.

As for the proposition itself, unless you can make a case for it in a non-MFA authentication setting—such as the sign-up process some Brazilian banks use, where they rely on SMS and email to confirm ownership before enabling an actual secure authentication method for login, which is usually face biometrics, it’s not a good idea. As Okta states:

SMS-based two-factor authentication [01] shows up as an option on many websites, but in some cases, it’s worse than not having a second factor at all! [02]

In 2016, the National Institute of Standards and Technology (NIST) started indicating that it no longer considered SMS secure [03], and recommended deprecating this option as a method of MFA. While they have since softened their stance to an extent, it’s still clear that SMS was not designed with the intent to securely transport data [04]. While SMS OTP is easy to deploy because everyone has a phone, it’s not truly a secure way to access accounts. [05]

Many companies, such as Evernote [06], Twitter [07], and Microsoft [08], are on the path to discontinuing SMS-based 2FA. They recognize that the cost of sending SMS messages and the increased risk of user attacks are not worth the convenience it provides.

The same concerns apply to email-based 2FA. Although it is less vulnerable and cheaper than SMS-based methods, it still has the disastrous side effect of enabling a hacker to permanently lock a user out of their account if they gain control of the user's email (personal email, not business email) or clone their SIM card. These are far easier to obtain remotely than if the user relied solely on a username and password, which wouldn't expose them to the risks Okta highlighted (assuming those credentials weren’t leaked—something secure 2FA methods were designed to prevent in the first place).

Once hackers gain control, they are free to carry out scams on behalf of the user for months, which is particularly common on Instagram [09].

[01] https://www.okta.com/blog/2020/10/sms-authentication/
[02] https://sec.okta.com/articles/2020/05/sms-two-factor-authentication-worse-just-good-password
[03] https://pages.nist.gov/800-63-3/sp800-63b.html
[04] https://www.cnet.com/how-to/sim-swap-fraud-what-it-is-why-you-should-care-and-how-to-prevent-it/
[05] https://www.okta.com/blog/2020/05/why-you-should-ditch-sms-as-an-auth-factor/
[06] https://discussion.evernote.com/forums/topic/147112-we-are-removing-sms-as-a-two-factor-authentication-method/
[07] https://blog.x.com/en_us/topics/product/2023/an-update-on-two-factor-authentication-using-sms-on-twitter
[08] https://www.reddit.com/r/sysadmin/comments/16irazw/microsoft_removing_sms_mfa_auth_entirely_starting/
[09] https://www.reddit.com/r/InstagramMarketing/comments/15jzcru/instagram_account_hacked_and_phone_number_and/

0 replies

Nefcanto · 2024-10-13T09:33:14Z

Nefcanto
Oct 13, 2024
Author

@codespearhead, thanks for sharing your thoughts. The point here is not to insist that Phone/OTP is a good or secure method of signing in the users. Nobody insists on that. The points are:

Extending Keycloak is expensive. Because it requires hiring a Java developer or outsourcing a project to a Java developer, which for many small teams like us is not affordable or fails. So, Keycloak must make extending it easier, like for example providing a way for us to extend login via API, or via other technologies if it's mission is helping teams become more secure.
While Phone/OTP login is not secure for a corporation like Microsoft, it's OK for a school in a town. It's very easy. It prevents the overhead of MFA. It's widespread (Web, android, iOS, Windows, ...). Small companies don't have enough budget to buy A-level security. If Keycloak belongs to the community, it can create some less-than-A-level security alternatives, with a lot of warnings all over the place to make sure that it has done its job.
Security is not prescriptive. It won't work. Security is descriptive. People use and consume things that fit the market. It's not like saying I'm your boss, I know what's secure, thus silence and obey. It's more like People do use X & Y. What can we do to make the overall market more secure?. That's the philosophy behind LetsEncrypt. Because SSLs were expensive. Most people didn't buy it. So that's the solution. An official phone/OTP plugin is way more secure than a home-made attempt.

1 reply

vvvin333 Feb 17, 2025

Let's suggest this method at least for verification of the user phone (in addition with username+password sign up process).

jonkoops · 2024-10-13T14:31:36Z

jonkoops
Oct 13, 2024

Hi all, please reply in-thread instead of starting a new thread for every reply.

1 reply

vvvin333 Feb 17, 2025

I'd like to up this suggestion in 2025 year.

ahus1 · 2025-03-22T15:56:38Z

ahus1
Mar 22, 2025
Collaborator

The Keycloak extensions page lists

https://github.com/netzbegruenung/keycloak-mfa-plugins

which includes a SMS integration.

Note that in 2025, there are several attack vectors to SMS, as https://pages.nist.gov/800-63-3/sp800-63b.html states:

Verifiers SHOULD consider risk indicators such as device swap, SIM change, number porting, or other abnormal behavior before using the PSTN to deliver an out-of-band authentication secret.

As there are APIs to send SMS, but AFAIK no (common) APIs to receive notifications about device swap, SIM change or number porting, I don't think using SMS is a good idea in 2025.

5 replies

Nefcanto Mar 23, 2025
Author

@ahus1 that's for MFA, not for the main login (1FA) with phone/OTP.

Also, I again insist that security levels differ based on organizational sizes. Microsoft's security requirements are different from a simple school with 400 students that wants to create a pane for parents to provide educational reports. Phone/OTP is amazing for situations where security requirements are low. It's attack vectors can be accepted.

We're creating software for SMBs. None in the last 20 years I have seen an attach on any of our customers. Zero attacks.

Economically it's not viable for an attacker to attack our customers. None have anything that's valuable to them.

I still think that Keycloak should provide an official phone/OTP solution out of the box, with tons of warnings.

ahus1 Mar 23, 2025
Collaborator

Thank you for the added details. So it seems you want to have something like magic link via email, but with SMS? There is a community extension for magic link, see https://github.com/p2-inc/keycloak-magic-link (again, it is listed on the KC community extensions page)

I didn't see this discussion to get much traction or upvotes here from the community, nor an extension listed in the community extensions.

I understand that you want this solution, still I'm lacking information how it would work, what corner cases there would be, and what the advantages and differences to a magic link would be. The text "Since phone-OTP login is becoming so widespread" doesn't reveal to me that you wanted it to be the main login.

One way to make a case for that would be to describe the functionality you want to see in more detail in the description at the top, and compare it to other alternatives for your scenario. Still, there is no guarantee that there will be volunteers to implement it in Keycloak core, or as an extension.

Nefcanto Mar 24, 2025
Author

@ahus1 thank you for the time. I'll do my best to describe the flow:

Users go to example.com and navigate the site.
They want to go to a private part which is behind login
The example.com redirects them to accounts.example.com, which is an instance of the Keycloak
What they see is a form, with a single field. It's called "Phone number". A hint might say "Please enter your phone number
". There is no validation other than the characters should be numbers or the plus sign.
They enter their phone numbers.
They hit the "Send Code" button.
The Keycloak receives the phone number and checks the database. The phone number should be treated as the "username"
If no user exists for this phone number, a user will be created (with a null password)
An OTP or TOTP should be created. That OTP should be sent to an API that is configured via the Keycloak's Admin Panel.
That OTP should be stored for the current user in the database.
That API would deliver the OTP to the owner of that phone number (this part is on developers to implement)
The UI goes to the next form. It's a form with one field called "Code" and a hint that says "Please enter the code you received". It shows the recipient number and has a way to change the number. It also shows a timer to enable re-sending the code.
They enter the code they have received and hit "Sign in".
Keycloak receives the code. Keycloak knows the current user from the context (maybe via a Cookie, or the phone number is also sent again, or in any other form).
Keyclaok checks the OTP. If it's valid, it signs the user in.
The user would be redirected to example.com, and the rest of the flow is like other flows

This is an example of the first form:

This is an example of the second form:

ahus1 Mar 26, 2025
Collaborator

@Nefcanto - thank you for the details. I see you added it as a comment while I asked you to update the description above. I copied the contents to the description at the top.

I have a some questions. Please update the description at the top (!).

"There is no validation other than the characters should be numbers or the plus sign."
-> you will probably need a normalization of phone numbers as people might enter a phone number with or without a plus sign at the start. Or should all phone number start with "+"?

"If no user exists for this phone number, a user will be created (with a null password)"
-> I suppose a user entry should be created only after the code has been entered and when the user doesn't exist. Otherwise you might end up with a lot of dummy users that never logged in in your database. If we agree on that, then please move it further to the end.
-> Why would you write "with a null password"? Are there different methods to sign in except with an SMS code?

"An OTP or TOTP should be created. That OTP should be sent to an API that is configured via the Keycloak's Admin Panel."
-> I think that is an implementation detail, and shouldn't be described here. There might be different ways to implement that. Maybe the code is only generated as part of the login flow. Please remove or rewrite.

"That OTP should be stored for the current user in the database."
-> Again, an implementation detail. Shouldn't be listed in the behavior.

"That API would deliver the OTP to the owner of that phone number (this part is on developers to implement)"
-> can you provide an example of how an API to send SMS could look like? Would a GET request with a URL and some placeholders be enough?

"Keyclaok checks the OTP"
-> Please rename OTP to code, as this is also what the UI shows. OTPs have a different meaning in Keycloak

Would we need a protection that too many people try random SMS codes? Would we need a captcha for that?

cc:: @srose

Nefcanto Mar 29, 2025
Author

@ahus1 I updated the description above. However, I added answers as "some notes". And I did not remove the code creation steps, because I don't think that they are implementation details. They are part of the flow. It's similar to payment gateway flow. Codes are mentioned in the flow. Or similar to the OAuth flow in which tokens are mentioned. Thank you.

ryan-morris · 2025-06-06T19:14:44Z

ryan-morris
Jun 6, 2025

I have 2 primary use cases which sort of align with this thread, and this seems to be where SMS related questions are being pointed.

We have various applications users login to. Some of those applications support SMS based notifications. We have added a field on the users profile within keycloak to get their phone number. Unfortunately there is no mechanism built into keycloak for the ability to verify the phone number. Better support for a phone number field and the format of the value that gets stored would be a plus (enforcing e.164 format)
In regards to MFA via SMS, I understand and mostly agree with Phone-OTP registration and login, out of the box #27152 (comment). I wouldn't even consider but I get a lot of push back on the "not secure" front, usually in the context of how their bank lets them do it so it must be "secure enough". In my use case I wouldn't want phone number based login or recovery, strictly MFA support which I think alleviates some of the attack vectors. If SMS is strictly used as a second factor, while not entirely secure, at least an attacker would still need to get a hold of username/password as well.

I think if there could be a facility for SMS built-in and some enhancements around phone numbers, even if it was non-functional without a provider via a plugin being present (twilio/aws/azure/etc) that may alleviate some of the maintenance burden. That would allow for case 1, and based on risk level someone running keycloak is willing to accept supports case 2.

If sponsoring specific features is an option, I think my company may be open to that. If not and there's a vendor with a decent track record of successfully getting features into keycloak via PR I'd appreciate any suggestions.

0 replies

YandyZaldivar · 2025-08-08T11:37:06Z

YandyZaldivar
Aug 8, 2025

Phone OTP doesn't need to be SMS where security may be a concern, this is a much needed use case and should be intended to serve as a main authentication flow. One example is WhatsApp authentication, every modern business is supporting authenticating via WhatsApp and KeyCloak is lagging behind.

See #37671

0 replies

gillg · 2025-08-20T11:42:29Z

gillg
Aug 20, 2025

@YandyZaldivar I like your last idea as compromise, but I have a different use case not working.

The context would be for an association, where members (not necessarily familiar with computers and security...) needs to authenticate in a simple way (avoid passwords to manage, remember, rotate + having a way to invite them by phone number as primary way). Every year admins can decommission or deactivate accounts.

Ideally a WhatsApp/telegram like login would be great.
But, the backend app would be a mattermost to avoid Whatsapp (and other GAFAM options) what is big source of ethical debates... So Whatsapp can't be used as login source.

Any idea for something else than SMS ?

0 replies

This comment was marked as disruptive content.

Sign in to view

Phone-OTP registration and login, out of the box #27152

Uh oh!

Uh oh!

Idea

Backstory

Expected behavior

Solution

Some notes

Replies: 13 comments · 9 replies

Uh oh!

Uh oh!

Nefcanto Feb 20, 2024 Author

Uh oh!

Uh oh!

Nefcanto Feb 21, 2024 Author

Uh oh!

Uh oh!

Nefcanto Feb 21, 2024 Author

Uh oh!

Nefcanto Feb 21, 2024 Author

This comment was marked as disruptive content.

Uh oh!

Uh oh!

Uh oh!

Nefcanto Oct 13, 2024 Author

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

ahus1 Mar 22, 2025 Collaborator

Uh oh!

Nefcanto Mar 23, 2025 Author

Uh oh!

Uh oh!

ahus1 Mar 23, 2025 Collaborator

Uh oh!

Nefcanto Mar 24, 2025 Author

Uh oh!

Uh oh!

ahus1 Mar 26, 2025 Collaborator

Uh oh!

Nefcanto Mar 29, 2025 Author

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Replies: 13 comments 9 replies

Nefcanto
Feb 20, 2024
Author

Nefcanto
Feb 21, 2024
Author

Nefcanto Feb 21, 2024
Author

Nefcanto
Feb 21, 2024
Author

Nefcanto
Oct 13, 2024
Author

ahus1
Mar 22, 2025
Collaborator

Nefcanto Mar 23, 2025
Author

ahus1 Mar 23, 2025
Collaborator

Nefcanto Mar 24, 2025
Author

ahus1 Mar 26, 2025
Collaborator

Nefcanto Mar 29, 2025
Author