Two-factor authentication Rest API

Extending the server
1

Hi there!
During the implementation of keycloak for our services with REST API, we encountered a problem with setting up two-factor authentication via REST. Is there any way to get the QR code without accessing the keycloak login page (we have our own login page UI)?

2

are you looking at enabling 2FA for a user using rest api, if so it should be as simple as setting up mandatory action “configure_otp” for the user.

i guess this rest call can do it

curl ‘http://localhost:8080/auth/admin/realms/test/users/c8e1f8d2-3c30-4e14-bd2e-ba4d1faf2193’
-X ‘PUT’
-H ‘Connection: keep-alive’
-H ‘Accept: application/json, text/plain, /’
-H ‘DNT: 1’
-H 'Authorization: Bearer ’
-H ‘User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/86.0.4240.75 Safari/537.36’
-H ‘Content-Type: application/json;charset=UTF-8’
-H ‘Origin: http://localhost:8080’
-H ‘Sec-Fetch-Site: same-origin’
-H ‘Sec-Fetch-Mode: cors’
-H ‘Sec-Fetch-Dest: empty’
-H ‘Referer: http://localhost:8080/auth/admin/master/console/’
-H ‘Accept-Language: en-US,en;q=0.9’
–data-binary ‘{“id”:“c8e1f8d2-3c30-4e14-bd2e-ba4d1faf2193”,“createdTimestamp”:1603179101242,“username”:“user1”,“enabled”:true,“totp”:false,“emailVerified”:false,“disableableCredentialTypes”:[],“requiredActions”:[“CONFIGURE_TOTP”],“notBefore”:0,“access”:{“manageGroupMembership”:true,“view”:true,“mapRoles”:true,“impersonate”:true,“manage”:true},“attributes”:{}}’
–compressed

3

Hi, I would like to know if there are any rest call to verify the totp value of a authenticated user. It is for verify some importants request such as payments. Best regards

1 Like
4

No standard SPI call for TOTP verification. But you can create your own REST API to do it.

Refer this,
https://www.keycloak.org/docs/latest/server_development/#_extensions

5

Hello!

I understand your challenge with implementing two-factor authentication via REST API without accessing the Keycloak login page. While Keycloak doesn’t natively provide a REST endpoint for generating QR codes for 2FA setup, I’d like to recommend a custom extension that might help solve your problem.

Take a look at the khode-two-factor-auth extension: GitHub - chornthorn/khode-two-factor-auth: khode-two-factor-auth is a Keycloak extension that provides a REST API for managing Time-based One-Time Password (TOTP) authentication. This extension allows you to set up, verify, enable, disable, and validate TOTP for users in a Keycloak realm.

This extension provides additional REST endpoints for Keycloak, including one that allows you to generate QR codes for two-factor authentication setup without needing to access the Keycloak login page. It’s designed to work with custom login page UIs, which seems to fit your use case perfectly.

The extension offers the following features:

  1. Generate QR code for 2FA setup
  2. Verify OTP code
  3. Enable/disable 2FA for a user
  4. Check if 2FA is enabled for a user

By using this extension, you should be able to implement the 2FA setup process entirely through your own login page UI, communicating with Keycloak via REST API calls.

6

Nice plugin! This is an old thread but extending the REST API still comes up a lot so having a nice example is great!

Are all of these endpoints authenticated? It doesn’t look like the call to checkAuth is actually called, I might be missing something. Client authentication or using a service account to limit access would be great.

I wrote my own version of this (code is owned by my employer so I cannot share it, sorry); but I took the approach of authenticating with the user’s access code. e.g. Authorization: Bearer <token> and then the endpoints are always in the context of the current user instead of taking a userId value. Unless you’re specifically wanting to bulk-manage OTP credentials I’d think allowing a userId to be passed in just exposes an attack vector that’s not necessary.

1 Like
7

Thank you for your feedback! In our latest release (1.3), we’ve addressed several security concerns:

  1. All endpoints are now properly authenticated.
  2. We’ve implemented user context authentication using bearer tokens.
  3. We’ve retained the userId parameter to support dual authentication scenarios.

Additionally, in future releases, we plan to support TOTP auth for sensitive API operations. If you have any ideas or suggestions, we’d love to hear them. Please join the discussion at [feature]: TOTP-Based Secure Action Token for Sensitive API Operations · Issue #1 · chornthorn/khode-two-factor-auth · GitHub