Authentication

Kerberos Hub supports local password sign-in, authenticator-based two-factor authentication (2FA), passkeys, and single sign-on (SSO) through OpenID Connect (OIDC). This page explains how they work together, what users can set up themselves, and what an administrator needs to configure.

Authentication establishes who you are. It does not grant access to every camera or project: organisation and project membership and roles determine what you can see and do after signing in.

Choose a sign-in method

Available choices depend on your deployment and browser. For local accounts, enable 2FA and consider registering a passkey for everyday use. For centrally managed identities, use OIDC and enforce your organisation’s authentication policy at the identity provider.

Password sign-in

Enter your Hub username or email address and password on the login page. If the deployment uses domains, open the correct tenant URL or supply the domain requested by the login screen.

Hub stores local passwords as bcrypt hashes, not plaintext. A successful password check can be followed by a 2FA challenge or required 2FA enrollment. Password sign-in also checks account activation, the deployment’s license, and any configured account access-time window.

Change your password

While signed in, open Profile > Change password, enter your current password, enter and repeat the new password, and select Change password. This changes the local Hub password, not the password at an OIDC identity provider.

Forgotten password

On the local login form, select Forgot password, enter the account’s email address, and submit the request. Hub emails a newly generated password; this is not a reset-link flow. Sign in with the emailed password, complete 2FA if enabled, and then choose a new password in your profile.

The deployment must have working outgoing email. A password reset does not disable 2FA. For an SSO password problem, use the identity provider’s recovery process instead.

Two-factor authentication (2FA)

Hub’s built-in 2FA uses TOTP, the time-based codes generated by an authenticator app such as Google Authenticator. It is not SMS or email verification.

Enable an authenticator app

1. Sign in and open Profile > Multi-factor Authentication.
2. Select Setup Multi-factor Auth.
3. Scan the displayed QR code with your authenticator app. If scanning is unavailable, enter the displayed secret manually.
4. Enter a code generated by the app to validate the enrollment.
5. Confirm that Hub reports 2FA as enabled.

The QR code and manual secret allow an authenticator to generate your codes. Treat both as credentials: do not share them or include them in screenshots or support tickets.

On subsequent password sign-ins, enter the current authenticator code when Hub asks for it. If codes are rejected, check that you selected the correct account in the app and that the authenticator device’s clock is synchronized.

Required enrollment and disabling 2FA

An administrator can enable force MFA for an account. If the user has not enrolled, Hub presents the QR code and code-validation step after the password check instead of completing the password sign-in. Complete enrollment and sign in again.

Users can disable optional 2FA from their profile, but Hub rejects self-service disabling when force MFA is enabled. Changing this requirement is an administrator decision.

This setting governs Hub’s password/TOTP flow. A verified passkey does not trigger TOTP enrollment or an additional TOTP challenge, including for accounts with force MFA. OIDC sign-in uses the identity provider’s policy rather than Hub’s local TOTP challenge.

Authenticator label for self-hosted deployments

The Hub API’s optional MFA_ISSUER environment variable sets the issuer label in the enrollment QR code. It defaults to Kerberos.io. Set it to a recognizable deployment name before users enroll; it is a label, not a different authentication method.

Passkeys

Passkeys use the browser’s WebAuthn support to prove possession of a credential registered to your Hub account. Your device or passkey manager asks you to verify yourself, for example with a PIN, fingerprint, or face recognition. Hub requires this user verification.

A passkey sign-in does not ask for your Hub password or a separate TOTP code. It does not turn off either credential: password sign-in, with 2FA when enabled, remains available wherever the local login form is offered.

Requirements

• An administrator has configured passkeys in the Hub API as described below.
• You are using the intended Hub hostname over HTTPS, with a browser that supports WebAuthn and the Credentials API.
• Your authenticator supports discoverable credentials (also called resident keys) and user verification. The browser determines which devices, security keys, or passkey managers are available.
• You have access to your current local Hub password and, if Hub 2FA is enabled, your authenticator app when adding or removing a passkey.

Passkey management currently confirms the local Hub password, not a fresh OIDC sign-in. An SSO session alone is therefore not sufficient to enroll or remove passkeys. Do not enter your identity provider password into this confirmation form.

Passkey registration and sign-in are disabled in Hub’s demo mode.

Add a passkey

1. Sign in to your own Hub account and open Profile > Passkeys.
2. Select Add passkey and give it a recognizable name, such as Work laptop.
3. Confirm your current Hub password and, if enabled, your current authenticator code.
4. Continue to Create on your device and open the device’s passkey prompt.
5. Follow the browser or passkey manager’s instructions and approve with your device’s verification method.
6. Confirm that the new passkey appears in the list.

You can register multiple passkeys. The list shows each passkey’s name, creation date, and last-used time, or indicates that it has never been used.

Sign in with a passkey

On the local login form, open the sign-in-method menu beside the sign-in button and select Sign in with a passkey. Choose a registered passkey in the browser prompt and approve the request. You do not need to fill in the username and password fields for this flow.

Hub resolves the account from the registered credential. Passkey sign-in still checks account activation, the deployment’s license, and configured account access-time windows.

If you cancel or the request expires, start a new sign-in attempt. If the local sign-in-method menu is not shown because the page is directing you to SSO, use that deployment’s SSO flow instead.

Remove a passkey

In Profile > Passkeys, choose the delete action for the relevant passkey and confirm your current Hub password and, if enabled, your authenticator code. Removal revokes that credential in Hub; it does not disable password sign-in or 2FA.

Removing a passkey from a device or passkey manager is separate from removing its registration in Hub. If a device is lost, revoke its Hub registration using another available sign-in method.

Configure passkeys in a self-hosted deployment

Set these environment variables on the Hub API, not just the frontend:

For example:

env:
  - name: PASSKEY_RP_ID
    value: "hub.example.com"
  - name: PASSKEY_ORIGINS
    value: "https://hub.example.com"
  - name: PASSKEY_RP_NAME
    value: "Example Hub"

This is a container environment example, not a new top-level Helm values setting. Apply it through your deployment’s supported API environment configuration, then restart the API.

Use the frontend origin, not the API origin, in PASSKEY_ORIGINS: it is the browser page that creates and uses the credential. For multiple frontend origins under the same RP ID, separate the exact origins with commas. Only allow origins that should be trusted to use these credentials. HTTP is accepted only for localhost development, for example RP ID localhost with origin http://localhost:4200.

Missing or invalid RP configuration makes the passkey endpoints unavailable; it does not disable password or OIDC sign-in. Browser support alone does not mean the backend has been configured.

Choose the RP ID before enrolling users. A passkey is bound to its relying party; changing the RP ID or moving Hub to an unrelated hostname can require users to enroll new passkeys. Plan a working fallback before changing hostnames.

Single sign-on with OIDC

OIDC lets Hub delegate authentication to an identity provider such as Microsoft Entra ID, Google, or Auth0. Hub supports multiple configured SSO domains, so different email domains can select different providers.

1. Open your deployment’s login page and enter the email address associated with the configured SSO domain, or use its SSO-only login screen.
2. Select Continue with SSO.
3. Complete authentication and any MFA required by the identity provider.
4. The provider redirects back to Hub, which verifies the identity and signs in the matching Hub account.

An administrator must configure the provider’s issuer, client credentials, callback URL, and identity claim. The callback must match the provider’s application registration. The returned identity must match an existing Hub user’s email address or username; this flow does not automatically provision a new Hub user.

Set MFA and conditional-access requirements at the identity provider for SSO users. Do not assume that enabling Hub’s local force MFA setting adds a Hub TOTP prompt to OIDC sign-in.

The forceSSO domain option changes the login experience to show SSO and hide the local password form and passkey selector. It is not, by itself, an API-wide policy disabling local credentials.

See the SSO integration guide for provider configuration, domain settings, and SSO chaining when embedding Hub in another application.

Recovery and troubleshooting

Plan recovery before making an authentication method mandatory or replacing a device.

For centrally managed SSO accounts, follow your identity provider’s recovery and device-management procedures. For local accounts, keep access to the account’s email and authenticator, and consider registering another passkey on a separate trusted authenticator before losing access to the first.