Digitalboard/docs
5
1
Fork 0
Code Pull requests 1 Activity Actions
docs/keycloak/enforce-otp-internal.md

4.1 KiB
Raw Permalink Blame History

Enforce OTP (TOTP) 2FA for Internal Users in Keycloak

Goal: Enforce OTP-based two-factor authentication (2FA) for internal users managed inside Keycloak in the Digitalboard realm, while external users coming from Microsoft Entra ID as Identity Provider are not prompted for OTP.

Prerequisites

  • Admin access to the Keycloak Admin Console for the Digitalboard realm.
  • A running Keycloak instance (TLS termination handled by Traefik or Keycloak itself).
  • Microsoft Entra ID already set up as an Identity Provider for the realm.
  • Internal users stored directly in Keycloak (username/password authentication).

Steps

Step 1 — Verify External Identity Provider

  1. In the Digitalboard realm, open the Admin Console.
  2. Navigate to Identity Providers.
  3. Confirm that Microsoft Entra ID is configured (OpenID Connect or SAML).
  4. Ensure that external users sign in via this IdP.

Step 2 — Configure OTP Policy

  1. In the left-hand menu of the Digitalboard realm, go to Authentication → OTP Policy (or Realm Settings → Security Defenses → OTP Policy, depending on Keycloak version).
  2. Configure the following:
    • Type: totp (time based)
    • Digits: 6
    • Period: 30 seconds
    • Algorithm: sha512
    • Look ahead window: 1-2
    • Reusable token: off

Click Save.

Step 3 — Copy the Browser Flow

  1. Navigate to Authentication → Flows.
  2. Locate the built-in Browser flow.
  3. Click Copy.
  4. Enter the new name: browser-internal-otp.

This custom flow will handle internal (local) user logins for the Digitalboard realm.

Step 4 — Add OTP Requirement

  1. Open the browser-internal-otp flow.
  2. Inside the Browser Forms sub-flow, locate the Username Password Form.
  3. After it, click Add execution → select OTP Form (or Conditional OTP if available).
  4. Set requirement to Required.

This ensures OTP is enforced for all username/password logins (internal users).

Step 5 — Enable “Configure OTP” Required Action

  1. In the Digitalboard realm, go to Authentication → Required Actions.
  2. Locate Configure OTP.
  3. Ensure the status is Enabled.

With this enabled, internal users without an OTP configured will be prompted to set it up during login.

Step 6 — Bind the Flow

  1. In the Digitalboard realm, go to Authentication → Flows.
  2. Click the flow browser-internal-otp to open it.
  3. In the top-right, open Actions → Bind flow.
  4. In the dialog, choose Browser flow and click Save.

This makes browser-internal-otp the default Browser flow, so internal (local) users who log in with username/password must use OTP.

Important for external (Entra) users:

  • Go to Identity Providers → (Microsoft Entra) and ensure Post Login Flow / Post Broker Login Flow is None (or a flow without OTP), so external users don't get a Keycloak OTP prompt after IdP login.

Step 7 — Test the Setup

  1. Log in with an internal Keycloak user in the Digitalboard realm:
    • After entering username and password, you should be prompted for OTP (or OTP setup if not already configured).
  2. Log in with an external Microsoft Entra user:
    • You should be redirected to Entra ID for login.
    • After successful login, you should be signed in without an additional OTP prompt from Keycloak.

Troubleshooting

  • External users see OTP prompt: Check that Post Broker Login Flow is not set to browser-internal-otp.
  • Internal users not asked for OTP: Verify that the OTP Form is present in browser-internal-otp and set to Required.
  • Looping on OTP setup: Ensure realm time synchronization (NTP) and correct OTP policy values.

Next Steps

  • Roll out OTP to internal users gradually (pilot group).
  • Provide instructions for enrolling an authenticator app (Google Authenticator, Microsoft Authenticator, FreeOTP).
  • Monitor login events in the Digitalboard realm to confirm expected OTP usage.