Sign in, two-factor and SSO
KCM accounts sign in with a password, optionally with a second factor, or through your identity provider with SSO. This page also explains how sessions end and how repeated failures are locked.
Accounts
| Account | Signs in with |
|---|---|
Built-in admin | Password. Created at the first start, see Install. |
| Local user Team | Password, plus an optional second factor. |
| SSO user Enterprise | Your identity provider. The second factor, if any, is the one of the identity provider. |
| Service account Team | API tokens only, never a password, see Service accounts and tokens. |
Passwords
- Change your password from My profile. Changing it ends all your sessions, the current one included: you sign in again with the new password.
- KCM asks for a new password at the first sign in of a user created by an administrator, after
an administrator sets a password, and for the built-in
adminwhen its password was generated. Until then, the session can only change the password or sign out.
Two-factor sign in
Every edition Local accounts can add a second factor with any authenticator app that supports time-based codes (TOTP), such as the apps of Google, Microsoft or your password manager.
Turn it on
- Open My profile and start the two-factor setup.
- Scan the QR code with your authenticator app, or type the secret shown under it.
- Enter the 6-digit code the app shows to confirm.
- Save the 10 recovery codes. They are shown once. Each one can replace an app code a single time.
From then on, KCM asks for a code after the password. Codes change every 30 seconds and each code is accepted once.
Lost phone and recovery codes
- Sign in with a recovery code instead of the app code.
- From My profile, you can generate new recovery codes (the old ones stop working) or turn two-factor off. Both ask for a current code.
- If you have neither your app nor a recovery code, ask an administrator to reset your second
factor. Nobody can reset their own, and a security administrator cannot reset an
ADMIN. The reset is recorded in the audit trail.
Two-factor sign in is per account and optional: KCM 1.5.0 has no setting to make it mandatory for everyone. Turn it on for every administrator account. Wrong codes count as failed sign ins for the locks described below.
Sessions
A session lasts KCM_JWT_TOKEN_VALIDITY seconds (one day by default). Every session of a user ends at
once when:
- the user chooses Sign out everywhere in My profile;
- an administrator ends the sessions of that user;
- the user's global role changes, including a role that comes from SSO;
- the password changes;
- the account is disabled.
With several API instances, each one refuses a revoked session within KCM_SESSION_CHECK_CACHE_SECONDS
(30 seconds by default). Grants are read on each request, so a new or removed grant applies at once, without
signing in again.
Sign in locks
- After 5 failed sign ins of one username from one address, that username is locked from that address for 15 minutes. The window restarts with each failure.
- After four times as many failures (20 by default) from any address, the username itself is locked.
- A locked attempt gets an error that says how many minutes to wait. A successful sign in clears the counter.
- Every attempt, successful or not, is recorded in the audit trail.
Change the thresholds with KCM_LOGIN_MAX_FAILURES and KCM_LOGIN_LOCK_MINUTES, see the
configuration reference.
Single sign-on (OIDC and SAML)
Enterprise Users sign in with your identity provider: Microsoft Entra ID
(Microsoft 365), Google, Okta, Keycloak or any OIDC or SAML 2.0 provider. Configure providers in
Settings > SSO providers (global ADMIN; auditors can read them).
OIDC
- In your identity provider, register an application of type web, with the redirect URI
wherehttps://kcm.example.com/login/oauth2/code/{registrationId}{registrationId}is the identifier you give the provider in KCM. - In KCM, add a provider of type OIDC. Pick a preset (Microsoft 365, Google, Okta, Keycloak)
or Custom, then fill in the issuer URI, client id and client secret. Presets fill the usual values: for
Microsoft 365, the tenant id builds the issuer and the username is
preferred_username. - Optional: scopes (default
openid,profile,email), user name attribute, logout URI, and explicit endpoints when the issuer has no discovery document. - Enable the provider: a button with its label appears on the sign in page.
SAML 2.0
- In your identity provider, create a SAML application with the Assertion Consumer Service URL
and the service provider entity id you choose.https://kcm.example.com/login/saml2/sso/{registrationId} - In KCM, add a provider of type SAML2 with the metadata URI of the identity provider, or its entity id, sign in URL and signing certificate, and the service provider entity id.
The client secret is stored encrypted and is never shown again. KCM_REDIRECT_ALLOWLIST must list the
origin of the console.
The SSO paths must reach the API: /auth/sso, /oauth2/ and /login/oauth2/
(OIDC), /saml2/, /login/saml2/ and /logout/saml2/ (SAML).
- Helm chart: SSO behind the Ingress of the chart needs chart 1.5.1 or later, which routes these paths to the API. Older charts send the return URLs to the console and the sign in fails.
- Your own Ingress or reverse proxy: forward these paths to the API, next to
/api/and/ws/v1, see Ingress and reverse proxy.
Sign in rules
- The identity provider must send an email address, not flagged as unverified.
- At the first SSO sign in, the KCM account is bound to that provider and identity. Another identity with the same email is refused.
- A user signing in for the first time is created automatically and takes a seat; when no seat is free, the sign in is refused.
- Disabled accounts and service accounts cannot sign in with SSO.
Roles from the identity provider
KCM can read the global role from a claim of the identity provider:
- Role claim:
rolesby default for OIDC; for SAML, the usual role and group claim URIs. - Admin values: a claim value in this list (default
KCM_ADMIN) makes the user a globalADMIN; any other user is aUSER. - Sync roles on: the role is applied again at every sign in. Off: the claim only sets the role at the first sign in, then the role set in KCM prevails.
- The last enabled administrator is never demoted by SSO.
Role groups from identity provider groups
Enterprise Map the groups of your identity provider to KCM role groups, so that access follows your directory:
- Groups claim:
groupsby default for OIDC; for SAML, the usual group claim URIs (Microsoft, then generic), thengroups. - Group mappings: one line per mapping,
claim value = role group name. Lines starting with#and blank lines are ignored.
# IdP group = KCM role group
kafka-payments-devs = payments-team
kafka-platform-admins = platform-admins
At each SSO sign in, KCM adds or removes the user's memberships that came from this provider so that they match
the claim. Memberships added by hand in KCM are never touched. A mapped role group that does not exist is skipped
with a warning in the log. Every change is recorded in the audit trail as ROLE_GROUP_SSO_SYNC.