OIDC (Keycloak)

Stack relies on Keycloak for OAuth2 and OpenID Connect flows. To install Keycloak, run stack init --install-keycloak so the CLI installs everything required to run a shared Keycloak control plane inside your cluster.

OIDC in Stack is implemented with oauth2-proxy in front of your app plus a Keycloak realm per namespace. This is separate from components.auth (Supabase Auth), which provides the /auth API.

Alt text

Enabling OIDC

spec:
  components:
    ingress:
      port: 30010
    db: 
    rest: {}
    oidc:
      # Required by Keycloak for OIDC. OIDC requires a stable redirect URL.
      hostname-url: http://localhost:30013

When you enable oidc in your Stack yaml, oauth2-proxy is deployed and app traffic is gated through OIDC login.

Alt text

How Stack uses Keycloak

  • Each StackApp with spec.components.oidc.hostname-url defined triggers the Stack controller to ensure a Keycloak realm and OAuth2 Proxy configuration exist.
  • The CLI creates an initial admin secret named keycloak-initial-admin in the Keycloak namespace. stack status --manifest … reads this secret so you can log in instantly.
  • OAuth2 Proxy is configured to trust Keycloak and inject the right upstream headers toward your app.
  • Stack stores OIDC client settings in an oidc-secret secret in your app namespace.

What gets installed

  1. CustomResourceDefinitions – keycloaks.k8s.keycloak.org and keycloakrealmimports.k8s.keycloak.org enable the operator to watch realms and servers.
  2. Keycloak Operator – A deployment that reconciles Keycloak and KeycloakRealmImport resources.
  3. Dedicated namespace – Stack creates (or reuses) the keycloak namespace so the identity stack stays isolated.
  4. Backing database – The Keycloak operator provisions a CloudNativePG cluster for Keycloak itself; Stack wires credentials automatically.

Verifying the installation

kubectl get pods -n keycloak
kubectl get keycloaks.k8s.keycloak.org -n keycloak
kubectl get secret keycloak-initial-admin -n keycloak -o yaml

If you ever need to reinstall Keycloak components (for example after manually deleting the namespace), re-run stack init --install-keycloak. The CLI reapplies the CRDs, operator deployment, and database manifests idempotently.

Accessing the Keycloak admin

If you need to reach the Keycloak admin UI quickly open up the port.

kubectl -n keycloak port-forward svc/keycloak-service 8080:8080

Then use kubectl to read the initial admin credentials:

kubectl -n keycloak get secret keycloak-initial-admin \
  -o jsonpath='{.data.username}' | base64 -d && echo
kubectl -n keycloak get secret keycloak-initial-admin \
  -o jsonpath='{.data.password}' | base64 -d && echo

The output includes the admin username and password.