SSO (Single sign-on)

This reference document describes the available SSO protocols, configuration options, and parameters in Infrahub.

Supported protocols

info

See Authentication topic for details on the differences between OIDC and OAuth2.

OpenID Connect (OIDC)

OIDC is an identity layer built on top of OAuth 2.0 that standardizes user authentication and identity information exchange.

OAuth 2.0

OAuth 2.0 is an industry-standard protocol for authorization that focuses on client developer simplicity.

Configuration slots

Infrahub provides six predefined configuration slots for identity providers:

Protocol	Available Slots
OIDC	PROVIDER1, PROVIDER2, GOOGLE
OAuth 2.0	PROVIDER1, PROVIDER2, GOOGLE

info

The Google provider configuration is simplified compared to standard providers. It only requires client_id and client_secret parameters, as the other endpoints are pre-configured. Otherwise, the functionality is identical to standard providers.

Configuration parameters

OIDC parameters

Parameter	Environment Variable	TOML Path	Description	Required
Client ID	INFRAHUB_OIDC_<SLOT>_CLIENT_ID	security.oidc_provider_settings.<slot>.client_id	The client identifier issued to the client by the identity provider	Yes
Client Secret	INFRAHUB_OIDC_<SLOT>_CLIENT_SECRET	security.oidc_provider_settings.<slot>.client_secret	The client secret issued to the client by the identity provider	No
Discovery URL	INFRAHUB_OIDC_<SLOT>_DISCOVERY_URL	security.oidc_provider_settings.<slot>.discovery_url	The URL of the OIDC discovery document	Yes
PKCE	INFRAHUB_OIDC_<SLOT>_PKCE_ENABLED	security.oidc_provider_settings.<slot>.pkce_enabled	Indicates if PKCE is enabled	No
Verify id_token signature	INFRAHUB_OIDC_<SLOT>_ID_TOKEN_VERIFY_SIGNATURE	security.oidc_provider_settings.<slot>.id_token_verify_signature	Verify the cryptographic signature, audience and issuer of the OIDC id_token. Defaults to true; disable only for a misconfigured provider	No
Display Label	INFRAHUB_OIDC_<SLOT>_DISPLAY_LABEL	security.oidc_provider_settings.<slot>.display_label	The label displayed on the login button	No
Icon	INFRAHUB_OIDC_<SLOT>_ICON	security.oidc_provider_settings.<slot>.icon	The Material Design icon name to display on the login button	No
Enabled Providers	INFRAHUB_SECURITY_OIDC_PROVIDERS	security.oidc_providers	Array of enabled OIDC provider slots	Yes*

*At least one provider must be specified if using OIDC.

OAuth 2.0 parameters

Parameter	Environment Variable	TOML Path	Description	Required
Client ID	INFRAHUB_OAUTH2_<SLOT>_CLIENT_ID	security.oauth2_provider_settings.<slot>.client_id	The client identifier issued to the client by the identity provider	Yes
Client Secret	INFRAHUB_OAUTH2_<SLOT>_CLIENT_SECRET	security.oauth2_provider_settings.<slot>.client_secret	The client secret issued to the client by the identity provider	No
Authorization URL	INFRAHUB_OAUTH2_<SLOT>_AUTHORIZATION_URL	security.oauth2_provider_settings.<slot>.authorization_url	The authorization endpoint URL	Yes
Token URL	INFRAHUB_OAUTH2_<SLOT>_TOKEN_URL	security.oauth2_provider_settings.<slot>.token_url	The token endpoint URL	Yes
Userinfo URL	INFRAHUB_OAUTH2_<SLOT>_USERINFO_URL	security.oauth2_provider_settings.<slot>.userinfo_url	The userinfo endpoint URL	Yes
PKCE	INFRAHUB_OAUTH2_<SLOT>_PKCE_ENABLED	security.oauth2_provider_settings.<slot>.pkce_enabled	Indicates if PKCE is enabled	No
Display Label	INFRAHUB_OAUTH2_<SLOT>_DISPLAY_LABEL	security.oauth2_provider_settings.<slot>.display_label	The label displayed on the login button	No
Icon	INFRAHUB_OAUTH2_<SLOT>_ICON	security.oauth2_provider_settings.<slot>.icon	The Material Design icon name to display on the login button	No
Enabled Providers	INFRAHUB_SECURITY_OAUTH2_PROVIDERS	security.oauth2_providers	Array of enabled OAuth 2.0 provider slots	Yes*

*At least one provider must be specified if using OAuth 2.0.

Redirect URI formats

When configuring a provider in an external identity system, use the following format for the redirect URI:

https://<your-infrahub-hostname>/auth/<protocol>/<provider-slot>/callback

Protocol	Format Example
OIDC	https://infrahub.example.com/auth/oidc/provider1/callback
OAuth 2.0	https://infrahub.example.com/auth/oauth2/provider1/callback

User attributes mapping

Infrahub maps the following claims from identity providers to its internal user model:

Infrahub Field	OIDC Claim	OAuth 2.0 Field	Notes
Identity anchor	sub	sub	Provider-issued subject identifier; used to resolve accounts across logins. Requires the openid scope.
Account name	name	name	Used as the account name on creation. If an account with that name already exists, email is used instead, and the login fails when the provider sends no email or an account with that email name also exists. When the account name fallback is enabled, an existing account with that name that is not linked to an identity is adopted instead.
Display label	name	name	Synced on every login.
Group memberships	groups	groups	Read from the groups claim by default; override per provider with groups_claim when your provider emits memberships under a different key (e.g., roles). Applied on every login, additively — memberships are never removed automatically. See group mapping.

Account name fallback

On a user's first SSO login (before an identity is linked), Infrahub can adopt a pre-existing account whose name matches the provider's display name, as long as that account has never been linked to another identity. This eases upgrades where local accounts already exist. The fallback is disabled by default from Infrahub 1.12.

Parameter	Environment Variable	TOML Path	Description	Default
Account name fallback	INFRAHUB_SECURITY_SSO_ACCOUNT_NAME_FALLBACK	security.sso_account_name_fallback	Allow a first-time SSO login to adopt a pre-existing account that matches by display name. When disabled, such a login creates a separate account, named or rejected as described in the account name row above.	false

warning

This fallback is a transitional convenience and is deprecated; it will be removed in Infrahub 1.13. While the fallback is enabled, each Infrahub process logs a warning when it loads its configuration. Enable it only while existing SSO users complete their first login, then set INFRAHUB_SECURITY_SSO_ACCOUNT_NAME_FALLBACK=false again so that accounts are resolved only by the immutable sub identity anchor. See How to migrate off the SSO account-name fallback.

Examples

OIDC configuration example

[security.oidc_provider_settings.provider1]
client_id = "client-id-from-idp"
client_secret = "client-secret-from-idp"
discovery_url = "https://login.microsoftonline.com/tenant-id/v2.0/.well-known/openid-configuration"
display_label = "Microsoft Entra ID"
icon = "mdi:microsoft"

[security]
oidc_providers = ["provider1"]

OAuth 2.0 configuration example

[security.oauth2_provider_settings.provider1]
client_id = "client-id-from-idp"
client_secret = "client-secret-from-idp"
authorization_url = "https://login.microsoftonline.com/tenant-id/oauth2/v2.0/authorize"
token_url = "https://login.microsoftonline.com/tenant-id/oauth2/v2.0/token"
userinfo_url = "https://graph.microsoft.com/oidc/userinfo"
display_label = "Microsoft Entra ID"
icon = "mdi:microsoft"

[security]
oauth2_providers = ["provider1"]