Turn on authentication¶
Turn on sign-in for an installation: the authentication reef and its Nereid keycloak run the realm nereus, and every person logs in with nereus login, never with a kubeconfig.
Before you start¶
- A cluster from Prepare the cluster. With
--profile internal-developer-platformthe reef and the Nereid are already there, and step 1 reportsunchanged. - After a plain
nereus init, Nereids for the secrets and release reefs, the release one with a default Mandate: Keycloak runs as a Release. - Tenancy and access explains who the initial admin is and what
nereus-adminscan do.
Steps¶
1. Install the reef and its Nereid¶
nereus reef apply adds the reef; nereus nereid apply runs Keycloak and makes the default Mandate keycloak.
nereus reef apply authentication
✓ core/reefs/authentication 0.1.0 created (authentication.getnereus.dev/v1alpha1: tokens)
Next steps:
nereus authentication --help
nereus nereid apply <nereid> --reef authentication
nereus nereid apply keycloak \
--reef authentication
✓ core/nereids/keycloak created, Ready, pinned to sha256:e8731e3fb833: see 'nereus authentication --help'
release/releases/keycloak created by core/nereids/keycloak, Ready (codecentric/keycloakx 7.0.1 in namespace nereus-system)
core/mandates/keycloak created (reef: authentication, nereid: keycloak, default)
issuer http://localhost:8180/realms/nereus (dev mode, kept in the Database keycloak)
client claude (public, PKCE S256, redirect https://claude.ai/api/mcp/auth_callback)
user nereus (password: kubectl --namespace nereus-system get secret keycloak-user --output jsonpath='{.data.password}' | base64 --decode)
Next steps:
kubectl --namespace nereus-system port-forward service/keycloak-server-http 8180:8180
Until its Release is Ready the Nereid reports WaitingForRelease; with no default release Mandate it reports NoReleaseNereid. On a cluster with an ingress address the realm is served at http://auth.localhost:8080 and needs no port-forward.
2. Log in as the initial admin¶
The realm's user nereus is the instance's initial admin, in nereus-admins. nereus login --initial-admin reads its generated password with your kubeconfig and copies it to the clipboard, never printed. Paste it on the login page.
nereus login --initial-admin
The initial admin's password is in your clipboard (user nereus). Paste it on the login page.
Opening http://auth.localhost:8080/realms/nereus/protocol/openid-connect/auth?... in the browser.
logged in as nereus (nereus-admins), issuer http://auth.localhost:8080/realms/nereus
3. Give the realm a public host¶
nereus mandate apply replaces every param, so name them all. The API trusts one issuer at a time: after the change every person runs nereus login again.
nereus mandate apply keycloak \
--reef authentication \
--nereid keycloak \
--default \
--param publicUrl=https://auth.example.com
4. Log in from another machine¶
nereus login with the instance's address asks the instance for its identity provider, so no kubeconfig is needed. The address is kept for the next commands.
KUBECONFIG=/nonexistent nereus login https://nereus.example.com
Opening https://auth.example.com/realms/nereus/protocol/openid-connect/auth?... in the browser.
instance https://nereus.example.com saved in ~/.config/nereus/config.yaml
logged in as ana-silva (nereus-users), issuer https://auth.example.com/realms/nereus
On a machine with no browser, add --use-device-code and type the code on another device.
Check it worked¶
nereus whoami asks the Nereus API who you are.
nereus whoami
ana-silva (nereus-admins, nereus-users)
nereus status now reads through the API with your token, and lists the reef:
nereus status
REEF NEREID VERSION STATUS AGE
authentication keycloak 0.1.0 Ready 2m
core built-in 0.1.0 Ready 4m
release flux 0.1.0 Ready 3m
secrets openbao 0.1.0 Ready 4m
tenancy - - Ready 4m
Registry localhost:5111
Next¶
- Grant access to the people of your team.
Learn more¶
- The authentication reef: every command, and the realm's clients.
- ADR 0006: the OIDC contract the default Mandate publishes.