Epithet is an SSH certificate authority that replaces static authorized_keys with short-lived certificates (2-10 minutes) and authentication over OIDC. It creates on-demand SSH agents for each outbound connection, enabling real-time policy enforcement without touching your target hosts.
1. Build epithet:
git clone https://github.com/epithet-ssh/epithet.git
cd epithet
make build2. Start the agent:
epithet agent --ca-url https://your-ca.example.comThe agent discovers its OIDC issuer and client ID from the CA's Link header on the root response — nothing to configure locally.
3. Tag the hosts this profile should handle, then include the generated config (~/.ssh/config):
Host *.example.com
Tag epithet
Include ~/.epithet/run/*/ssh-config.conf # must come after Tag lines4. SSH as normal:
ssh server.example.comFirst connection opens your browser for authentication (~2-5 seconds). Subsequent connections reuse the refreshed token.
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.
| 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 tagged ... exec to trigger certificate flow |
epithet ca |
Run the certificate authority server |
epithet policy |
Run the policy server with OIDC-based authorization |
- 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
make build # Build all binaries
make test # Run tests
make clean # Clean build artifactsRequirements: Go 1.25+
Requires OpenSSH 9.4+ on the client (for Tag/Match tagged; see below).
Apache 2.0