Component Interaction

This document describes how the core Airlock components interact during installation, agent connection, and user access to resources.

Component Roles

Auth Service is the only cluster component with persistent state storage. Proxy Service and agents do not store cluster configuration: they obtain credentials from Auth Service and maintain a connection to it through Proxy Service.

Overview

  flowchart TB
    subgraph users [Users]
        airsh[airsh / airctl]
        browser[Web Browser]
    end

    subgraph perimeter [Perimeter]
        proxy[Proxy Service :443]
    end

    subgraph cluster [Airlock Cluster]
        auth[Auth Service]
    end

    subgraph private [Private Network]
        agent1[SSH Agent]
        agent2[Kubernetes Agent]
        agent3[Database Agent]
        res1[Linux Server]
        res2[Kubernetes API]
        res3[PostgreSQL]
    end

    airsh -->|TLS login, SSH, kube, db| proxy
    browser -->|HTTPS Web UI| proxy
    proxy <-->|gRPC API| auth
    agent1 -->|reverse tunnel| proxy
    agent2 -->|reverse tunnel| proxy
    agent3 -->|reverse tunnel| proxy
    agent1 --> res1
    agent2 --> res2
    agent3 --> res3
    proxy -->|traffic via tunnel| agent1
    proxy -->|traffic via tunnel| agent2
    proxy -->|traffic via tunnel| agent3

Users connect only to Proxy Service (typically https://airlock.example.com). Resources and agents in the private network do not expose inbound ports to the internet — agents themselves establish outbound reverse tunnels to the proxy.

Auth Service

Auth Service serves as the cluster’s trust center:

• Stores users, roles, SSO connectors, and resource definitions.
• Manages certificate authorities (CAs) for users, nodes, and services.
• Issues short-lived certificates after successful authentication.
• Processes agent join requests (join tokens) and issues long-lived certificates to agents.
• Records audit events.

Auth Service does not accept user traffic for SSH, Kubernetes, or databases directly. Clients and agents communicate with it via the gRPC API; for users, this path goes through Proxy Service.

Proxy Service

Proxy Service is the single entry point:

• Web interface — user login, resource listing, launching applications, SSH and RDP terminal in the browser.
• Identity-Aware Proxy (IAP) — issuing user certificates after SSO or local login; the airsh client uses these certificates for subsequent connections.
• Routing — forwarding SSH, Kubernetes, HTTPS application, and database traffic to the appropriate agent via reverse tunnel.
• TLS routing — multiple protocols over a single port 443.

Proxy Service maintains persistent reverse tunnels from agents. When a user connects to a resource, the proxy selects the agent registered for that resource and forwards traffic through the established tunnel.

Multiple Proxy Service Instances

In production, you can run multiple Proxy Service instances — on different nodes, in different availability zones, or regions. This provides:

• High availability — if one proxy fails, users and agents continue working through the remaining instances.
• Load distribution — incoming traffic is spread across proxies (load balancer or DNS).
• Lower latency — proxies can be placed closer to users or agents to reduce network path.

Typical setup:

  flowchart TB
    users[Users]
    lb[Load Balancer / DNS]
    p1[Proxy 1]
    p2[Proxy 2]
    p3[Proxy N]
    auth[Auth Service]
    agent[Agent]

    users --> lb
    lb --> p1
    lb --> p2
    lb --> p3
    p1 --> auth
    p2 --> auth
    p3 --> auth
    agent -->|tunnel| p1
    agent -->|tunnel| p2
    agent -->|tunnel| p3

Recommendations:

• Place a load balancer or DNS with multiple A records in front of the proxies; use round-robin algorithm, without sticky sessions.
• Agents establish a reverse tunnel to each Proxy Service in the cluster when connecting — see join-token connection.
• All Proxy Service instances use one Auth Service and shared TLS certificates for the same domain (airlock.example.com).
• Auth Service can also run as multiple instances for fault tolerance; cluster state is stored in a shared backend.

Placing proxies in regions close to user teams or agent pools reduces RTT during login and session proxying.

Agents

An agent is an airlock process with one or more services (SSH, Kubernetes, Database, Application, Desktop), deployed near the protected resources.

Joining an Agent to the Cluster

1. An administrator creates a join token: airctl tokens add --type=node (or kube, db, app, etc.).
2. The agent starts with the token and Proxy Service address.
3. The agent establishes a TLS connection to Proxy Service and registers with Auth Service.
4. Auth Service issues a certificate to the agent; the agent opens a reverse tunnel to the proxy.
5. The agent periodically renews its certificate and maintains the tunnel.

The agent does not need a public IP address or open port — outbound access to Proxy Service on port 443 is sufficient.

Agent Behavior During User Access

1. The user authenticates and receives a certificate with roles and attributes.
2. The user initiates a connection (e.g., airsh ssh user@host or airsh db connect).
3. Proxy Service validates the user certificate and RBAC with Auth Service.
4. The proxy routes traffic through the tunnel to the agent serving the resource.
5. The agent re-validates the certificate and policies, then establishes a connection to the target resource (SSH, Kubernetes API, PostgreSQL, etc.).
6. Session events are recorded in the Auth Service audit log.

Users

Login and Certificate Issuance

A user authenticates using one of the following methods:

• Local account — username and password (+ OTP or WebAuthn when MFA is enabled).
• SSO (OIDC / SAML) — external identity provider.

After successful login, Auth Service issues a short-lived certificate containing the username and roles. The airsh client stores the certificate locally; the browser uses a session for the web interface.

airsh login --proxy=airlock.example.com --user=alice

Accessing Resources

At every step, the Airlock certificate is validated; static passwords to target resources are never exposed to the user.

Administrator

Administrators use airctl to manage the cluster: users, roles, tokens, resources. airctl can run:

• on the Auth Service host (with local configuration);
• from a workstation after airsh login (via Proxy Service).

Common Scenarios

Initial Deployment

1. Install Auth Service and Proxy Service on the control node (or in Kubernetes).
2. Configure DNS and TLS for airlock.example.com.
3. Create local users and roles using airctl.
4. Install agents on servers, in Kubernetes clusters, and near databases.
5. Users run airsh login and connect to resources.

Resource Behind a Firewall

Resources and agents remain in the private network without inbound internet access. The agent initiates an outbound connection to Proxy Service; internet users connect only to the proxy, which forwards traffic through the tunnel.

Direct Connection (Without Proxy)

In some configurations, a client with a valid Airlock certificate can connect directly to an agent, bypassing Proxy Service. This reduces latency but requires network reachability of the agent from the client. Routing through the proxy is recommended by default.