SSO / OIDC Integration

Configure OpenID Connect (OIDC) Single Sign-On (SSO) to federate authentication and map provider claims to Infralo permissions.

Infralo supports enterprise Single Sign-On (SSO) using the OpenID Connect (OIDC) protocol. When enabled, authentication is delegated to your Identity Provider (IdP) such as Keycloak, Okta, Auth0, or Entra ID.

Backend Configuration

To activate and configure OIDC, set the following environment variables in your Infralo backend environment:

Environment Variable	Required	Description
`LOGIN_TYPE`	Yes	Set to `oidc` to enable SSO. If not set, the platform defaults to basic authentication (`basic`).
`OIDC_CLIENT_ID`	Yes	The Client ID registered in your Identity Provider.
`OIDC_CLIENT_SECRET`	Yes	The Client Secret associated with the Client ID.
`OIDC_DISCOVERY_URL`	Yes	The discovery endpoint (metadata URL) of the OIDC provider (e.g. `https://your-idp.com/realms/myrealm/.well-known/openid-configuration`).
`OIDC_REDIRECT_URL`	Yes	The callback URL that users are redirected to after IdP authentication (e.g., `https://infralo.yourcompany.com/api/v1/auth/oidc/callback`).
`OIDC_ALLOWED_PERMISSIONS`	No	Comma-separated list of required claims prefixes to filter allowed users (e.g. `role:admin,group:infralo-users`).

Required Parameters

If LOGIN_TYPE=oidc is enabled, the backend will fail to start if OIDC_CLIENT_ID, OIDC_CLIENT_SECRET, OIDC_DISCOVERY_URL, or OIDC_REDIRECT_URL is missing.

Claim Mapping Logic

When a user successfully authenticates with the OIDC provider, Infralo retrieves the user info claims from the provider's token and extracts authorization claims.

The system uses specific prefixes to normalize claims from different parts of the OIDC token:

       IdP ID Token Claims
                │
                ├─► user_info.roles ───────────────► prefix: role:
                ├─► resource_access.<client_id> ───► prefix: client:<client_id>:
                ├─► realm_access.roles ────────────► prefix: realm:
                └─► user_info.groups ──────────────► prefix: group:

1. Top-Level Roles (`role:`)

Claim Source: roles list at the root of the user info payload.
Format: role:<role_name>
Example: A role of developer maps to role:developer.

2. Client Resource Access (`client:`)

Claim Source: Client-scoped roles found in resource_access.<client_id>.roles.
Format: client:<client_id>:<client_role>
Example: If client_id is infralo-gateway and the user has role editor in that client, it maps to client:infralo-gateway:editor.

3. Realm Access (`realm:`)

Claim Source: Realm-wide roles in Keycloak/OIDC found in realm_access.roles.
Format: realm:<realm_role>
Example: A realm role of offline_access maps to realm:offline_access.

4. Group Memberships (`group:`)

Claim Source: User groups list found in the groups claim.
Format: group:<group_name>
Example: A group membership of /engineering/ai maps to group:/engineering/ai.

Case Normalization

All extracted claims are converted to lowercase during normalization.

The Allowed Permissions Filter

You can control exactly which users are allowed to log into Infralo using the OIDC_ALLOWED_PERMISSIONS environment variable.

Extraction: The backend extracts all normalized claims from the authenticated OIDC token.
Intersection Check: The backend verifies if there is any intersection between the user's extracted claims and the CSV list specified in OIDC_ALLOWED_PERMISSIONS.
- If matches exist (or if OIDC_ALLOWED_PERMISSIONS is empty/undefined), login succeeds.
- If no matches exist, access is denied immediately with a 403 Forbidden response: "User does not have required permissions".

Example Configurations

Allow any authenticated user: Leave OIDC_ALLOWED_PERMISSIONS empty.
Limit to specific IdP group: Set OIDC_ALLOWED_PERMISSIONS=group:ai-team.
Limit to specific client roles or realm roles: Set OIDC_ALLOWED_PERMISSIONS=client:infralo-app:admin,role:platform-operator.

User Auto-Provisioning

When an authorized user logs in via SSO/OIDC for the first time, Infralo provisions their account automatically:

Lookup by Subject: The backend queries the database using the unique OIDC Subject (sub) and Issuer (iss).
Email Linking: If no matching subject is found, the backend looks for an existing account with the same email. If found, the OIDC subject is linked to this account for future logins, and user details (like profile pictures) are synchronized.
Automatic Creation: If no account exists with that subject or email, a new global user is created:
- Username: Derived from their email prefix (appended with random digits if collisions occur).
- Tenant: Assigned to the default system tenant.
- Global Role: Assigned the standard GlobalRole.MEMBER role by default (see Global Roles).
- Status: Provisioned directly as Active.

On this page