Skip to content

sandbox-sso-setup.md

Latest commit

 

History

History
171 lines (118 loc) · 6.7 KB

sandbox-sso-setup.md

File metadata and controls

171 lines (118 loc) · 6.7 KB
Raw

Sandbox SSO Setup

Overview

The sandboxed-local cluster can authenticate users via the production Keycloak at keycloak.rijksapp.nl, which in turn uses SSO-Rijk. This provides real government SSO authentication in a local development environment.

SSO is optional. Without it, the sandbox works with a local admin user only (admin@sandbox.rijksapp.dev).

How It Works

Authentication Chain

User login (sandbox)
  → Sandbox Keycloak (keycloak.sandbox.rijksapp.dev)
    → Production Keycloak (keycloak.rijksapp.nl / rig-platform realm)
      → SSO-Rijk (government identity provider)

The sandbox Keycloak is configured with an OIDC identity provider (sso-rijk) that points to the production Keycloak's rig-platform realm. When a user logs in, they are redirected through this chain to SSO-Rijk for authentication.

The development-clusters Client

A shared OIDC client called development-clusters is registered in the production Keycloak's rig-platform realm. This client is used by both local Kind clusters and sandbox clusters to authenticate against the production Keycloak.

Allowed redirect URIs:

  • https://keycloak.kind/* (local Kind cluster)
  • https://keycloak.sandbox.rijksapp.dev/* (sandbox cluster)
  • http://localhost:*/* (local development)

The client secret is generated by the production Keycloak and must be obtained manually from the admin console.

Attribute Passthrough

SSO-Rijk attributes (email, name, organization) are passed through the entire chain:

  1. SSO-Rijk issues SAML/OIDC assertions with user attributes
  2. Production Keycloak maps these to the custom_attributes_passthrough client scope
  3. The development-clusters client includes this scope by default
  4. Sandbox Keycloak receives the attributes via OIDC and maps them to local user attributes

Configuring SSO

During Cluster Setup

When running task sandbox:setup, you will be prompted:

=========================================
SSO Configuration (Optional)
=========================================

The sandbox can use the production Keycloak (keycloak.rijksapp.nl) for real
SSO-Rijk authentication. This requires the client secret for the
'development-clusters' client in the production rig-platform realm.

Without SSO, the sandbox still works using a local Keycloak admin user.
Applications deployed in the sandbox will use Keycloak but cannot use SSO.

Do you want to configure SSO? [y/N]:

If you choose y, you will be asked for the client secret. This is stored in .env.sandboxed-local.secrets (gitignored) and encrypted via SOPS into a Kubernetes Secret.

Getting the Client Secret

  1. Log into the production Keycloak admin console: https://keycloak.rijksapp.nl
  2. Select the rig-platform realm
  3. Go to Clients > development-clusters
  4. Go to the Credentials tab
  5. Copy the Client secret

Adding SSO After Setup

If you skipped SSO during initial setup, you can add it later:

  1. Run the interactive SSO configuration:

    task sandbox:configure-sso

  2. Encrypt the secret and create the Kubernetes Secret:

    task sandbox:generate-env-secrets

  3. Apply the updated secret to the cluster:

    task sandbox:sync

  4. Restart the Operations Manager to pick up the new secret:

    kubectl rollout restart deployment/operations-manager -n rig-system

Manual Configuration

You can also configure SSO manually by creating the secrets file directly:

cat > operations-manager/python/.env.sandboxed-local.secrets << 'EOF'
# Sandbox SSO secrets
KEYCLOAK_MASTER_OIDC_CLIENT_SECRET=<your-client-secret-here>
EOF

Then run task sandbox:generate-env-secrets to encrypt it.

How the Secret Flow Works

.env.sandboxed-local.secrets     (gitignored plaintext file)
  → task sandbox:generate-env-secrets
    → SOPS-encrypted K8s Secret   (operations-manager-env-secrets.yaml)
      → Synced to in-cluster Forgejo
        → ArgoCD deploys to cluster
          → OPI reads KEYCLOAK_MASTER_OIDC_CLIENT_SECRET env var
  1. The plaintext secret lives in operations-manager/python/.env.sandboxed-local.secrets (gitignored)
  2. task sandbox:generate-env-secrets reads this file and creates a SOPS-encrypted Kubernetes Secret at bootstrap/rig-system/kustomize/operations-manager/overlays/sandboxed-local/operations-manager-env-secrets.yaml
  3. The encryption uses the sandbox AGE key (security/sandbox-key.txt)
  4. This encrypted secret is synced to the in-cluster Forgejo and deployed by ArgoCD
  5. ArgoCD's CMP plugin decrypts the SOPS secret during deployment
  6. The Operations Manager reads the secret as an environment variable

Configuration Reference

Environment Variables

Variable Value Source
KEYCLOAK_MASTER_OIDC_CLIENT_ID development-clusters Configmap
KEYCLOAK_MASTER_OIDC_DISCOVERY_URL https://keycloak.rijksapp.nl/realms/rig-platform/.well-known/openid-configuration Configmap
KEYCLOAK_MASTER_OIDC_CLIENT_SECRET (from production Keycloak) SOPS-encrypted Secret

Files

File Purpose
operations-manager/python/.env.sandboxed-local.secrets Plaintext secrets (gitignored)
bootstrap/.../overlays/sandboxed-local/operations-manager-env-secrets.yaml SOPS-encrypted K8s Secret
bootstrap/.../overlays/sandboxed-local/configmap.yaml Non-secret configuration
bootstrap/.../overlays/sandboxed-local/patches/deployment.yaml Mounts the secret as env var
operations-manager/python/opi/configs/keycloak/bootstrap-sandbox.yaml Keycloak bootstrap config for sandbox

Taskfile Tasks

Task Description
sandbox:configure-sso Interactive prompt to configure SSO client secret
sandbox:generate-env-secrets Encrypt .env.sandboxed-local.secrets into SOPS-encrypted K8s Secret

Troubleshooting

SSO login redirects fail

Verify the sandbox Keycloak hostname is in the development-clusters client's redirect URIs in the production Keycloak. It should include https://keycloak.sandbox.rijksapp.dev/*.

"Invalid client secret" errors

The client secret may have been regenerated in the production Keycloak. Re-run task sandbox:configure-sso and task sandbox:generate-env-secrets.

SSO works but user attributes are missing

Check that the custom_attributes_passthrough client scope is assigned as a default scope on the development-clusters client in the production Keycloak.

Sandbox works but no SSO prompt on login

If KEYCLOAK_MASTER_OIDC_CLIENT_SECRET is empty, the Operations Manager falls back to local admin authentication only. The SSO identity provider is not configured in the sandbox Keycloak without a valid upstream client secret.