OIDC

When to use: A developer with just a browser should be able to get a key. busbar hosts the SSO sign-in page and hands back the dev’s own budgeted key, ideal for Cursor / Claude Code / VSCode BYOK, where the tool just needs a static key and a base URL.

public_url: "https://busbar.example.com"   # busbar builds /auth/token itself
plugins:
  enabled: true
  fetch:
    - github: GetBusbar/auth-oidc@1.0.2
identity-providers:
  oidc:
    module: oidc
    settings:
      issuer: "https://login.microsoftonline.com/<tenant-id>/v2.0"
      audience: "<entra-client-id>"
    browser_login:                            # presence = hosted login button on
      client_secret: { env: OIDC_CLIENT_SECRET }
auth:
  signing_key: { file: /run/secrets/busbar-signing.key }
  chain: [keys]                               # the issued key authenticates here
  key_ttl: 90d                                # admin-set; default 90d, no dev choice
  role_bindings:
    oidc:
      "<entra-dev-group>": { group: engineering }

A dev opens GET /auth/token (busbar builds the URL from public_url), signs in with Entra, and busbar returns their own static key: self-scoped user:<sub>, budget auto-provisioned from the team’s child_default on first login, the secret shown on sign-in and again any time you sign in. Add a second method with its own browser_login and the page becomes a chooser (Microsoft / GitHub).

When to use: Headless or CI: the caller already holds an OIDC token (an IdP CLI, an internal app, <code>az account get-access-token</code>). No hosted page, no client secret, just the token exchange.

public_url: "https://busbar.example.com"
plugins:
  enabled: true
  fetch:
    - github: GetBusbar/auth-oidc@1.0.2
identity-providers:
  oidc:                                        # no browser_login → POST-only
    module: oidc
    settings:
      issuer: "https://login.microsoftonline.com/<tenant-id>/v2.0"
      audience: "<entra-client-id>"
auth:
  signing_key: { file: /run/secrets/busbar-signing.key }
  chain: [keys]
  key_ttl: 90d                                # admin-set; default 90d, no dev choice
  role_bindings:
    oidc:
      "<entra-dev-group>": { group: engineering }

Omit browser_login and the method is token-only: a dev (or CI) POSTs an OIDC token they already hold to /auth/token and gets back the same self-scoped, budgeted key, created on first exchange, with the secret shown then and re-shown on every later exchange.

When to use: No key at all: every request itself must carry a valid OIDC token, checked live against the issuer on the data plane. This is the existing 1.5.1 behavior: still valid, and stackable alongside the two token-exchange scenarios above.

identity-providers:
  oidc:
    module: oidc
    settings:
      issuer: "https://login.microsoftonline.com/<tenant-id>/v2.0"
      audience: "<entra-client-id>"
auth:
  chain: [oidc]                               # every request verified against the issuer, no issued key
  role_bindings:
    oidc:
      "<entra-dev-group>": { group: engineering }
plugins:
  enabled: true
  fetch:
    - github: GetBusbar/auth-oidc@1.0.2

No public_url, no browser_login, no key_ttl; nothing is issued or exchanged. Each caller presents its own OIDC token on every request; busbar verifies it live against the issuer’s JWKS and maps its groups claim through role_bindings.oidc the same way. Use this when callers already hold short-lived tokens and a long-lived busbar key isn’t wanted.

When to use: Not tied to one IdP: the same method fronts any OIDC-compliant issuer. You change one thing (<code>issuer</code>) and busbar discovers that provider’s login + JWKS endpoints from it. The sign-in button’s label and icon are inferred from the issuer host, so there’s no label to configure.

public_url: "https://busbar.example.com"   # busbar builds /auth/token itself
plugins:
  enabled: true
  fetch:
    - github: GetBusbar/auth-oidc@1.0.2
identity-providers:
  oidc:                                        # your choice of name; module: oidc backs it
    module: oidc
    settings:
      issuer: "https://accounts.google.com"    # the only line that changes per provider
      audience: "<google-client-id>"
    browser_login:                            # button label + icon inferred from issuer
      client_secret: { env: GOOGLE_SECRET }
auth:
  signing_key: { file: /run/secrets/busbar-signing.key }
  chain: [keys]                               # the issued key authenticates here
  key_ttl: 90d                                # admin-set; default 90d, no dev choice
  role_bindings:
    oidc:
      "<workspace-group>": { group: engineering }   # Google: wire Workspace groups (see note)

The identity-provider name (here oidc) is your choice, not the module name: identity-providers: entries are name → {module, …}, and auth.chain / role_bindings reference that name. Two named providers can share one module, so running more than one OIDC issuer at once (say oidc-google and oidc-okta, each module: oidc) is supported; the single-instance example above is the common case, not a limit. Only issuer changes between providers, and busbar discovers each one’s login + JWKS from it; the sign-in button is inferred from the issuer host, nothing to set. Okta: https://<org>.okta.com. Auth0: https://<tenant>.us.auth0.com/. Keycloak: https://<host>/realms/<realm>. Google (shown) puts no groups claim in the token by default; bind by email/hosted-domain or wire Workspace directory groups before group-based role_bindings will match.

When to use: The management plane can take OIDC too, not just the operator token; a token is a token on both planes (new in 1.5.2). Let an SSO admin group sign in to run mutations, while the same method still mints budgeted keys for devs.

public_url: "https://busbar.example.com"
plugins:
  enabled: true
  fetch:
    - github: GetBusbar/auth-oidc@1.0.2
identity-providers:
  oidc:
    module: oidc
    settings:
      issuer: "https://login.microsoftonline.com/<tenant-id>/v2.0"
      audience: "<entra-client-id>"
    browser_login:
      client_secret: { env: OIDC_CLIENT_SECRET }
auth:
  signing_key: { file: /run/secrets/busbar-signing.key }
  chain: [keys]                               # data plane: devs' issued keys
  admin_auth: [admin-tokens, oidc]            # admin plane: operator token OR OIDC
  key_ttl: 90d                                # admin-set; default 90d, no dev choice
  role_bindings:
    oidc:
      "<entra-dev-group>":   { group: engineering }   # data-plane budget
      "<entra-admin-group>": { admin_scope: full }     # admin authority: read-only | full

Admin scopes are exactly two after the 1.5.2 collapse: read-only (every read) and full (every mutation). An SSO admin group maps to one of them via role_bindings.oidc.<group>.admin_scope, so admin_auth: [admin-tokens, oidc] lets the operator token or an OIDC sign-in onto the admin plane. The one method does both jobs at once: a dev group gets a data-plane budget ({ group: … }), an admin group gets admin authority ({ admin_scope: … }). For an untrusted third-party identity provider, cap what it can ever grant with an optional max_admin_scope on its identity-providers: definition (omitted = the most restrictive default, read-only; use none for an external IdP that should never reach the admin plane).