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

AccountSigns in with
Built-in adminPassword. Created at the first start, see Install.
Local user TeamPassword, plus an optional second factor.
SSO user EnterpriseYour identity provider. The second factor, if any, is the one of the identity provider.
Service account TeamAPI tokens only, never a password, see Service accounts and tokens.

Passwords

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

  1. Open My profile and start the two-factor setup.
  2. Scan the QR code with your authenticator app, or type the secret shown under it.
  3. Enter the 6-digit code the app shows to confirm.
  4. 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

Good to know

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:

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

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

  1. In your identity provider, register an application of type web, with the redirect URI
    https://kcm.example.com/login/oauth2/code/{registrationId}
    where {registrationId} is the identifier you give the provider in KCM.
  2. 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.
  3. Optional: scopes (default openid,profile,email), user name attribute, logout URI, and explicit endpoints when the issuer has no discovery document.
  4. Enable the provider: a button with its label appears on the sign in page.

SAML 2.0

  1. In your identity provider, create a SAML application with the Assertion Consumer Service URL
    https://kcm.example.com/login/saml2/sso/{registrationId}
    and the service provider entity id you choose.
  2. 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.

Reverse proxy and Ingress

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

Roles from the identity provider

KCM can read the global role from a claim of the identity provider:

Role groups from identity provider groups

Enterprise Map the groups of your identity provider to KCM role groups, so that access follows your directory:

# 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.