OIDC authentication

This guide describes how to configure an OpenID Connect (OIDC)-based SSO provider to issue Airlock credentials to user groups. Combined with RBAC, administrators can define policies such as:

• Only members of the “DBA” group can connect to PostgreSQL.
• Developers are prohibited from SSH access to production servers.

Prerequisites

• Administrative access to the SSO/IdP with users organized into groups.
• An Airlock role with permission to manage oidc resources (available in the editor role by default).
• The airctl utility installed and cluster access configured.

Registering the application in the IdP

Register Airlock in your external identity provider and obtain a client_id and client_secret.

OIDC redirect URL

OIDC uses HTTP redirects to return control to Airlock after authentication. The redirect URL must be agreed upon with the IdP in advance.

URL format:

https://<proxy-address>:443/v1/webapi/oidc/callback

Replace <proxy-address> with the public address of the Airlock Proxy Service (for example, airlock.example.com).

Configuring the OIDC connector

Connectors are created, tested, and deleted via airctl or the Airlock web interface.

Create a file client-secret.txt containing only the client secret. Generate the connector YAML configuration:

airctl sso configure oidc --name keycloak \
  --issuer-url https://keycloak.example.com/realms/master \
  --id airlock \
  --secret $(cat client-secret.txt) \
  --claims-to-roles groups,/users,access \
  --claims-to-roles groups,/admins,editor > oidc-connector.yaml

Example of a complete connector:

kind: oidc
metadata:
  name: keycloak
spec:
  claims_to_roles:
  - claim: groups
    roles:
    - access
    value: /users
  - claim: groups
    roles:
    - editor
    value: /admins
  client_id: airlock
  client_secret: abc123...
  issuer_url: https://keycloak.example.com/realms/master
  redirect_url: https://airlock.example.com:443/v1/webapi/oidc/callback
version: v3

Example: Keycloak

In Keycloak on keycloak.example.com, create a client named airlock. In the airlock-dedicated client scope, add a “Group Membership” mapper so that the groups claim is included in the token.

Testing and applying

Test the connector before applying it:

cat oidc-connector.yaml | airctl sso test

The command opens a browser and attempts to log in through the IdP. If an error occurs, examine the output — the “[OIDC] Claims” section shows all user claims from the IdP.

After a successful test, create the connector:

airctl create -f oidc-connector.yaml

Log in via OIDC:

airsh --proxy=airlock.example.com login --auth=keycloak

Additional parameters

ACR Values

Airlock can send an Authentication Context Class Reference (ACR) when requesting an authorization code. If the acr_values field is set, Airlock expects the same value in the acr claim.

kind: oidc
version: v2
metadata:
  name: oidc-connector
spec:
  issuer_url: "https://oidc.example.com"
  client_id: "xxxxxxxxxxxxxxxxxxxxxxx.example.com"
  client_secret: "zzzzzzzzzzzzzzzzzzzzzzzz"
  redirect_url: "https://airlock.example.com/v1/webapi/oidc/callback"
  display: "Login with Example"
  acr_values: "foo/bar"
  scope: [ "group" ]
  claims_to_roles:
     - claim: "group"
       value: "editor"
       roles: [ "editor" ]
     - claim: "group"
       value: "user"
       roles: [ "access" ]

Max age

The max_age field sets the maximum age of an OIDC session before forced re-authentication. Not set by default. A value of 0s forces re-authentication on every login.

spec:
  max_age: 24h

Prompt

Controls the behavior of the Authorization Server during re-authentication and consent. Airlock uses select_account by default.

spec:
  # Allowed values: none, select_account, login, consent
  prompt: 'login'

Disabling email verification

By default Airlock verifies the email_verified claim. For testing you can enable allow_unverified_email (reduces security):

kind: oidc
version: v2
metadata:
  name: connector
spec:
  allow_unverified_email: true

Username claim

By default Airlock uses the email as the username. To use a different claim:

spec:
  username_claim: preferred_username

Default authentication

To make OIDC the default login method, update cluster_auth_preference:

airctl get cap > cap.yaml

kind: cluster_auth_preference
metadata:
  name: cluster-auth-preference
spec:
  type: oidc
version: v2

airctl create -f cap.yaml

Troubleshooting

If you see Failed to calculate user attributes, check the claims_to_roles mapping — claim values must exactly match what the IdP returns. Use airctl sso test to view all claims.