SSO / OIDC

Stream Trace supports single sign-on through OpenID Connect using the authorization-code flow. Providers are configured as a JSON array in ST_AUTH_OIDC_PROVIDERS_JSON.

Configure a provider

ST_AUTH_OIDC_PROVIDERS_JSON='[
  {
    "id": "okta",
    "display_name": "Okta",
    "issuer_url": "https://example.okta.com/oauth2/default",
    "client_id": "stream-trace",
    "client_secret": "secret",
    "scopes": ["openid", "email", "profile", "groups"],
    "callback_url": "https://trace.example.com/api/auth/oidc/okta/callback",
    "email_claim": "email",
    "email_verified_claim": "email_verified",
    "groups_claim": "groups",
    "hosted_domains": ["example.com"]
  }
]'

Key fields:

• id - a stable identifier used in the login and callback URLs.
• callback_url - must be registered with your provider. The path is always /api/auth/oidc/<id>/callback.
• email_claim / email_verified_claim - which token claims supply the user’s email.
• groups_claim - the claim that lists the user’s groups, used for role mapping.
• hosted_domains - optional allow-list of email domains.

Add more objects to the array to offer multiple providers; each appears as its own button on the login page.

Users and provisioning

Users are created automatically the first time they sign in through OIDC. To grant them access, map provider groups to Stream Trace roles - see Teams & multi-tenancy for ST_AUTH_PROVISIONED_ROLE_MAPPINGS_JSON.

Break-glass admin

If you run OIDC-only but need an emergency local login (for example, if your IdP is unavailable), enable break-glass access for the instance_admin:

ST_AUTH_BREAK_GLASS_LOCAL_ENABLED=true