epithet/examples/policy-server/policy.example.yaml at main · epithet-ssh/epithet · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
# Epithet Policy Server - Inline Configuration Example
#
# Use this format for INLINE configuration in ~/.epithet/*.yaml files.
# The "policy:" wrapper is required because Kong resolves config by subcommand name.
#
# For DYNAMIC policy sources (--policy-source flag), use a flat format
# WITHOUT the "policy:" wrapper. See policy-source.example.yaml.
#
# This configuration uses group names as principals, designed to work with
# SSH's AuthorizedPrincipalsFile feature for fine-grained access control.

policy:
  # CA public key for signature verification
  # Get this from your CA server: curl http://localhost:8080/
  # Or from the file: cat ca_key.pub
  ca-pubkey: "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIAbCdE..."

  # OIDC configuration for token validation
  # Examples:
  #   Google: issuer: https://accounts.google.com
  #   Okta: issuer: https://your-domain.okta.com
  #   Azure AD: issuer: https://login.microsoftonline.com/{tenant-id}/v2.0
  oidc:
    issuer: "https://accounts.google.com"
    audience: "your-client-id"  # Your OAuth2 client ID

  # Map users (by email or OIDC sub claim) to tags
  # Tags represent roles or team membership
  users:
    alice@example.com: [admin, eng] # Senior engineer with admin access
    bob@example.com: [eng] # Engineer
    charlie@example.com: [ops] # Operations team
    diana@example.com: [admin, ops] # Ops lead with admin access

    # Add your team members here:
    # yourname@example.com: [admin]

  # Global defaults for all hosts (unless overridden per-host)
  defaults:
    # Map principals (group names) to allowed tags
    #
    # IMPORTANT: Principals are group names, not usernames!
    # Use AuthorizedPrincipalsFile on target hosts to map group principals
    # to local user accounts.
    #
    # The certificate will contain ALL principals the user is authorized for
    # (union of global defaults + all host-specific policies).
    allow:
      wheel: [admin] # Admins get 'wheel' group
      developers: [eng] # Engineers get 'developers' group
      operators: [ops] # Ops team gets 'operators' group
      dbadmins: [admin] # Admins also get 'dbadmins' group

    # Default certificate expiration (2-10 minutes recommended)
    expiration: "5m"

    # Default SSH certificate extensions
    extensions:
      permit-pty: ""
      permit-agent-forwarding: ""
      permit-user-rc: ""

  # Per-host policy overrides (optional)
  # Use this to grant additional principals for specific hosts
  hosts:
    # Production database - only admins get postgres group
    prod-db-01:
      allow:
        postgres: [admin]
      expiration: "2m" # Shorter expiration for production database

    # Development server - engineers get additional access
    dev-server:
      allow:
        docker: [eng] # Engineers can access docker group
      expiration: "10m" # Longer expiration for development

    # Staging environment
    staging-api:
      allow:
        deployers: [ops, eng] # Both ops and eng can deploy to staging
      expiration: "5m"
# Certificate Principal Assignment Examples:
#
# 1. alice@example.com (tags: [admin, eng])
#    Certificate principals: [dbadmins, deployers, developers, docker, operators, postgres, wheel]
#    - From global: wheel (admin tag), developers (eng tag), operators (admin tag via ops-lead role), dbadmins (admin tag)
#    - From prod-db-01: postgres (admin tag)
#    - From dev-server: docker (eng tag)
#    - From staging-api: deployers (admin OR eng tag)
#
# 2. bob@example.com (tags: [eng])
#    Certificate principals: [deployers, developers, docker]
#    - From global: developers (eng tag)
#    - From dev-server: docker (eng tag)
#    - From staging-api: deployers (eng tag)
#
# 3. charlie@example.com (tags: [ops])
#    Certificate principals: [deployers, operators]
#    - From global: operators (ops tag)
#    - From staging-api: deployers (ops tag)

# Target Host Setup with AuthorizedPrincipalsFile
#
# On each SSH server, configure /etc/ssh/sshd_config:
#
#   TrustedUserCAKeys /etc/ssh/ca/epithet.pub
#   AuthorizedPrincipalsFile /etc/ssh/auth_principals/%u
#
# Then create /etc/ssh/auth_principals/[username] files mapping principals to users:
#
# /etc/ssh/auth_principals/root:
#   wheel
#
# /etc/ssh/auth_principals/ubuntu:
#   developers
#   operators
#
# /etc/ssh/auth_principals/deploy:
#   operators
#
# /etc/ssh/auth_principals/postgres:
#   postgres
#   dbadmins
#
# Now when alice (who has principals [wheel, developers, postgres, ...]) runs:
#   ssh root@server     → Allowed (cert has 'wheel', authorized for root)
#   ssh ubuntu@server   → Allowed (cert has 'developers', authorized for ubuntu)
#   ssh postgres@prod-db → Allowed (cert has 'postgres', authorized for postgres)
#
# And when bob (who has principals [developers, docker]) runs:
#   ssh root@server     → Denied (cert lacks 'wheel')
#   ssh ubuntu@server   → Allowed (cert has 'developers', authorized for ubuntu)
#   ssh postgres@prod-db → Denied (cert lacks 'postgres' or 'dbadmins')

# Security Notes:
#
# 1. Certificates can be used on ANY host that trusts the CA, regardless of
#    host-specific policies in this config. Host restrictions are enforced
#    at certificate ISSUANCE time, not validation time.
#
# 2. Use AuthorizedPrincipalsFile on target hosts for additional control over
#    which principals can access which local user accounts.
#
# 3. Keep certificate expiration short (2-10 minutes). This minimizes the
#    blast radius if a certificate is compromised. Users remain authenticated
#    via OIDC refresh tokens, so re-authentication is fast (~100-200ms).
#
# 4. The certificate contains ALL principals the user is authorized for,
#    making it convenient (one cert works for all authorized access) while
#    still allowing fine-grained control via AuthorizedPrincipalsFile.