Users and SSO
The system Keycloak from page 00 of the app ladder holds one realm per
tenant. shc user manages the users in a realm and the SHC roles they hold.
On the node you are a platform admin, so every user command names its
tenant with --tenant.
$ shc user ls --tenant prod.........$ shc user ls --tenant prod...Email is required: Keycloak 26 refuses password sign-in without it with “Account is not fully set up”.
A user’s name is the person’s full name, quoted: the last word is the family
name. rename corrects it in place, and alice keeps her password, roles and
sessions.
$ shc user rename alice "Alice Pleasance Liddell" --tenant prod...A role is a scope and a name: stack:web lets alice open web through the
SSO gate, tenant:read lets her read every deployment’s logs and status in
the tenant, tenant:manage makes bob a tenant admin. A grant writes the role
on the user; roles in the listing is what the user’s token carries and
direct_roles is what was granted on the user itself.
$ shc user grant alice tenant:read --tenant prod...$ shc user grant bob tenant:manage --tenant prod...$ shc user ls --tenant prod...$ shc user revoke alice tenant:read --tenant prod...$ shc user revoke bob tenant:manage --tenant prod --force-last-admin...$ shc user ls --tenant prod...--force-last-admin lets a revoke or a removal leave the tenant without a
manager; without it, taking the last manager’s role away is refused.
A deployment’s own role family is written to the realm by the first grant that names it, so a grant typed right after an install holds. Install a second nginx and grant alice its role at once, then take the deployment away again. A name the tenant has no deployment of is refused, and no role is made for it.
$ shc user grant alice stack:web --tenant prod✔ granted role "stack:web" to user "alice" in tenant "prod"$ shc install ~/learn/nginx -s hello -t prod --expose 18083=nginx:80installing deployment "hello"[hello] Healthy 1/1✔ nginx healthy✔ installed deployment "hello"exposure: lan$ shc user grant alice stack:hello --tenant prod✔ granted role "stack:hello" to user "alice" in tenant "prod"$ shc user grant alice stack:nosuch --tenant prodshc: [X404936USRSTK] stack:nosuch names deployment nosuch, which tenant prod does not have$ shc uninstall hello -t prod --yesuninstalling deployment "hello"[hello] Complete 4/4✔ remove from home01✔ take the safety backup✔ leave every node's service VIP table✔ tear down✔ uninstalled deployment "hello"Reset a password and end a session. shc user logout ends every SSO session
the user holds and revokes the tokens issued from them; the user can log in
again straight away.
$ shc user reset-password alice P@ssw0rd --temporary --tenant prod...$ shc user logout alice --tenant prod...--temporary makes alice change the password at her next login. The
command prefers to prompt for the password; the page types it because a walk
has no terminal to answer a prompt.
Logging in from a workstation is shc auth login: it opens the browser for
the realm’s login page and keeps the tokens for the commands that follow.
The tenant is always named; login does not read the context. Pass
--ca-fingerprint to check the cluster CA against a fingerprint you were
given, or --ca with a bundle you trust. --insecure skips the check and
prints a warning, for a cluster you are only testing.
$ shc auth login --url https://home01 --tenant prod --ca-fingerprint <fingerprint>$ shc auth login --url https://home01 --tenant prod --ca ~/learn/ca.pem$ shc auth login --url https://home01 --tenant prod --insecureAutomation logs in without a browser. A service client is a confidential
client in the master realm; its secret is printed once, when it is made,
and --rotate-secret mints a new one in place of the old. The second create
call finds the client and prints its id only. A pipeline then logs in with
the client credentials, and every token it gets is platform root. No command
removes the client, so this page makes none. The gated page makes one,
because that is where its bearer gets used.
$ shc auth create-service-client learn --token-lifespan 7200$ shc auth create-service-client learn$ shc auth create-service-client learn --rotate-secret$ shc auth login --url https://home01 --client-credentials --client-id learn --client-secret <secret>$ shc auth login --url https://home01 --client-credentials --client-id learnThe last login reads the secret from SHC_CLIENT_SECRET instead of the
command line, which is the form to use.
A scope narrows a service client. With platform:read its tokens read the
condition set and the deployment list and nothing else, whatever the realm
maps to it later. --seal writes the credential into a vault key at the
estate-wide tier and prints no secret at all.
$ shc auth create-service-client learn-read platform:read --seal learn_read_credentialshc auth logout clears the tokens stored on this machine, and only those.
shc user apps and shc user managed-apps list the deployments the caller
may open and may manage. On the node you are a platform admin, so both list
every deployment on the cluster, master’s included; for alice they would
list web and nothing she manages.
$ shc user apps...$ shc user managed-apps...$ shc auth logout...Remove the two users. Removing a user revokes every role granted to them.
$ shc user rm alice --yes --tenant prod...$ shc user rm bob --yes --tenant prod...$ shc user ls --tenant prod...$ shc user rm bob --yes --force-last-admin --tenant prodThe system Keycloak’s own admin password can be reset from the node. This resets the live credential, updates the sealed seed and redeploys keycloak, and the command answers once the redeploy has landed, which takes minutes. The user commands reach the realm through that credential, so a listing after the reset shows it holds.
$ shc system keycloak reset-admin-password --password P@ssw0rd✔ reset system keycloak admin password, keycloak redeployed$ shc user ls --tenant prod...$ shc ls -t masterSTACK TENANT ENV APP STATUS NODEkeycloak master default keycloak running home01postgres master default postgres running home01traefik master default traefik running home01Tenant prod is back to the users it had, the master realm gained nothing,
and the platform apps are running.
Next: Gated apps.