Tyler King
e7fc9fa5e1
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>
72 lines
1.9 KiB
Markdown
72 lines
1.9 KiB
Markdown
# 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.**
|
|
|
|
```toml
|
|
[auth]
|
|
mode = "accept-all"
|
|
```
|
|
|
|
## authorized-keys
|
|
|
|
Standard SSH authorized_keys file, same format as OpenSSH.
|
|
|
|
```toml
|
|
[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.
|
|
|
|
```toml
|
|
[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
|
|
|
|
1. Agent obtains an OAuth token from Entra via `client_credentials` flow
|
|
2. Agent connects via SSH: `ssh agent-name@proxy -p 2222`
|
|
3. Agent provides the OAuth token as the SSH password
|
|
4. Bascule validates the token against Entra's JWKS
|
|
5. 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:
|
|
1. SSH public key (if configured)
|
|
2. Password / token-as-password (if configured)
|
|
|
|
Humans use SSH keys. Agents use token-as-password. Both work through the same SSH server.
|