Skip to content

CD OIDC Setup

This guide covers how to enable OIDC authentication on the CD production environment. The CD environment runs on the public internet at nirn.clarity-innovations.com, so authentication is essential to prevent unauthorized access to services like the Traefik dashboard, Prometheus, and cAdvisor.

The OIDC architecture is the same as dev mode — Traefik ForwardAuth with oauth2-proxy — but connected to your organization's production identity provider instead of a local Keycloak instance.

Prerequisites

  • The CD environment is already running (CLARITOOLS_ENVIRONMENT=cd)
  • DNS for *.cd.ciservers.net resolves to the CD server
  • You have admin access to your organization's identity provider, or can request a client registration from DevOps

Information to request from DevOps

OIDC client registration

Ask your DevOps or identity team to create a new OIDC client application with the following details:

Field Value
Application name claritools-cd (or per your org convention)
Application type Web application (confidential client)
Scopes openid email profile
Sign-out URL (optional) https://dashboard.cd.ciservers.net

Redirect URIs — provide one of the following depending on whether your IdP supports wildcard URIs:

https://*.cd.ciservers.net/oauth2/callback

https://dashboard.cd.ciservers.net/oauth2/callback
https://traefik.cd.ciservers.net/oauth2/callback
https://prometheus.cd.ciservers.net/oauth2/callback
https://cadvisor.cd.ciservers.net/oauth2/callback
https://docs.cd.ciservers.net/oauth2/callback

Note

If using enumerated URIs, you must add a callback URI for every new service added to the stack. The wildcard approach avoids this maintenance burden.

Values you will receive back

After the client is registered, you will receive:

Value Description Example
OIDC Issuer URL The IdP's issuer endpoint https://company.okta.com, https://login.microsoftonline.com/<tenant>/v2.0, https://accounts.google.com
Client ID Identifies claritools to the IdP 0oa1b2c3d4e5f6g7h8i9
Client Secret Authenticates claritools to the IdP AbCdEf...

Access control decisions

Decide who should have access and communicate this to DevOps:

Decision Options oauth2-proxy config
Email domain restriction Limit to @clarity-innovations.com OAUTH2_PROXY_EMAIL_DOMAINS=clarity-innovations.com
Group-based access Limit to a specific IdP group OAUTH2_PROXY_ALLOWED_GROUPS=claritools-users
Open to org Anyone with an org account OAUTH2_PROXY_EMAIL_DOMAINS=clarity-innovations.com

Ask DevOps which OIDC claim carries group membership if you plan to restrict by group (commonly groups or roles).

Infrastructure checklist

Verify the following before deployment:

  • [ ] DNS — *.cd.ciservers.net wildcard DNS points to the CD server
  • [ ] Outbound HTTPS — The CD server can reach the IdP (for token validation and JWKS)
  • [ ] Let's Encrypt — Certificates are issuing correctly for *.cd.ciservers.net
  • [ ] Secret storage — Decide where the client secret and cookie secret will be stored (.env file, Docker secrets, Vault, etc.)

Do not commit secrets to git

The client secret and cookie secret must never be committed to the repository. Store them in the .env file on the CD server (which is already in .gitignore) or use your organization's secret management system.

Configuration

Once you have the OIDC details, create a docker-compose.cd-auth.yml overlay file on the CD server. This follows the same pattern as the dev mode docker-compose.dev.yml but with production values.

python3 -c "import secrets; print(secrets.token_urlsafe(32)[:32])"

The cookie secret must be exactly 16, 24, or 32 bytes.

Environment variables

Add the following to the .env file on the CD server:

CLARITOOLS_ENVIRONMENT=cd
OIDC_ISSUER_URL=https://your-idp.example.com
OIDC_CLIENT_ID=your-client-id
OIDC_CLIENT_SECRET=your-client-secret
OAUTH2_COOKIE_SECRET=your-32-char-cookie-secret
OIDC_EMAIL_DOMAINS=clarity-innovations.com

Provider-specific notes

Different identity providers may require additional configuration:

OAUTH2_PROXY_PROVIDER: oidc
OAUTH2_PROXY_OIDC_ISSUER_URL: https://company.okta.com

Okta's well-known endpoint works with standard OIDC discovery.

OAUTH2_PROXY_PROVIDER: oidc
OAUTH2_PROXY_OIDC_ISSUER_URL: https://login.microsoftonline.com/<tenant-id>/v2.0

You may need to add OAUTH2_PROXY_OIDC_EXTRA_AUDIENCES if the token audience doesn't match the client ID.

OAUTH2_PROXY_PROVIDER: google
OAUTH2_PROXY_OIDC_ISSUER_URL: https://accounts.google.com

Use the google provider type for built-in Google Workspace integration.

OAUTH2_PROXY_PROVIDER: keycloak-oidc
OAUTH2_PROXY_OIDC_ISSUER_URL: https://keycloak.example.com/realms/your-realm

If the Keycloak instance is external and accessible over HTTPS, standard OIDC discovery works and you do not need to skip discovery or manually set endpoints (unlike the local dev setup).

Differences from dev mode

Aspect Dev mode CD mode
Identity provider Local Keycloak container Organization's production IdP
OIDC discovery Disabled (split internal/external URLs) Enabled (IdP is externally accessible)
Credentials Hardcoded dev/dev Real user accounts from IdP
Cookie domain .local.ciservers.net .cd.ciservers.net
TLS to IdP Self-signed (skip verification) Valid certificate (strict verification)
Client secret In docker-compose.dev.yml In .env on server (never in git)

Verification

After deploying:

  1. Visit https://dashboard.cd.ciservers.net — you should be redirected to your IdP login
  2. Authenticate with your organizational credentials
  3. Confirm you are redirected back to the dashboard
  4. Visit another service (e.g., https://traefik.cd.ciservers.net) — SSO should pass you through without re-authenticating
  5. Open an incognito window and verify unauthenticated access is blocked

Rollback

If authentication causes issues, remove the auth overlay from the compose command in the Taskfile and restart:

task restart

The base CD stack runs without authentication, so removing the overlay restores the previous behavior.