Skip to content

OpenID Connect (OIDC) authorization

Authorizes a user request via OpenID Connect (OIDC).

There is no need that the actual user exists in any way on the host machine of Bifröst. Even if the local environment is used together with createIfAbsent and updateIfDifferent set to true, it will create/update the users. There is no need for tools like Puppet or Ansible.

This provides an easy way for SSO in all types of organizations, small or big. See use cases for more details.

Currently, the following flow of OpenID Connect is supported:

Device Auth

Properties

type

Authorization Type = "oidc"

Has to be set to oidcDeviceAuth to enable the OIDC DeviceAuth authorization.

issuer

URL Core

The issuer is the URL identifier for the service which is issued by your identity provider.

The issuer and its discovered device-authorization and token endpoints must use HTTPS. Bifröst rejects HTTP endpoints before transmitting client credentials. Private certificate authorities can be added to Bifröst's bundled trust store through the standard SSL_CERT_FILE environment variable.

Examples
  • https://login.microsoftonline.com/my-great-tenant-uuid/v2.0
  • https://accounts.google.com
  • https://login.salesforce.com

clientId

string Core

Client ID issued by your identity provider.

clientSecret

string Core

Secret for the corresponding Client ID.

The provider metadata must support client-secret authentication at the token endpoint. Bifröst prefers client_secret_basic, falls back to client_secret_post when explicitly advertised, and uses the OpenID Connect default client_secret_basic when token_endpoint_auth_methods_supported is omitted. Providers that advertise neither method are rejected.

Redirects from the device-authorization and token endpoints are followed only when the destination has the same scheme and host as the configured endpoint. Cross-origin redirects are returned without being followed so that neither an Authorization header nor a client_secret_post request body can be forwarded to another origin.

scopes

[]string Core = ["openid", "profile", "email"]

Scopes to request the token from the identity provider for.

For refresh-token verification, configure the scopes and client settings required by your provider to issue a refresh token (often offline_access). The default scopes (openid, profile, email) do not include offline_access, and Bifröst does not add it automatically.

Example with offline_access
1
2
3
4
5
scopes:
  - openid
  - email
  - profile
  - offline_access

retrieveIdToken

bool = true

Will retrieve the ID Token and makes it available in the corresponding context via idToken.

If the identity provider does not return a new ID token during refresh, the previously verified token remains available only until it expires. Reconnecting with a loginAllowed rule that requires its claims may then fail even while the refresh grant remains valid; an expired ID token is never treated as fresh evidence.

retrieveUserInfo

bool = false

Will retrieve the UserInfo and makes it available in the corresponding context via userInfo.

forceDisposeSessionOn

string = "lostAccess"

Controls forced session disposal when OIDC access can no longer be verified. Can be one of:

  • lostAccess: Require a refresh token at login and check it while the session is active, even if refreshToken.mode is never. Dispose the session if its refresh token is missing or permanently rejected (for example, invalid_grant), or if no successful verification occurs within refreshToken.maxUnverifiedFor during an identity-provider outage. This is the default.
  • never: Do not dispose a session because of a failed OIDC refresh. refreshToken.mode: proactive still requires a refresh token and refreshes it; set both properties to never to restore the previous behavior.

With lostAccess, a login without a refresh token is denied, and existing OIDC sessions without a refresh token or a recorded identity are disposed. If a refresh returns a new ID token, its issuer and subject must match the identity bound to the session. A refresh without a new ID token still checks that the provider accepts the refresh grant; it does not re-evaluate claims. This does not require UserInfo or periodically re-evaluate loginAllowed.

If verification of a newly returned ID token temporarily fails (for example, because JWKS is unavailable), rotated credentials are stored as pending. They cannot authorize a reconnect or replace trusted claims until verification succeeds. Failure beyond refreshToken.maxUnverifiedFor disposes the session.

refreshToken

Refresh Token

Settings for refresh-token verification. Refresh is enabled when forceDisposeSessionOn is lostAccess or refreshToken.mode is proactive. When enabled, a login without a refresh token is denied.

Refresh token

mode

string = "proactive"

Can be one of:

  • proactive: Refresh the token at the configured percentage of its lifetime. This does not force session disposal unless forceDisposeSessionOn: lostAccess is enabled. This is the default.
  • never: Do not refresh tokens proactively unless forceDisposeSessionOn: lostAccess is enabled.

atLifetimePercent

integer = 70

Percentage of the token lifetime at which to refresh it, from 1 through 99.

fallbackEvery

Duration = "15m"

Positive interval between refresh attempts when the token lifetime is unavailable.

maxUnverifiedFor

Duration = "30m"

Positive maximum time without successful refresh verification during transient identity-provider failures before lostAccess forces session disposal.

For lostAccess, a refresh is scheduled before this deadline if the configured access-token percentage would be later. A session that has already exceeded the deadline is disposed even if the identity provider becomes available again.

Session cleanup

When a session is disposed (for example, after expiry or lost OIDC access), housekeeping removes the local OIDC authorization token after successful session and environment disposal, without contacting the identity provider or restoring the authorization. This applies both before and after the session's retention period ends. After retention, housekeeping can delete the session once environment cleanup succeeds, subject to the configured audit failure policy. Bifröst does not revoke access or refresh tokens at the identity provider; OIDC disposal only removes the local token.

Context

This authorization will produce a context of type Authorization OIDC.

Examples

  1. Use the default lostAccess policy with a provider that requires offline_access to issue refresh tokens: 
    1
2
3
4
5
6
7
8
9
    type: oidcDeviceAuth
issuer: https://login.microsoftonline.com/my-great-tenant-uuid/v2.0
clientId: my-great-client-uuid
clientSecret: very-secret-secret
scopes:
  - openid
  - email
  - profile
  - offline_access
  2. Retain the previous behavior temporarily while enabling refresh tokens at the identity provider: 
    1
2
3
4
5
6
7
    type: oidcDeviceAuth
issuer: https://login.microsoftonline.com/my-great-tenant-uuid/v2.0
clientId: my-great-client-uuid
clientSecret: very-secret-secret
forceDisposeSessionOn: never
refreshToken:
  mode: never

Compatibility

linux darwin windows
/ / /