← All Projects

BeaconSSH

Distributed SSH access using OAuth identity and short-lived certificates

Infrastructure macOS Linux Windows CLI Server • Go PostgreSQL Redis OAuth OpenSSH
#Security#SSH#PKI#Authentication#DevOps

Overview

BeaconSSH is a distributed system that provides secure SSH access using OAuth identity and short-lived SSH certificates. It replaces static SSH keys and manual access management with a certificate-based architecture where access control decisions are enforced at issuance time and validated offline by standard OpenSSH.

Core Idea

Static SSH keys are a persistent security risk. They never expire by default, are difficult to audit, and tend to accumulate across machines without clear ownership. Revoking access means tracking down and removing individual keys from potentially hundreds of hosts.

BeaconSSH solves this by issuing short-lived SSH certificates tied to a user’s OAuth identity. Certificates expire automatically, access policies are centrally defined, and hosts validate certificates locally using standard OpenSSH mechanisms — no runtime dependency on the BeaconSSH server during SSH connections.

Architecture

The system is composed of six components with strict boundaries:

  • User CLI — runs on the user’s machine, handles identity and key management
  • Host CLI — runs on SSH hosts, manages trust of the certificate authority
  • Certificate Server — core control plane, issues signed SSH certificates
  • Diagnostic Server — isolated observability service for telemetry and alerting
  • Web Portal — read-only interface for end users to view activity and preferences
  • Admin Dashboard — operational control for administrators to manage policies and CA lifecycle

The certificate server is stateless per request. The host CLI is not a daemon. The diagnostic server is fully isolated from the authentication path.

How It Works

  1. The user authenticates via OAuth device flow through the CLI
  2. The CLI generates or reuses a local SSH key pair (private key always encrypted)
  3. When SSH access is needed, the CLI checks for a valid certificate
  4. If expired or missing, it requests a new certificate from the server with the public key, requested principals, and OAuth token
  5. The server validates the token, checks authorization policies, and signs a short-lived certificate
  6. The certificate is returned to the CLI and loaded into ssh-agent
  7. The user connects to the host using standard SSH with the certificate
  8. The host validates the certificate against trusted CA public keys — no callback to BeaconSSH

Key Components

User CLI

Runs on the user’s machine. Performs OAuth device authentication, generates and manages SSH key pairs, requests certificates, and handles ssh-agent integration. The private key is always encrypted with a strong passphrase. Certificates are reused while valid and cleaned up on expiry or logout. Provides commands for login, logout, reset, status, trust inspection, diagnostics, and SSH execution.

Host CLI

Runs on SSH hosts via cron. Retrieves the CA public key bundle over HTTPS, verifies its GPG signature, ensures monotonically increasing bundle versions to prevent rollback, and atomically writes trusted CA keys to the TrustedUserCAKeys file. Never handles private keys or authenticates users.

Certificate Server

The core control plane. Validates OAuth tokens, maps identities to internal users, checks authorization policies, and signs short-lived SSH certificates. Stateless per request. Records all issuance events in PostgreSQL for audit. Uses Redis optionally for TTL-based active certificate tracking. Exposes endpoints for CA public key bundles, fingerprints, user management, policy updates, and CA lifecycle control.

Diagnostic Server

Isolated observability service. Receives opt-in telemetry (compressed with Brotli, signed for integrity), validates schemas, enforces size limits, and aggregates data for latency trends, failure rates, and system patterns. Fully separated from authentication and certificate issuance. Cannot affect SSH access even if compromised.

Web Portal

Read-only interface for end users. OAuth-authenticated. Displays certificate usage history, recent activity, device information, and certificate expiry timelines. Does not issue certificates or alter policies.

Admin Dashboard

Operational control for administrators. OAuth-authenticated with elevated permissions. Manages users, access policies, host groups, and CA lifecycle (creation, activation, rotation). Provides visibility into active certificates, audit logs, and diagnostic insights. All actions are logged as immutable audit events.

Security Model

  • Certificates are short-lived and expire automatically
  • Private keys are always encrypted at rest
  • OAuth tokens are stored in the OS keystore when available
  • CA key bundles are GPG-signed with rollback protection
  • The certificate server is stateless — no session hijacking surface
  • The diagnostic server is fully isolated from the auth path
  • SSH access is enforced by OpenSSH on the host, not by BeaconSSH at connection time
  • All administrative actions produce immutable audit records

Philosophy

The system follows strict separation of concerns. Identity stays in the CLI. Authorization stays in the certificate server. Trust distribution stays in the host CLI. Observability stays in the diagnostic server. Visibility stays in the web portals. Enforcement stays in OpenSSH.

No component reaches outside its boundary. No runtime service is required during the actual SSH connection. This makes the system resilient, auditable, and compatible with standard SSH infrastructure.

Status

In development.

Notes

Future improvements: hardware key support, certificate pinning, multi-provider identity federation, host attestation, and automated policy recommendations based on usage patterns.