SHA256

Tyler King e7fc9fa5e1 feat: structured logging, tracing spans, comprehensive documentation

Observability:
  Structured JSON logging via BASCULE_LOG_FORMAT=json
  Tracing spans on auth (method, principal, peer)
  Tracing spans on session lifecycle (id, principal, backend, source_ip)
  Tracing spans on exec requests (session_id, command)
  Config: [telemetry] and [metrics] sections (OTel export planned)

Documentation (8 files, 489 lines):
  docs/quickstart.md — three-path getting started
  docs/configuration.md — full config reference with examples
  docs/authentication.md — all auth modes with setup guides
  docs/architecture.md — backends, traits, extension model, security
  docs/observability.md — logging, tracing, metrics
  docs/comparison.md — vs Teleport, Boundary, StrongDM
  images/README.md — curated image catalog
  README.md — features, comparison, quickstart, extension example

1557 lines Rust, 489 lines docs, 0 substrate deps.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

2026-04-04 23:45:03 -04:00

1.9 KiB

Raw Blame History

Authentication

Bascule supports multiple authentication methods. Configure via [auth] in your TOML config.

accept-all (Development Only)

Accepts any SSH key or password. Never use in production.

[auth]
mode = "accept-all"

authorized-keys

Standard SSH authorized_keys file, same format as OpenSSH.

[auth]
mode = "authorized-keys"
authorized_keys_path = "/etc/bascule/authorized_keys"

The file format is identical to ~/.ssh/authorized_keys:

ssh-ed25519 AAAAC3NzaC1l... user@host
ssh-rsa AAAAB3NzaC1yc2... another-user@host

Entra Agent ID (AI Agents)

Microsoft Entra Agent ID authentication for AI agents. Agents present their OAuth token as the SSH password.

[auth]
mode = "accept-all"   # For human SSH key auth (or authorized-keys)

[auth.agent_id]
tenant_id = "your-entra-tenant-id"
audiences = ["api://bascule-proxy"]
multi_tenant = false

How agents authenticate

Agent obtains an OAuth token from Entra via client_credentials flow
Agent connects via SSH: ssh agent-name@proxy -p 2222
Agent provides the OAuth token as the SSH password
Bascule validates the token against Entra's JWKS
Session created with auth_method: "agent-id" and full agent metadata

Agent metadata extracted

From the validated token, Bascule extracts:

Agent application ID
Display name
Agent type (from custom claims)
Blueprint ID (Entra Agent ID template)
Sponsor (human/org that registered the agent)
On-behalf-of (if agent is delegated)
Scopes and roles

Your SessionHandler receives this in SessionInfo and can apply different policies for human vs agent sessions.

Composing Auth Providers

Bascule tries auth methods in order:

SSH public key (if configured)
Password / token-as-password (if configured)

Humans use SSH keys. Agents use token-as-password. Both work through the same SSH server.

1.9 KiB Raw Blame History