README
¶
Epithet makes SSH certificates easy
Epithet is an SSH certificate authority that replaces static authorized_keys with short-lived certificates (2-10 minutes). It creates on-demand SSH agents for each outbound connection, enabling real-time policy enforcement without touching your target hosts.
Authentication is OIDC only, handled in-process by the broker — no plugins, no subprocess auth commands.
Requires OpenSSH 9.4+ on the client (for Tag/Match tagged; see below).
Quick start
1. Build epithet:
git clone https://github.com/epithet-ssh/epithet.git
cd epithet
make build
2. Start the agent:
epithet agent --ca-url https://your-ca.example.com --name work
The agent fetches its OIDC issuer and client ID from the CA's /discovery
endpoint — nothing to configure locally.
3. Tag the hosts this profile should handle, then include the generated config (~/.ssh/config):
Host *.example.com
Tag epithet-work
Include ~/.epithet/run/*/ssh-config.conf # must come after Tag lines
4. SSH as normal:
ssh server.example.com
First connection opens your browser for authentication (~2-5 seconds). Subsequent connections reuse the refreshed token (~100-200ms).
How it works
When you run ssh server.example.com, OpenSSH's Match tagged triggers epithet match for hosts you've tagged in your own ssh config. epithet match asks the broker for a certificate. The broker authenticates in-process via OIDC, requests a signed certificate from the CA (which checks policy in real time), and spins up a per-connection SSH agent with the short-lived certificate. See architecture for detailed sequence diagrams.
Components:
- Broker (
epithet agent): Daemon managing OIDC authentication state and certificate lifecycle. Creates per-connection SSH agents. - CA Server (
epithet ca): Signs SSH certificates after passing the caller's token through to a policy server for validation. - Policy Server (
epithet policy): Validates tokens and makes authorization decisions - who can access what hosts as which users. - Per-connection Agents: In-process SSH agents, one per unique connection, serving a certificate minted for that connection alone.
Commands
| Command | Description |
|---|---|
epithet agent |
Start the broker daemon that manages certificates and agents |
epithet agent inspect |
Query a running broker's state |
epithet server |
Run the CA and policy server as supervised subprocesses behind one port |
epithet match |
Called by SSH Match exec to trigger certificate flow |
epithet ca |
Run the certificate authority server |
epithet policy |
Run the policy server with OIDC-based authorization |
Documentation
- Architecture - How epithet works under the hood
- Policy Server Guide - Setup and configuration for the policy server
- Authentication - The OIDC token contract and in-process auth flow
- OIDC Setup - Provider-specific OIDC configuration (Google, Okta, Azure AD)
- Releasing - Notes on cutting releases
Development
make build # Build all binaries
make test # Run tests
make clean # Clean build artifacts
Requirements: Go 1.25+
License
Apache 2.0
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
epithet
command
|
|
|
pkg
|
|
|
auth/oidc
Package oidc performs OIDC/OAuth2 authentication and returns an ID token.
|
Package oidc performs OIDC/OAuth2 authentication and returns an ID token. |
|
breakerpool
Package breakerpool provides a generic circuit breaker pool with priority-based failover.
|
Package breakerpool provides a generic circuit breaker pool with priority-based failover. |
|
oidctest
Package oidctest provides a minimal in-process OIDC provider for tests.
|
Package oidctest provides a minimal in-process OIDC provider for tests. |
|
serviceauth
Package serviceauth mints and verifies short-lived, request-bound JWTs that authenticate CA -> policy-server requests.
|
Package serviceauth mints and verifies short-lived, request-bound JWTs that authenticate CA -> policy-server requests. |
|
tlsconfig
Package tlsconfig provides shared TLS configuration for HTTP clients.
|
Package tlsconfig provides shared TLS configuration for HTTP clients. |
|
wire
Package wire holds every type that crosses a process boundary (CA, policy server, CA client).
|
Package wire holds every type that crosses a process boundary (CA, policy server, CA client). |
|
test
|
|