Guide 47 of 61 · Running a fleet with Central Lite
Sign in to the console with your identity provider
Let admins open Central Lite's console through Okta, Entra ID or another OIDC provider, with roles from its groups and a passkey still behind every change.
Built, not yet claimed preview: this guide describes a package that has not passed its release gate.
Register Central Lite at your identity provider, point Central Lite at it, map its groups or app roles to console roles, sign in and add your passkey, require single sign-on while keeping a break-glass owner, and sign in from a SAML-only provider through a broker. At the end your admins open the console with the sign-in they already use.
1. Know what single sign-on changes and doesn't
Central Lite speaks OpenID Connect (OIDC) to one issuer: Okta, Entra ID, Keycloak, or any other provider that publishes OIDC discovery. Single sign-on (SSO) only opens a console session. Every change you make still asks for a fresh passkey assertion over that exact change (a step-up), and nothing your provider asserts counts in its place. Remote approvals, kill-order approvals and legal-hold releases stay signatures by keys, never sign-ins.
An SSO identity signs in only once it is linked to a Central Lite admin, by SCIM provisioning or by garm-central admin link; an unlinked one is refused. With just-in-time admins on (garm-central sso jit on, or the switch under Settings → Single sign-on), an unlinked identity whose groups map to a role other than owner gets a passkeyless admin at its first sign-in, named from its preferred_username before any @, with only those roles, and an owner is alerted (admin_added_by_sso). JIT never grants owner. An SSO session has the passkey session's limits: 12 hours at most, 30 minutes idle, and a restart of serve signs everyone out.
Sign out ends Central Lite's session and, when the provider offers a sign-out endpoint (Okta, Entra ID and Keycloak do), sends the browser there to end your session at the provider too; the provider then sends it back to Central Lite. Okta and Entra ID never tell Central Lite that someone signed out there, so a person removed at the provider loses the console when SCIM deactivates them, or when the session's limits run out. A provider that sends OIDC back-channel logout, as Keycloak can, ends the matching sessions at once. Commands run on Central Lite's host are outside SSO and roles altogether.
See also
Provision and remove people with SCIMLet Okta or Entra ID create the people Central Lite knows, give them console roles from their groups, and end their access when they leave.
2. Register Central Lite at Okta or Entra ID
Central Lite's redirect URI is its URL followed by /auth/oidc/callback, here https://central.example:8443/auth/oidc/callback. Register exactly that: the provider must match it character for character. Register Central Lite's URL followed by / (here https://central.example:8443/) as the sign-out (post-logout) redirect URI too, so that signing out of the console can end your session at the provider and bring you back.
Okta: in the Admin Console, create an app integration of type OIDC, Web Application, with the Authorization Code grant and that sign-in redirect URI. For client authentication choose public key / private key: you paste the key Central Lite prints in the next step, so no client secret exists. Add a groups claim to the ID token, filtered by the regular expression ^agentgarm-.*, so the token carries only the groups meant for Central Lite: if more than 100 groups match, Okta refuses to issue the token at all. Assign the app to the people or groups who may sign in, and note the client id and your issuer, such as https://example.okta.com.
Entra ID: register an application for this tenant only, with a Web redirect URI as above. Make an RSA certificate and key, as the sample shows, and upload the certificate under Certificates & secrets; keep the key for the next step. Define an app role for each console role you will grant, such as agentgarm.security, then, in the enterprise application, assign people or groups to those roles (assigning a group needs Entra ID P1). Note the application's client id and your tenant id. Map app roles rather than groups: a user in more than 200 groups gets a token that names no groups, and Central Lite refuses it.
openssl req -x509 -newkey rsa:3072 -nodes -days 365 -subj "/CN=agentgarm-central" -keyout central-oidc.key -out central-oidc.crt3. Point Central Lite at your provider
On the Central Lite host, garm-central sso oidc set fetches the issuer's discovery document and checks it: the issuer must equal the one you give byte for byte, its endpoints must be https://, and it must offer the authorization code flow and PKCE S256, which Central Lite always sends. It prints SSO configured: with the client and the redirect URI to check against the provider's. --display-name names the console's sign-in button.
Okta: with neither a certificate nor a secret, Central Lite signs its client assertions with its own P-256 key, kept in its keystore, and prints paste this public key at the IdP: and the key as a JWK. Paste it into the Okta app's public keys; garm-central sso oidc jwk prints it again.
Entra ID: the issuer is your one tenant's v2.0 issuer; a multi-tenant issuer is not supported, and a token from another tenant is refused as “from another issuer (or tenant)”. Give the certificate and key with --cert-file and --key-file (the key at least 2,048 bits); Central Lite seals the key in its keystore and signs with it. Set --groups-claim roles, so roles come from the app roles, and --scopes profile, which Entra needs to send the user's object id (oid), the identity SCIM links to.
Another provider can use a client secret instead (--client-secret-file), sealed in the keystore too. No key or secret is ever kept in Central Lite's database, and the change is chained in its audit log without one. In the console, Settings → Single sign-on shows the configuration read-only; it is set only here.
garm-central sso oidc set --issuer https://example.okta.com --client-id <client id> --display-name Okta
garm-central sso oidc showgarm-central sso oidc set --issuer https://login.microsoftonline.com/<tenant id>/v2.0 --client-id <client id> --cert-file central-oidc.crt --key-file central-oidc.key --groups-claim roles --scopes profile --display-name "Entra ID"4. Map groups or app roles to console roles
garm-central sso map gives everyone whose token carries a group, or an Entra app role, a console role at a scope (org unless you name a host group or a host). --group takes the value exactly as the token carries it: an Okta group as its groups claim sends it, or an Entra app role's value, never a display name you typed elsewhere. Central Lite works out these roles again at every sign-in, so a person removed from a group at the provider loses its role at their next sign-in; deactivating them through SCIM ends their sessions at once. --remove drops a map.
In the console, Settings → Single sign-on lists the group and app role maps; adding or removing one, with SSO required, is saved with one passkey step-up. Roles can also come from SCIM groups or be bound by hand: what each role sees is in the roles guide.
garm-central sso map --group agentgarm-security --role security
garm-central sso map --group agentgarm.viewer --role viewerSee also
Give people the right access in the consoleGive each Central Lite admin one of six roles, for the whole org or a host group, and know who may request a kill order and who holds each approver key.
5. Sign in, then add your passkey
Before anyone signs in, link their identity to an admin. With SCIM provisioning that happens for you. By hand, garm-central admin link links an admin to the issuer and the sub the provider puts in its ID token (for Okta, the user id, 00u…); for Entra ID add --oid with the user's object id, since Entra's sub differs for every application.
The console's sign-in page now shows “Sign in with” and your provider's name above the passkey button. It sends you to your provider and back. If Central Lite refuses, it shows a page saying why and linking here: “Your identity is not linked to an active Central admin” (link it, as above); a user in too many groups for the token (Entra group overage: map app roles instead, or emit only “groups assigned to the application”); or a token from another issuer or tenant (check the issuer you configured). Overage and issuer refusals also raise an alert.
An admin who signs in with SSO and holds no passkey gets a read-only session: a banner says so, no change is offered, and every write would need a passkey. To add the first passkey, an owner runs garm-central admin recover for that admin on the Central Lite host and passes on the one-time code (it works once, for 15 minutes). Enter it in the banner's One-time code field and choose “Register your first passkey”; your authenticator asks twice. From then on, writes ask that passkey.
garm-central admin link --name alice --issuer https://example.okta.com --subject <okta user id>garm-central admin recover --name alice6. Require SSO and keep a break-glass owner
garm-central sso require on, or the SSO required switch in Settings → Single sign-on, makes passkey sign-in and recovery codes work only for admins holding owner at the whole org; the sign-in page then says “Passkey sign-in is for owners: everyone else signs in with single sign-on.” Each owner's passkey sign-in raises a High alert. An SSO admin can still redeem a code for a first passkey from their own SSO session.
Keep at least two owners with passkeys for the day your provider is down or misconfigured, and sign in with them now and then, so you know the way in works. Central Lite refuses to remove the last owner binding held by an admin with a passkey, and warns while only one is left. If every console way in fails, the account that runs Central Lite on its host still can: it prints recovery codes and binds roles.
garm-central sso require on
garm-central role listSee also
Stand up Central LiteSet up Central Lite on one Linux host: its org and keys, its HTTPS port, a first admin and a backup passkey, and its first encrypted backup.
7. Sign in from a SAML-only provider through a broker
Central Lite has no SAML parser: SAML's XML signatures have a long record of bypasses even in mature libraries. A provider that speaks only SAML signs in through an OIDC broker you run, and Central Lite sees only OIDC. Keycloak is the tested broker: a realm brokers your SAML provider and offers Central Lite an OIDC client, configured as in step 3 (a client secret, or the key Central Lite prints). Don't use Dex, whose SAML connector is unmaintained. AD FS 2019 and later, PingFederate, PingOne and Google speak OIDC and need no broker; Google's token carries no groups, so roles come from SCIM or are bound by hand.
The broker sees every assertion, so harden it. Run Keycloak 26.8.2 or later. In the identity provider's settings, turn on “Validate Signature” and “Want Assertions Signed”, and check both again after every metadata import. Turn IdP-initiated sign-on off: no client should have an IdP-initiated SSO URL, since that is the only defence against an assertion replay no Keycloak release fixes yet. Leave allowAdminRoleMapping off, as 26.8.0 and later default it. In the broker's client for Central Lite, set the back-channel logout URL to the one sso oidc set prints (back-channel logout URI:), so a sign-out at the broker ends the console session too.