Sign-in and SSO

Set up SSO

1. 1

   Register the dashboard with your provider

   Create a confidential client in the provider's developer console, requesting the openid email profile scopes, with this redirect URI:

   https://<dashboard-host>/api/auth/oauth2/callback/<providerId>
   

   <providerId> is a short name you choose, such as globus.

2. 2

   Set the dashboard's URL

   Set BETTER_AUTH_URL to the dashboard's browser-facing URL, such as https://dashboard.example.edu. The redirect URI you registered must match it exactly, scheme and port included.

3. 3

   Add the provider

   Set OIDC_PROVIDERS to a JSON array with one object per provider:

   [{
     "providerId": "globus",
     "displayName": "Globus",
     "discoveryUrl": "https://auth.globus.org/.well-known/openid-configuration",
     "clientId": "YOUR_CLIENT_ID",
     "clientSecret": "YOUR_CLIENT_SECRET",
     "scopes": ["openid", "email", "profile"]
   }]
   

4. 4

   Restart the control plane and approve people

   The sign-in page shows a button per provider. Each person's first sign-in creates a pending account; approve it on Users.

Where the variables go depends on how you run the dashboard: deploy/docker/.env for Docker Compose, control-plane/.env.local when running it on the host with npm run dev, or the controlPlane values under Helm (see below). Moving from a test provider to a real one is only a change to these variables.

Provider fields

The discovery URLs are https://auth.globus.org/.well-known/openid-configuration for Globus and https://cilogon.org/.well-known/openid-configuration for CILogon (register at cilogon.org/oauth2/register). An unknown authentication value or claims field is refused with an error.

Admin approval flow

A first SSO sign-in creates an account with no access. Pending users see an awaiting-approval screen with Sign out.

On Users, accounts waiting for approval are listed first. Pick a role and a tenant, then Approve; Not now leaves them waiting. Below them, everyone else is listed with what they can reach and when they joined, and can be changed or deactivated.

Two changes are always refused, so nobody locks the gateway out: removing admin from your own account, and demoting or deactivating the last active admin. The same rule covers the sign-in library's own admin endpoints under /api/auth/admin/*.

Break-glass local admin

One email-and-password admin is seeded at start-up and works even when the identity provider is down. Public sign-up is closed; every other account comes from a first SSO sign-in.

The account is created only when there is no active admin, so it is made on first boot and not recreated. A password shorter than 8 characters, or an existing non-admin account with the same email, is logged as an error and no account is made; the dashboard still starts and serves SSO. Change both values from any development defaults before the dashboard is reachable from a network.

Reaching the dashboard from another host

Sign-in checks the browser's Origin against BETTER_AUTH_URL, which defaults to http://localhost:3000 (the Compose stack uses http://localhost:3002). Opening the dashboard by IP address or another hostname fails with an invalid-origin error, for the local admin as well as SSO, until you either set BETTER_AUTH_URL to the URL you browse to or list the other origins:

TRUSTED_ORIGINS=http://10.0.0.10:3002,http://obleth.example.internal:3002

A single * trusts every origin: acceptable on a trusted private network, unsafe anywhere reachable from the internet. BETTER_AUTH_URL still sets the host in redirect URIs, whatever TRUSTED_ORIGINS allows.

Kubernetes (Helm)

controlPlane:
  dashboardAdminEmail: "admin@your-org.example"
  dashboardPassword: ""        # at least 8 characters; pass with --set or a Secret
  dashboardSessionSecret: ""   # at least 32 characters; also used as BETTER_AUTH_SECRET
  betterAuthUrl: "https://dashboard.example.edu"
  trustedOrigins: ""
  oidcProviders: |
    [{"providerId":"globus","displayName":"Globus","discoveryUrl":"https://auth.globus.org/.well-known/openid-configuration","clientId":"ID","clientSecret":"SECRET","scopes":["openid","email","profile"]}]

In production, put these in a Secret you create and set controlPlane.existingSecret. The chart then renders no control-plane Secret, so yours must carry every key: DASHBOARD_PASSWORD, DASHBOARD_SESSION_SECRET, BETTER_AUTH_SECRET, DATABASE_URL, DASHBOARD_ADMIN_EMAIL, BETTER_AUTH_URL, TRUSTED_ORIGINS and OIDC_PROVIDERS. See Helm values.

Try it locally with Dex

The Compose stack includes a Dex test provider behind the sso-dev profile, with one user, researcher@example.edu / password. In deploy/docker/.env:

COMPOSE_PROFILES=sso-dev
OIDC_PROVIDERS=[{"providerId":"dex","displayName":"Dev SSO (Dex)","discoveryUrl":"http://host.docker.internal:5556/dex/.well-known/openid-configuration","clientId":"obleth-control-plane","clientSecret":"dev-dex-secret","scopes":["openid","email","profile"]}]

Run docker compose up -d in deploy/docker and open http://localhost:3002. The issuer uses host.docker.internal because it must resolve to the same address from your browser and from the control-plane container. If you change the dashboard's port, update Dex's redirectURIs in deploy/docker/dex/config.docker.yaml and BETTER_AUTH_URL to match.

When the control plane runs on the host (npm run dev, port 3000) and only Dex runs in Docker, use http://localhost:5556/dex/.well-known/openid-configuration as the discovery URL and set BETTER_AUTH_URL=http://localhost:3000 in control-plane/.env.local. More test users go under staticPasswords in the Dex config, with bcrypt-hashed passwords; restart Dex after editing.

{ "claims": { "email": "preferred_username" }, "overrideUserInfo": true, "pkce": true }