# Set up Keycloak one-time codes

[Read this guide on KeySigner](https://keysigner.io/integrations/guides/set-up-a-keycloak-one-time-code/)

Add a Keycloak test account to KeySigner and check that Keycloak accepts a one-time code during setup and at a fresh sign-in.

## Before you start

**KeySigner on iPhone or Mac with Sign-in codes**

- Use a non-admin user in a disposable Keycloak realm with the default time-based OTP policy. Have a separate realm administrator who can reset the test credential, plus the signers your KeySigner rule requires.
- [Check Keycloak availability](https://keysigner.io/integrations/setup-requirements/#provider-availability-keycloak)

## Data and access

- **Shared or checked**. Keycloak supplies the account’s enrollment. It validates the code at setup and again in the selected realm’s sign-in flow.
- **Check separately**. Different clients can use different flows or mapped roles. Check the destination app and any existing sessions separately.

## 1. Prepare one test user

In the Keycloak Admin Console, open your test realm and select Users. Open a non-admin test user, add Configure OTP under Required User Actions, and save. Open the Keycloak Account Console for that realm and sign in as the test user to see the setup QR code. Keep the QR code private.

**Check.** The same realm’s Account Console shows the setup QR for the intended test user.

## 2. Add the account in KeySigner

Open Accounts, then Add (+) and Sign-in codes and backup. Unlock Sign-in codes, choose Add account, and scan the QR code. In Review account, check the issuer, test username, and time-based type before you choose Confirm and add.

**Check.** Confirm the account list shows your Keycloak test entry with the expected issuer and username.

## 3. Confirm the code in Keycloak

Choose Show code in KeySigner. If prompted, set up a personal signing rule and enable signer protection. Complete the required approvals and enter the current code in Keycloak. Give the authenticator a recognizable name and finish setup.

**Check.** The enrollment screen closes after accepting the code and the test user’s account lists the named authenticator.

## 4. Try a fresh sign-in

Keep your original browser session open. Sign in to the same realm in a separate private browser window. When Keycloak asks for a One-time code, approve a fresh code in KeySigner and enter it before it expires.

![Keycloak sign-in form for the test realm with an empty One-time code field.](https://keysigner.io/integrations/guides/set-up-a-keycloak-one-time-code/keycloak-code-prompt.png)

One-time code prompt in a local Keycloak 26.8.2 test realm.

**Check.** The private browser window prompts for a code. An incorrect code leaves that prompt in place. A fresh valid code opens the account.

## Check your result

Keycloak accepts the enrollment code and opens the Account Console after you enter a fresh code.

### What we tested

**Tested on November 17, 2026.** We used the KeySigner vault and a browser against a local Keycloak 26.8.2 test realm. Keycloak accepted the enrollment code and a fresh sign-in code, and rejected an incorrect code.

[How to verify your setup](https://keysigner.io/integrations/verify-a-setup/)

## If you get stuck

### Keycloak does not ask for a code

Verify that the test user has an OTP credential and that the realm’s active browser flow asks that user for a code. If a code is rejected, check the account and device clock. Use the replacement guide when you need to remove a test credential and set up a new one.

- [This setup key is too short. Ask the service for a key of at least 16 bytes.](https://keysigner.io/integrations/setup-messages/#setup-key-too-short)
- [The code expired. Generate another code.](https://keysigner.io/integrations/setup-messages/#code-expired)

## Tools in this guide

- [Keycloak](https://keysigner.io/integrations/keycloak/)
  - [Review realm and administrator settings](https://www.keycloak.org/docs/latest/server_admin/)
  - [Setup requirements](https://keysigner.io/integrations/setup-requirements/#keycloak)

## Setup instructions

- [Set a required action for one Keycloak user](https://www.keycloak.org/docs/latest/server_admin/#proc-setting-required-actions_server_administration_guide)
- [Replace a Keycloak one-time code and verify the old code](https://keysigner.io/integrations/guides/replace-a-keycloak-one-time-code/)
- [Reset a Keycloak one-time code](https://www.keycloak.org/docs/latest/server_admin/#proc_creating-otp_server_administration_guide)
- [Set up codes for other test accounts](https://keysigner.io/integrations/guides/set-up-a-time-based-sign-in-code/)
- [Check authenticator app policies](https://keysigner.io/integrations/guides/check-authenticator-app-policies/)
- [Test the same reviewer account in Gerrit](https://keysigner.io/integrations/guides/test-a-gerrit-sign-in-code/)
- [Test a Keycloak-backed Smallstep certificate request](https://keysigner.io/integrations/guides/test-a-smallstep-certificate-request/)
- [Test Kubernetes access with a KeySigner code](https://keysigner.io/integrations/guides/test-kubernetes-access-with-keycloak/)

[More guides for this task](https://keysigner.io/integrations/tasks/set-up-sign-in-codes/)
