SAML authentication

This guide describes how to configure SAML for single sign-on (SSO) in Airlock. 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.

Airlock acts as a SAML Service Provider (SP) and accepts authentication from an external Identity Provider (IdP).

Prerequisites

• A deployed SAML IdP (for example, Active Directory Federation Services) with users organized into groups.
• An Airlock role with permission to manage saml resources (available in the editor role).
• The airctl utility installed.

SAML concepts

SAML authentication involves:

1. IdP (Identity Provider) — the provider that authenticates the user and issues a SAML assertion.
2. SP (Service Provider) — Airlock, which accepts the assertion and creates a session.
3. ACS URL — the Airlock endpoint where the IdP sends the SAML response: https://<proxy>/v1/webapi/saml/acs.
4. Entity Descriptor — IdP XML metadata containing certificates and endpoints.
5. Attributes (claims) — groups, email, username — mapped to Airlock roles via attributes_to_roles.

Step 1. Configure the IdP (ADFS example)

In Active Directory Federation Services, configure:

Claims Provider Trust — incoming claims from Active Directory:

• Name ID: LDAP attribute E-Mail-Addresses → Name ID
• Group: group membership claim for mapping to roles
• If needed: SAM-Account-Name → Windows account name, E-Mail-Addresses → UPN

Relying Party Trust — trust for Airlock:

• Display name: Airlock
• SAML 2.0 Web SSO URL: https://airlock.example.com/v1/webapi/saml/acs
• Relying party trust identifier: the same ACS URL
• Claim Issuance Policy: send at least Name ID and Group

Ensure that Active Directory users have the email field populated.

Step 2. Create Airlock roles

Create roles for administrators and regular users.

# admin-role.yaml
kind: role
version: v3
metadata:
  name: admin
spec:
  options:
    max_session_ttl: "8h0m0s"
  allow:
    logins: [ root ]
    node_labels:
      "*": "*"
    rules:
      - resources: ["*"]
        verbs: ["*"]

# user-role.yaml
kind: role
version: v3
metadata:
  name: dev
spec:
  options:
    max_session_ttl: "1h"
  allow:
    logins:
      - '{{external["http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname"]}}'
      - ubuntu
    node_labels:
      "access": "relaxed"

The dev role allows login only to nodes labeled access: relaxed. The {{external[...]}} template substitutes the SAML attribute value as a permitted OS login.

Step 3. Create the SAML connector

Generate the connector configuration:

airctl sso configure saml --acs https://airlock.example.com/v1/webapi/saml/acs \
  --preset adfs \
  --entity-descriptor https://adfs.example.com/FederationMetadata/2007-06/FederationMetadata.xml \
  --attributes-to-roles http://schemas.xmlsoap.org/claims/Group,teleadmins,editor \
  --attributes-to-roles http://schemas.xmlsoap.org/claims/Group,Users,access \
  > adfs.yaml

Test the connector before applying it:

cat adfs.yaml | airctl sso test

Apply the connector:

airctl create -f adfs.yaml

Exporting the signing key

Export the Airlock signing certificate and add it to the IdP as a certificate for signature verification:

airctl saml export adfs > saml.cer

Logging in via SAML

airsh --proxy=airlock.example.com login

If you have multiple SAML connectors, specify the name:

airsh login --auth=adfs

Attribute mapping

The attributes_to_roles field maps SAML attributes to Airlock roles:

kind: saml
version: v2
metadata:
  name: saml-connector
spec:
  acs: https://airlock.example.com/v1/webapi/saml/acs
  entity_descriptor: |
    <?xml version="1.0"?>
    <!-- IdP XML metadata -->
  attributes_to_roles:
    - name: "groups"
      value: "admins"
      roles: ["editor"]
    - name: "groups"
      value: "developers"
      roles: ["access"]

The full attribute name depends on the IdP. For ADFS, groups often use the URI http://schemas.xmlsoap.org/claims/Group.

Dynamic traits

SAML attribute values are available in roles via {{external["attribute-name"]}}. This allows assigning OS logins, environment labels, and other parameters based on IdP data.

Default authentication

To make SAML the default login method:

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

airctl get cap > cap.yaml
# edit cap.yaml
airctl create -f cap.yaml

Troubleshooting

• Verify that the ACS URL in the IdP and the connector match.
• Confirm that the IdP sends the required attributes (groups, email).
• Use airctl sso test to diagnose the SAML flow.
• If you see signature errors, check that the Airlock certificate has been added to the IdP.