Authorization

Authentication and authorization

Airlock handles both authentication and authorization:

• Authentication — verifying the identity of a user or service.
• Authorization — checking access rights to a resource.

This document describes authorization of users and services using RBAC.

Users and roles

Airlock supports several account types:

• Interactive and non-interactive.
• Local and external.

After successful authentication, each user is assigned one or more roles.

Interactive users

Interactive users can be local or external. Local accounts store a password hash and MFA data in the Airlock backend. External accounts authenticate through an identity provider using SSO protocols — OAuth 2.0, OIDC, or SAML.

External users from SSO

Each time an SSO user logs in, Airlock creates a temporary account record that expires automatically with the SSO session and writes events to the audit log. This prevents name conflicts with local users.

External users from other clusters

A user can be external to an Airlock cluster if another cluster or CA issues a certificate that this cluster trusts. In this case, Airlock applies trusted cluster role-mapping logic.

Local interactive users

Local interactive users have a record in the Airlock backend with credentials. An administrator creates accounts via airctl users add or the API.

Each local Airlock user must be associated with one or more roles — this is called “role mapping”.

Non-interactive users

Airlock supports non-interactive users for automation services (for example, CI/CD pipelines or microservices). Local non-interactive users have a record mapping a name to roles, but no credentials in the database.

Role-based access control (RBAC)

Each Airlock user is assigned one or more roles that determine access to resources and the Airlock API.

Allow and deny rules

Each role contains two rule lists: allow and deny:

• Everything is denied by default.
• deny rules are evaluated first and take precedence.
• A rule consists of resources and verbs.

Example allow rule for listing recorded SSH or Kubernetes sessions:

allow:
  - resources: [session]
    verbs: [list]

Principals

Roles define which principals (for example, Linux OS users or Kubernetes groups) users with that role may use:

spec:
  allow:
    logins: [ubuntu]
    kubernetes_groups: [viewer]

If a user has multiple roles, the principal lists are merged.

Labels

Role labels define which resources the rules apply to. Example granting access to SSH nodes and Kubernetes clusters:

spec:
  allow:
    node_labels:
      'environment': '^test|staging$'
    kubernetes_labels:
      'region': 'us-west-*'
      'cluster_name': '^us.*\.example\.com$'

Label matching rules:

• For an allow rule to match, all labels in the rule must match.
• For a deny rule to match, any single label match is sufficient.

Example: user Alice has roles dev and prod. The dev role allows SSH as root and full Kubernetes access as system:masters for resources with labels test or stage. The prod role allows SSH as ubuntu and Kubernetes access as view for resources with the label prod.

• Alice can SSH as root to a server labelled test or stage.
• Alice cannot SSH as root to a server labelled prod — the prod role only permits ubuntu.

Role templates

Roles support template variables:

spec:
  allow:
    logins: ['{{internal.logins}}']
    kubernetes_groups: ['{{external.groups}}']

Any role with variable interpolation is considered a role template.

Interpolation rules:

• If external.groups is the list ["dev", "prod"], the expression ["{{external.groups}}"] interpolates to ["dev", "prod"].
• If a variable is absent, the expression "{{external.groups}}" produces an empty string.
• Invalid values (for example, -foo as a Unix login) are omitted.

Role templates are evaluated at the moment of resource access by the proxy or node. Variables from the identity provider are encoded in X.509 certificate extensions.

Role conditions

The where field restricts access by conditions. Example — access only to one’s own sessions:

kind: role
metadata:
  name: only-own-sessions
spec:
  allow:
    rules:
    - resources: [session]
      verbs: [list, read]
      where: contains(session.participants, user.metadata.name)

Role options

In addition to allow and deny rules, roles define connection options:

kind: role
version: v5
metadata:
  name: relaxed
spec:
  options:
    max_session_ttl: 8h
    lock: strict

When options conflict across multiple roles, Airlock selects the most restrictive value (for example, the smaller max_session_ttl or strict mode over best_effort).

Access Requests

Roles can allow requesting elevated privileges — additional roles or individual resources. Roles define who may review requests and how many approvals or denials are required. In Airlock this feature is available through the web interface, airsh, and the built-in requester and reviewer roles.

spec:
  allow:
    review_requests:
      roles: ['dbadmin']
    request:
      roles: ['common', 'dev-*']
      thresholds:
        - approve: 2
          deny: 1

Additional resources