SSO / OpenID Connect

Enterprise single sign-on for the admin console: authorization code + PKCE, exchanged server-side, mapped to the normal JWT/RBAC session. Disabled by default.

How it works

browser                admin backend                     provider
   |  GET /social/config    |                                |
   |----------------------->|  enabled? providers?           |
   |  GET /social/authorize |  mint state + PKCE verifier    |
   |----------------------->|  discovery (issuer)            |
   |  302 authorize URL     |                                |
   |------------------------------------------------------->|
   |  provider redirects back to /sso-callback?code&state   |
   |  POST /social/callback |  verify state, exchange code   |
   |----------------------->|------------------------------->|
   |                        |  userinfo (access token)       |
   |                        |  find/provision user, RBAC     |
   |  framework JWT session |                                |
   |<-----------------------|                                |

• The client secret and PKCE verifier never reach the browser; only state and code travel through the redirect.
• Identity comes from the provider's userinfo endpoint; the ID token is not trusted as an authorization source.
• The user is matched by verified email; unknown emails can be auto-provisioned with a default role.
• The issued session is a normal framework JWT, so RBAC menus/authorities work unchanged.

Configuration

strata:
  social:
    enabled: true
    # Exact browser redirect URIs (open-redirect guard). Include every origin you deploy:
    allowed-redirect-uris:
      - https://admin.example.com/sso-callback
      - http://localhost:5173/sso-callback
    providers:
      keycloak:                                  # id used by the admin UI
        display-name: Keycloak                   # button label
        issuer-uri: https://id.example.com/realms/main
        client-id: strata-admin
        client-secret: ${OIDC_CLIENT_SECRET}      # keep out of YAML
        scopes: [openid, email, profile]
        default-role-code: viewer                # fallback role for auto-provisioned users ("" = none)
        auto-provision: true                     # false = only pre-created emails may log in
        require-verified-email: true             # reject unverified emails
        roles-claim: groups                      # dot paths reach nested claims, e.g. realm_access.roles
        role-mappings:                           # external group/role -> framework role code
          platform-admins: admin
          support-team: viewer
        sync-roles: false                        # true = provider roles are authoritative on every login

Endpoints are discovered from issuer-uri (/.well-known/openid-configuration). If your provider has no discovery document, set them explicitly:

        authorization-endpoint: https://id.example.com/authorize
        token-endpoint: https://id.example.com/oauth/token
        user-info-endpoint: https://id.example.com/userinfo

The admin UI must be reachable at the configured redirect URI. The SPA always uses ${origin}/sso-callback, so add one entry per origin (dev and production).

Try it locally with Keycloak

The repository ships an optional compose overlay with a Keycloak realm (client + a demo user) configured for the admin console:

git clone https://github.com/simplezac1995/strata.git
cd strata
docker compose -f docker-compose.yml -f docker-compose.sso.yml up --build