Skip to content

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-platform the reef and the Nereid are already there, and step 1 reports unchanged.
  • 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-admins can 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
output
✓ 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
output
✓ 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
output
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
output
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
output
ana-silva (nereus-admins, nereus-users)

nereus status now reads through the API with your token, and lists the reef:

nereus status
output
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

Learn more