Auth

Source: server/auth/.

Purpose

auth is etcd's RBAC system: users, roles, permissions, and the tokens that prove identity on each gRPC call. It can be enabled per-cluster (etcdctl auth enable) and supports two token formats: simple (etcd-internal, opaque) and jwt (signed RS256/PSS/ES* tokens, suitable for inter-service trust).

Directory layout

server/auth/
├── store.go            # AuthStore interface + persistence
├── range_perm_cache.go # Cached interval tree for permission checks
├── simple_token.go     # Opaque token provider
├── jwt.go              # JWT token provider
├── nop.go              # No-op provider when auth is disabled
├── options.go          # Token-config parsing
├── metrics.go
└── doc.go

Key abstractions

Symbol	File	Description
AuthStore	server/auth/store.go	The big interface: enable/disable, user/role CRUD, IsPutPermitted, IsRangePermitted, ...
authStore struct	same	The implementation; keeps an in-memory copy of users/roles plus the unifiedRangePermissions cache
unifiedRangePermissions	server/auth/range_perm_cache.go	Per-user interval tree of granted ranges
TokenProvider	server/auth/options.go	Pluggable token format
simpleTokenTTL	server/auth/simple_token.go	Token expiration (default 5 min)
tokenJWT	server/auth/jwt.go	RS/EC-signed JWT provider
Errors ErrAuthFailed, ErrPermissionDenied, ErrAuthNotEnabled, ...	server/auth/store.go	Sentinel errors translated to gRPC codes

Permission model

• A user has zero or more roles.
• A role has zero or more permissions; each is {Type, Key, RangeEnd}.
• Permission types: READ, WRITE, READWRITE.
• The special root role grants the full keyspace ([\x00, \x00)); the root user is required before auth can be enabled.
• Per-user range checks happen against unifiedRangePermissions — an interval tree built once, invalidated on any role change.

How it works

graph TD
    client[Client] -->|Authenticate user/pass| grpc[v3rpc/auth.go]
    grpc --> store[authStore.Authenticate]
    store --> tp[TokenProvider.assign]
    tp --> token[token]
    token -->|metadata "token: ..."| client

    client -->|RPC + token metadata| inter[v3rpc.AuthInterceptor]
    inter --> tp2[TokenProvider.info]
    tp2 -->|user+revision| store2[authStore.IsXxxPermitted]
    store2 --> cache[unifiedRangePermissions]
    cache -->|allowed| handler[handler proceeds]
    cache -->|denied| err[ErrPermissionDenied]

Token providers

• simple — opaque random tokens stored server-side with TTL renewal on use. Easy, but tokens don't survive leader change unless re-issued.
• jwt — signed JWTs that can be verified offline. Configured by --auth-token=jwt,pub-key=...,priv-key=...,sign-method=...,ttl=....
• nop — used internally when auth is disabled.

Provider selection happens in server/auth/options.go's NewTokenProvider.

Integration points

• bbolt buckets (auth, authUsers, authRoles) declared in server/storage/schema/.
• gRPC interceptor: every unary and stream handler is wrapped by AuthInterceptor in server/etcdserver/api/v3rpc/interceptor.go, which calls back into authStore for permission checks.
• Apply pipeline: every auth mutation is a Raft entry; server/etcdserver/apply/auth.go reflects committed changes into the in-memory store.
• Cluster version: token-format upgrades require both peers to understand the format; the version-negotiation in etcdserver/version gates this.

Recent activity

The latest commits at wiki time (70a2b4871, 4bc674b79, d97dfbc3b, c5893b5e6) are RBAC bypass fixes around Put-with-PrevKv and Put-with-lease nested in transactions. They illustrate how subtle the interactions between txn evaluation, lease attach, and permission checks can be — see security/ for the threat-model context.

Entry points for modification

• New permission check → range_perm_cache.go + the touching call site (e.g. server/etcdserver/txn/, server/etcdserver/apply/auth.go).
• New token provider → implement TokenProvider, register in options.go.
• New auth gRPC method → api/etcdserverpb/rpc.proto (regen), server/etcdserver/api/v3rpc/auth.go, server/etcdserver/apply/auth.go.