Skip to main content
ALTCHA®

Admin sign-in & SSO

Administrators sign in to the admin UI and the management API with a password, through an OAuth provider, or against an LDAP directory, optionally followed by a second factor. This page explains each method, what you configure in [auth], and how sessions behave.

API keys don't sign in; they authenticate the widget and server endpoints. See API keys & access levels.

How sign-in works

StepPasswordLDAPOAuth
1. Prove a browser did workLogin ALTCHALogin ALTCHA— (the provider handles it)
2. Check credentialsPOST /v2/auth/loginPOST /v2/auth/ldapGET /v2/auth/oauth/{provider} and its callback
3. Second factor, if the user has oneTOTP code or passkeyTOTP code or passkeyTOTP code or passkey
4. Sessionjwt cookie and tokenjwt cookie and tokenjwt cookie

The login page asks GET /v2/app-config, which needs no credentials, which methods to offer:

curl https://sentinel.example.com/v2/app-config
{
  "data": {
    "authMethods": [
      { "type": "password", "passwordMinLength": 8 },
      { "type": "ldap", "name": "Corp LDAP" },
      { "type": "oauth", "name": "Corp SSO", "provider": "keycloak", "url": "https://sentinel.example.com/v2/auth/oauth/keycloak" }
    ],
    "loginAltcha": true,
    "passkeys": true,
    …
  }
}
  • password is listed while password login is on.
  • ldap is listed when [auth.ldap] is configured and the license includes ldap.
  • One oauth entry is listed per configured provider, in the order azure, google, keycloak, okta, when the license includes oauth. name is the button label; url starts the login.
  • loginAltcha is false only with [auth] verify_altcha = false.
  • passkeys is whether passkeys are available.

Every sign-in attempt is written to the audit log (auth.login, auth.ldap, auth.oauth, auth.otp, auth.passkey).

Password sign-in

The bootstrap root user signs in with a password. On the first start, Sentinel creates it with [bootstrap] root_password, or with a random password that it logs once. See [bootstrap]. Root users create further users in Users; see Managing accounts & users.

Login ALTCHA

Password and LDAP sign-in are guarded by an ALTCHA proof-of-work, which slows down password guessing. The admin UI solves it automatically. Script clients do the same in three calls:

  1. Get a challenge. It expires after 5 minutes.

    curl https://sentinel.example.com/v2/auth/challenge
    {
      "parameters": {
        "algorithm": "PBKDF2/SHA-256",
        "cost": 5000,
        "expiresAt": 1795080696,
        "keyLength": 32,
        "keyPrefix": "e5527680d8cc03e18192d374d43cf839",
        "keySignature": "e866…b152",
        "nonce": "c06826bf97f3712ef562ffd4db4b5cd3",
        "salt": "05b683fbfeb6b52b9a7d19003ac4b2b2"
      },
      "signature": "45ed…0a60"
    }

    This response has no { "data": … } envelope: it's the challenge exactly as the ALTCHA widget expects it.

  2. Solve it with the ALTCHA widget or an ALTCHA library. The result is the widget's payload: base64 of {"challenge": …, "solution": …}.

  3. Sign in with the payload in altcha:

    curl https://sentinel.example.com/v2/auth/login \
      -H 'Content-Type: application/json' \
      -d '{ "username": "root", "password": "…", "altcha": "eyJjaGFsbGVuZ2UiOnsi…" }'

    Without a second factor, the response sets the session cookie and returns the token:

    HTTP/1.1 200 OK
    set-cookie: jwt=eyJ0eXAi…; HttpOnly; Secure; SameSite=Strict; Path=/; Max-Age=86400
    
    {"data":{"jwt":"eyJ0eXAi…"}}

Each solved payload works once; fetch a new challenge for every attempt. The common failures:

HTTPCodeMeaning
400INVALID_ALTCHA_PAYLOADaltcha is missing or isn't a payload.
403ALTCHA_VERIFICATION_FAILEDThe solution is wrong, expired, or already used.
401INVALID_CREDENTIALSUnknown user, wrong password, or a user without a password. The response doesn't say which.
403USER_DISABLEDThe password is right, but the user is deactivated.

The full list is in Error codes. [auth] verify_altcha = false turns the login ALTCHA off; use it only in tests.

The admin UI solves the ALTCHA with the browser's Web Crypto API, which browsers offer only on HTTPS, localhost, and 127.0.0.1. Over plain HTTP on any other address, the login page offers only OAuth.

Password policy

Passwords are 8 to 256 characters. They aren't trimmed, and there are no composition rules. Sentinel stores only a hash.

Users change their own password under User profile → Change password in the user menu, or with POST /v2/me/password. The change signs out every session of the user, including the current one, and returns a new token. Users who sign in through LDAP or OAuth have no password and get 403 PASSWORD_NOT_SET.

Two-factor authentication

A user with TOTP or at least one passkey gets no session from the first step. The response names the factors the user can finish with:

{ "data": { "otp": true, "otpJwt": "eyJ0eXAi…", "methods": ["totp"] } }

The client then sends a TOTP code or a passkey assertion with the otpJwt. The otpJwt is valid for 10 minutes, and 5 failures (wrong codes and rejected passkeys together) lock it with 401 OTP_ATTEMPTS_EXCEEDED; sign in again with the password to get a new one. Second factors work the same after password, LDAP, and OAuth sign-in.

TOTP

TOTP codes are standard: SHA-1, 6 digits, 30-second step, as produced by any authenticator app. Sentinel accepts the current step and one step on either side, and each code works once per user.

To enroll in the admin UI, open User profile → Two-factor authentication in the user menu and click Set up next to Authenticator app. Scan the QR code, then confirm with a code. With the API:

curl -H 'Authorization: Bearer <jwt>' https://sentinel.example.com/v2/me/otp
{
  "data": {
    "secret": "5OS5HWOKK2BNW3P3UGDSY2RNOEH7EBIW",
    "url": "otpauth://totp/ALTCHA%20Sentinel:root?secret=5OS5HWOKK2BNW3P3UGDSY2RNOEH7EBIW&period=30&digits=6&algorithm=SHA1&issuer=ALTCHA%20Sentinel"
  }
}

Nothing is stored yet. Confirm with the secret and a current code; the response is 204:

curl https://sentinel.example.com/v2/me/otp \
  -H 'Authorization: Bearer <jwt>' \
  -H 'Content-Type: application/json' \
  -d '{ "secret": "5OS5HWOKK2BNW3P3UGDSY2RNOEH7EBIW", "code": "123456" }'

From the next sign-in on, finish with the code:

curl https://sentinel.example.com/v2/auth/login/otp \
  -H 'Content-Type: application/json' \
  -d '{ "otpJwt": "eyJ0eXAi…", "code": "123456" }'
{ "data": { "jwt": "eyJ0eXAi…" } }

Existing sessions stay valid after enrollment. A user who already has passkeys needs step-up verification to enroll.

Users can't turn TOTP off themselves. If someone loses their authenticator, a root user disables OTP for them in Users → Disable OTP; see Reset a lost second factor.

Passkeys

Passkeys are a second factor that works instead of TOTP, for password, LDAP, and OAuth users alike. They don't replace the first step: users still sign in with a password, LDAP, or OAuth first.

Passkeys are available only when the auth base URL is set and its host is a domain name, not an IP address. The host is the WebAuthn relying party ID, and the URL's origin is the only origin accepted. Sentinel takes the first of these that's set:

  1. [auth] base_url
  2. [server.admin_ui] base_url, when the admin UI listener is enabled
  3. [server] base_url
[auth]
base_url = "https://sentinel.example.com"   # relying party ID: sentinel.example.com

Users must open the admin UI at that URL; a passkey registered for one host doesn't work on another. Changing the host makes every existing passkey unusable. Without a usable base URL, the passkey routes return 404 NOT_FOUND and GET /v2/app-config reports "passkeys": false.

Users add passkeys under User profile → Two-factor authentication → Add passkey. Each user can have up to 20. User verification (a PIN or biometric on the device) is required; ES256, EdDSA, and RS256 keys are accepted. Adding a passkey when the user already has a second factor, and removing one, need step-up verification. A user can't remove their last passkey without TOTP enabled (409 LAST_SECOND_FACTOR).

If a user loses their passkey, a root user removes it; see Reset a lost second factor. The registration and sign-in calls are in the API reference.

Step-up verification

Some changes to a user's own second factors require them to verify an existing factor again, even with a valid session:

  • adding a passkey when the user already has TOTP or a passkey;
  • deleting a passkey;
  • enrolling TOTP when the user already has passkeys.

The admin UI asks for a code or passkey when needed. With the API, get a step-up token with a TOTP code, or with a passkey assertion after POST /v2/me/verify/passkey/options:

curl https://sentinel.example.com/v2/me/verify \
  -H 'Authorization: Bearer <jwt>' \
  -H 'Content-Type: application/json' \
  -d '{ "code": "123456" }'
{ "data": { "expiresAt": 1795080704, "stepUpJwt": "eyJ0eXAi…" } }

Send it as the x-step-up-token header. It lasts 5 minutes (expiresAt, in Unix seconds), can be reused until then, and stops working when the user's sessions are revoked. Without it, the call returns 403 STEP_UP_REQUIRED. Five failed verifications within 10 minutes return 429 STEP_UP_ATTEMPTS_EXCEEDED.

Sessions

A session is an HS256 JWT. Sentinel returns it in data.jwt and sets it as the jwt cookie with HttpOnly; Secure; SameSite=Strict; Path=/. The admin UI uses the cookie; scripts send the token as a header:

curl -H 'Authorization: Bearer <jwt>' https://sentinel.example.com/v2/me
{
  "data": {
    "id": "usr_…",
    "username": "root",
    "root": true,
    "otpEnabled": true,
    "passkeyCount": 0,
    "hasPassword": true,
    "accounts": [ { "id": "acc_…", "name": "Default Account", "role": { "id": "admin", … } } ],
    …
  }
}

When an Authorization header is present, Sentinel uses only the header and ignores the cookie.

KeyEffect
[auth] jwt_ttlSession lifetime; also the cookie's Max-Age.
[auth] jwt_issuerThe token's iss claim. Tokens with another issuer are rejected.

Defaults are in the configuration reference. Sessions aren't refreshed or extended: when the token expires, requests return 401 UNAUTHORIZED and the user signs in again. Sessions are signed with [secrets] jwt_secret, so every replica must use the same value; see [secrets]. Changing it signs out everyone.

Logging out

The user menu offers two ways to log out:

  • Log out calls POST /v2/auth/logout. It needs no credentials and returns 204 with a cookie that clears jwt. It ends the session only in this browser: a copied token stays valid until it expires.
  • Log out everywhere calls POST /v2/me/_revoke_sessions after a confirmation. It revokes every session token and step-up token of the user, the current one included, in every browser and script, and returns the same cookie-clearing 204. The user then signs in again. Use it when a device is lost or a token may have leaked.
curl -i -X POST https://sentinel.example.com/v2/me/_revoke_sessions \
  -H 'Authorization: Bearer <jwt>'
HTTP/1.1 204 No Content
set-cookie: jwt=; HttpOnly; Secure; SameSite=Strict; Path=/; Max-Age=0

Later requests with any of the user's old tokens return 401 UNAUTHORIZED. Log out everywhere is recorded in the audit log as user.revoke_sessions; plain logout isn't recorded.

A root user can log out another user everywhere. Some changes to a user also revoke their sessions: a password change, deactivation, or a change to their root flag. See Revoke sessions.

Brute-force protection

Besides the login ALTCHA, three mechanisms limit password guessing:

  • Alerts. Failed sign-ins raise the brute_force alert (per client IP, default 3/10m) and the user_brute_force alert (per username from any IP, default 10/1h). Failed step-up verifications and wrong current passwords count too. See Alerts and [alerts.brute_force].
  • Automatic threat entries. Failed credentials and second factors count as signals per client IP. Enough of them create an automatic threat entry that blocks the IP.
  • Login blocking. With [auth] block_threats = true, the default, every sign-in step refuses a client IP that a manual or automatic threat entry blocks, with 403 IP_BLOCKED. Downloaded threat lists don't block sign-ins, sessions keep working, and private or loopback IPs are never refused. Other non-routable IPs, such as Tailscale's 100.64.0.0/10 addresses, are refused only by a manual entry. See Blocking logins.

All three rely on the real client IP. Behind a proxy or load balancer, configure client IP resolution first, or every admin shares the proxy's IP.

Single sign-on

OAuth providers

Sentinel signs users in with OpenID Connect: the authorization-code flow with PKCE (S256), state, and nonce, requesting the openid email profile scopes. A provider is enabled when its table is present in sentinel.toml. Every provider needs:

  • An auth base URL (see Passkeys for the order of precedence). Without one, startup fails with auth.base_url, server.admin_ui.base_url (admin UI enabled) or server.base_url is required with an [auth.oauth.*] provider.

  • A confidential client (web application) at the provider, with this redirect URI:

    {base_url}/v2/auth/oauth/{provider}/callback

    For example, https://sentinel.example.com/v2/auth/oauth/okta/callback.

name sets the button label; it defaults to the provider's name. Store the client secret as a secret file. Each provider's keys and defaults are in the configuration reference.

Provider{provider}Who can sign inReference
Microsoft Entra IDazureUsers of one tenant[auth.oauth.azure]
Google WorkspacegoogleUsers whose hd claim equals hosted_domain[auth.oauth.google]
KeycloakkeycloakUsers the realm lets into the client[auth.oauth.keycloak]
OktaoktaUsers assigned to the app[auth.oauth.okta]

Microsoft Entra ID

Register an app in a single tenant and use its directory (tenant) ID. tenant_id must be the GUID; common and organizations aren't accepted.

[auth.oauth.azure]
name          = "Microsoft"
client_id     = "11111111-2222-3333-4444-555555555555"
client_secret = "${file:/run/secrets/azure_client_secret}"
tenant_id     = "00000000-0000-0000-0000-000000000000"   # directory (tenant) ID

Sentinel identifies Entra ID users by the oid claim.

Google Workspace

Create an OAuth client of type Web application in the Google Cloud console. Only accounts of one Workspace domain can sign in; others are redirected back with OAUTH_NOT_ALLOWED.

[auth.oauth.google]
client_id     = "1234567890-abc.apps.googleusercontent.com"
client_secret = "${file:/run/secrets/google_client_secret}"
hosted_domain = "example.com"   # required hd claim

Keycloak

Create an OpenID Connect client with Client authentication on. issuer is the realm URL.

[auth.oauth.keycloak]
name          = "Corp SSO"
client_id     = "sentinel"
client_secret = "${file:/run/secrets/keycloak_client_secret}"
issuer        = "https://id.example.com/realms/corp"

Okta

Create an OIDC Web Application integration. issuer is the authorization server URL.

[auth.oauth.okta]
client_id     = "0oa1b2c3d4e5f6g7h8i9"
client_secret = "${file:/run/secrets/okta_client_secret}"
issuer        = "https://corp.okta.com/oauth2/default"

For Keycloak and Okta, issuer must be an http(s) URL without a query or fragment. Sentinel loads {issuer}/.well-known/openid-configuration from it.

The OAuth flow

  1. The browser opens the url from GET /v2/app-config, optionally with redirectUrl: a path such as /#/dashboard, or an absolute URL on the base URL's origin. It defaults to {base_url}/.

  2. Sentinel redirects to the provider and sets a short-lived, encrypted oauth_state cookie (HttpOnly; Secure; SameSite=Lax, 10 minutes).

  3. On the callback, Sentinel checks the state, exchanges the code, and verifies the ID token: signature, issuer, audience, expiry, nonce, and azp. For Google, it also checks hd.

  4. Sentinel redirects to redirectUrl with the jwt cookie set. If the user has a second factor, the redirect goes to /otp?otpJwt=…&methods=… in the fragment instead, and the login page asks for the second factor.

Failures redirect to the login page with an error code in the fragment, for example https://sentinel.example.com/#/login?error=OAUTH_FAILED. OAUTH_FAILED covers a provider that can't be reached, a failed code exchange, an invalid ID token, and a user who cancels at the provider; Sentinel logs the cause. The codes are listed in OAuth redirect errors.

LDAP

LDAP users sign in on the same form as password users, with their directory username and password and the login ALTCHA. The admin UI shows the method as Log in with followed by [auth.ldap] name (default LDAP). The API call is POST /v2/auth/ldap with the same body as POST /v2/auth/login, and it returns the same responses. [auth.ldap] lists every key and default.

Sentinel finds the user's DN in one of two ways.

Direct bind. Sentinel binds as the user. With USERNAME in user_dn, it replaces it with the escaped username; otherwise the DN is {username_attribute}={username},{user_dn}.

[auth.ldap]
name    = "Corp LDAP"
url     = "ldaps://ldap.example.com"
user_dn = "uid=USERNAME,ou=people,dc=example,dc=com"

Search-then-bind. Sentinel binds as a service account, searches user_search_base for ({username_attribute}={username}), then binds as the user it found. No match, or more than one, is 401 INVALID_CREDENTIALS. admin_dn, admin_password, and user_search_base must be set together.

[auth.ldap]
url                = "ldaps://ldap.example.com"
admin_dn           = "cn=sentinel,ou=services,dc=example,dc=com"
admin_password     = "${file:/run/secrets/ldap_admin_password}"
user_search_base   = "ou=people,dc=example,dc=com"
username_attribute = "uid"

For Active Directory, username_template = "USERNAME@corp.example" turns the typed name into the value that's bound or searched for.

TLS

SetupKeys
LDAPSurl = "ldaps://…"
StartTLSurl = "ldap://…" and starttls = true
Private CAtls_ca = "${file:/run/secrets/ldap-ca.pem}" (replaces the system roots)
Client certificatetls_cert and tls_key (PEM)

reject_unauthorized = false skips certificate verification; don't use it in production. Each connection and LDAP operation times out after 10 seconds. An unreachable server, a TLS failure, or a refused service account returns 502 LDAP_FAILED, with the cause in the server log.

Restrict sign-in to groups

With group_search_base and allowed_groups, only members of an allowed group can sign in. Others get 403 LDAP_NOT_ALLOWED, but only after their password is verified. An entry containing = is matched against the group's DN, any other entry against its cn, both case-insensitively.

[auth.ldap]
# … connection and bind keys as above
group_search_base = "ou=groups,dc=example,dc=com"
allowed_groups    = ["sentinel-admins", "cn=ops,ou=groups,dc=example,dc=com"]
# Defaults match groupOfNames/member. For posixGroup/memberUid:
# group_class                 = "posixGroup"
# group_member_attribute      = "memberUid"
# group_member_user_attribute = "uid"

SSO users

Sentinel matches SSO users by username:

MethodUsername
OAuth{provider}:{id}, where id is the ID token's sub (oid for Entra ID), e.g. okta:00u1a2b3c4
LDAPldap:{username}, lowercased, so JDoe and jdoe are the same user

On the first sign-in, Sentinel creates the user without a password, as a member of every active default account. The display name comes from the ID token's name, email, or preferred_username claim, or from the LDAP entry's cn. Later sign-ins reuse the user unchanged; change their roles or make them root in Users. Creating a user over the license's users limit fails with LICENSE_LIMIT_REACHED.

Anyone the provider or directory authenticates gets a user. Restrict access at the source: Entra ID tenant and app assignment, Google hosted_domain, Keycloak or Okta app assignment, or LDAP allowed_groups. To block one SSO user, deactivate them in Users: they then get USER_DISABLED.

Turn off password sign-in

Once SSO works, you can stop password sign-in for every user, root included:

[auth]
password_login = false

POST /v2/auth/login and POST /v2/me/password then return 403 PASSWORD_LOGIN_DISABLED, and the login page shows only LDAP and OAuth. LDAP sign-in isn't affected. Sentinel refuses to start with password_login = false and no [auth.oauth.*] or [auth.ldap] table.

Start typing to search...

↑ ↓ Navigate ↵ Select