Two-Factor Authentication

Logins with email and password are handled by Keycloak, the identity and access management system behind Smartchat. Keycloak can ask for a second factor after the password: a one-time code from an authenticator app on your phone. Whether this is required, and for whom, depends on how your installation is configured.

Single Sign-On

If you log in with your company’s SSO, your company’s identity provider handles authentication, including any second factor. This page applies to logins with email and password.

Authenticator apps

Any app that generates time-based one-time passwords (TOTP, RFC 6238) works, for example FreeOTP, Google Authenticator, Microsoft Authenticator, or a password manager with TOTP support.

Setting it up

When two-factor authentication is required for your account, Keycloak asks you to set it up at your next login:

1. Scan the QR code shown on the login page with your authenticator app.
2. Enter the 6-digit code the app now shows, and optionally give the device a name.

From then on, every login asks for the current code from the app after your password. If you lose access to your phone, contact your administrator, who can have you set up a new authenticator app.

How the app and Smartchat communicate

They don’t. The authenticator app never connects to Smartchat or Keycloak, and Keycloak never sends anything to the app. Both sides compute the same codes independently:

• Setup: Keycloak generates a random secret for your account and shows it as a QR code on the login page, which is delivered over HTTPS. The app reads the QR code through the camera and stores the secret on the phone. This is the only time the secret leaves Keycloak.
• Login: every 30 seconds, the app and Keycloak each derive a new code from the shared secret and the current time. You type the app’s code into the login page, and it is sent to Keycloak over HTTPS like the rest of the login form.

The app therefore works offline and sends no data of its own. Its clock must be roughly correct. Keycloak accepts the codes of neighbouring time intervals to absorb small clock differences (look-around window).

For administrators

Two-factor authentication is part of the Keycloak login flow of your installation. Depending on the configuration it is:

• required for every login with email and password,
• required only for users with a specific role, or
• asked only from users who have already set up an authenticator app.

Keycloak documents the building blocks:

• OTP policies: algorithm, number of digits and code period. The standard configuration uses Keycloak’s defaults, which every common authenticator app supports.
• Conditions in conditional flows and 2FA conditional workflow examples: how the second factor is required for all users, by role, or only once configured.
• Required actions: how a user is asked to set up an authenticator app at the next login.
• Creating an OTP: how to make a user set up a new authenticator app, for example after losing their phone.