epithet

Epithet makes SSH certificates easy

Epithet is an SSH certificate authority system that replaces traditional SSH key-based authentication with short-lived certificates. Instead of managing authorized_keys files across your infrastructure, epithet creates on-demand SSH agents for outbound connections, each with a fresh certificate valid for just a few minutes.

Quick Start

1. Build epithet:

git clone https://github.com/epithet-ssh/epithet.git
cd epithet
make build

2. Start the agent (using Google Workspace OIDC):

epithet agent \
  --match '*.example.com' \
  --ca-url https://your-ca.example.com \
  --auth "epithet auth oidc --issuer https://accounts.google.com --client-id YOUR_CLIENT_ID"

3. Add to your SSH config (~/.ssh/config):

Include ~/.epithet/run/*/ssh-config.conf

4. SSH as normal:

ssh server.example.com

First connection opens your browser for authentication (~2-5 seconds). Subsequent connections use cached tokens (~100-200ms).

How It Works

sequenceDiagram
    box ssh invocation on a client
        participant ssh
        participant match
        participant broker
    end

    box out on the internet
        participant ca
        participant policy
    end

    ssh ->> match: Match exec ...
    match ->> broker: {matchdata}

    create participant auth
    broker ->> auth: {state}

    destroy auth
    auth ->> broker: {token, state, error}

    broker ->> ca: {token, pubkey}
    ca ->> policy: {token, pubkey}
    policy ->> ca: {cert-params}
    ca ->> broker: {cert}

    create participant agent
    broker ->> agent: create agent
    broker ->> match: {true/false, error}
    match ->> ssh: {true/false}
    ssh ->> agent: list keys
    agent ->> ssh: {cert, pubkey}
    ssh ->> agent: sign-with-cert

Components:

• Broker (epithet agent): Daemon managing authentication state and certificate lifecycle. Creates per-connection SSH agents.
• CA Server (epithet ca): Signs SSH certificates after validating tokens against a policy server.
• Policy Server (epithet policy): Makes authorization decisions - who can access what hosts as which users.
• Per-connection Agents: In-process SSH agents, one per unique connection, serving short-lived certificates.

Commands

Authentication

Epithet supports pluggable authentication via external plugins. The broker invokes these to obtain tokens for certificate requests.

Built-in OIDC/OAuth2

Works with Google Workspace, Okta, Azure AD, and any OIDC-compliant provider:

epithet agent \
  --match '*.example.com' \
  --ca-url https://ca.example.com \
  --auth "epithet auth oidc --issuer https://accounts.google.com --client-id YOUR_CLIENT_ID"

Features: PKCE support, automatic token refresh, browser-based auth flow.

See docs/oidc-setup.md for provider-specific setup.

Custom Auth Plugins

Write plugins in any language using a simple protocol:

• stdin: State from previous invocation
• stdout: Authentication token
• fd 3: New state to persist
• Exit 0: Success

See docs/authentication.md for details.

Configuration

Config File

Epithet uses a simple key-value format:

# ~/.config/epithet/agent.conf
match *.work.example.com
match *.dev.example.com
ca-url https://ca.example.com
auth epithet auth oidc --issuer https://accounts.google.com --client-id YOUR_CLIENT_ID

Load with: epithet agent --config ~/.config/epithet/agent.conf

SSH Integration

The broker auto-generates SSH config at ~/.epithet/run/<hash>/ssh-config.conf. Include it:

Include ~/.epithet/run/*/ssh-config.conf

Multiple Brokers

Run separate brokers for different environments (work, personal, etc.) with unique socket paths:

epithet agent --broker ~/.epithet/work.sock --match '*.work.example.com' ...
epithet agent --broker ~/.epithet/personal.sock --match '*.personal.example.com' ...

Documentation

• Policy Server Guide - Setup and configuration for the policy server
• Authentication - Auth plugin protocol details
• OIDC Setup - Provider-specific OIDC configuration
• Development Tools - Testing and debugging utilities

Deployment

See examples/ for deployment patterns:

• systemd: Traditional Linux service deployment
• Client configs: SSH and epithet configuration examples
• Target host: sshd configuration for trusting epithet certificates

For AWS Lambda deployment (CA + policy server), see epithet-aws.

Development

make build    # Build all binaries
make test     # Run tests
make clean    # Clean build artifacts

Requirements: Go 1.25+

License

Apache 2.0