Authentication

How it works

At startup, three independent AuthRegistry instances can be created: one per project (consumer traffic at projects[*].auth), one for the admin API (admin.auth), and one for the healthcheck endpoint (healthCheck.auth). If a project has no auth config, its registry is nil and all requests are allowed. If admin.auth is nil, the admin endpoint hard-errors — configure admin.auth to protect it.

For each HTTP request, eRPC extracts credential signals from query params and headers in a fixed priority order, then calls AuthRegistry.Authenticate. The registry iterates strategies in declaration order, skipping any whose type does not match the credential type and any filtered out by method rules. The first strategy that both matches and succeeds wins; its returned User{Id, RateLimitBudget} is attached to the request for downstream rate-limiting and observability.

HTTP credential extraction order (first match wins):

1. ?token= — deprecated alias for ?secret= → AuthTypeSecret
2. ?secret= → AuthTypeSecret
3. X-ERPC-Secret-Token header → AuthTypeSecret
4. Authorization: Basic (password part of base64 user:pass) → AuthTypeSecret
5. Authorization: Bearer <token> → AuthTypeJwt
6. ?jwt= → AuthTypeJwt
7. ?signature= + ?message= → AuthTypeSiwe
8. X-Siwe-Message + X-Siwe-Signature headers → AuthTypeSiwe
9. No credential present → AuthTypeNetwork (fallback)

gRPC metadata uses a parallel order without query-param equivalents: x-erpc-secret-token, then authorization: Basic, authorization: Bearer, then x-siwe-message+x-siwe-signature, then network fallback. gRPC has no ?token= / ?secret= / ?jwt= equivalents — query params are not available in gRPC metadata.

Method filtering. Every strategy accepts ignoreMethods and allowMethods wildcard lists. ignoreMethods is evaluated first; allowMethods overrides it. The canonical pattern for restricting a strategy to one method is ignoreMethods: ["*"] plus allowMethods: ["eth_getLogs"].

Rate-limit budget cascade. A common.User{Id, RateLimitBudget} is returned from each strategy. Budget priority: (1) per-user budget from the strategy result (database record field, JWT claim, or strategy-level rateLimitBudget); (2) strategy-level AuthStrategyConfig.rateLimitBudget; (3) no budget → all requests pass. In acquireRateLimitPermit, the user's budget (if non-empty) overrides the strategy-level budget.

secret strategy

The simplest backend-to-backend gate. The client sends the token as ?secret=VALUE or the X-ERPC-Secret-Token header. Authorization: Basic is also accepted; only the password field is used — the username is silently discarded.

Authenticate: exact equality match (ap.Secret.Value != s.cfg.Value). Returns ErrAuthUnauthorized on mismatch. No timing-safe compare — plain Go string inequality. For public internet deployments, prefer database or jwt.

jwt strategy

Verifies a signed JWT bearer token. Supports RSA, EC, and HMAC keys with optional kid-based rotation. Rate-limit budget tiers can be embedded in any JWT claim, enabling per-user rate limiting without separate strategy entries.

Authenticate flow: ParseUnverified (kid extraction) → algorithm allowlist → key lookup by kid or type-compatibility → full Parse (signature + temporal claims) → issuer/audience/required claims → extract sub as User.Id → extract budget claim.

Critical footgun: when verificationKeys is nil or empty, s.keys is empty, key lookup finds nothing, and every JWT is rejected with "no suitable verification key found". An empty key map is deny-all, not allow-all.

siwe strategy

Verifies an EIP-4361 Sign-In-With-Ethereum message and signature. The recovered Ethereum address (lowercase) becomes User.Id. Requires an explicit allowedDomains list — an empty or absent list rejects all SIWE requests.

Authenticate flow: parse EIP-4361 message → EIP-191 signature verification → domain allowlist → ValidNow() temporal check → return User{Id: strings.ToLower(address)}.

Both raw and base64-encoded message forms are accepted. SIWE requires both ?signature= AND ?message= together — supplying only one causes silent fallthrough to network-strategy extraction.

network strategy

Authorizes requests by client IP address against an allowlist of exact IPs and CIDR ranges. This is the credential-less fallback — any request arriving without a recognizable token, JWT, or SIWE payload receives AuthTypeNetwork and is routed here if configured.

Authenticate: reads req.ClientIP() (proxy-resolved by HTTP ingress). Checks localhost → exact IP list → CIDR list. First match wins. ipAsUser=false (default): all IPs in a CIDR range share one identity (cidr.String()). ipAsUser=true: each IP gets its own identity (clientIP.String()).

database strategy

Looks up an API key against a connector-backed store (PostgreSQL, DynamoDB, Redis, memory, or gRPC). Includes an in-process Ristretto positive cache (default 1h TTL), a hardcoded 5-second negative cache for invalid/disabled keys, singleflight deduplication for concurrent misses, configurable retry/backoff, and a connector-down circuit-breaker with optional fail-open.

Authenticate fast paths (in evaluation order):

1. Positive Ristretto cache hit → return cached User immediately.
2. Negative Ristretto cache hit → return ErrAuthUnauthorized immediately.
3. Connector-down fast path (tryFastFailOpen) → return emergency user if fail-open enabled.
4. Singleflight deduplicated DB lookup → parse JSON → cache or negative-cache.

DB record format:

{
  "userId":          "string (required)",
  "enabled":         true,
  "rateLimitBudget": "budget-id (optional)"
}

enabled: false → ErrAuthUnauthorized + 5-second negative-cache entry. Missing userId → auth error. Missing enabled → treated as true.

Connector-down circuit-breaker (added after 2026-05-13 production incident). The strategy tracks connectorDown bool and connectorDownSince int64. On transport/timeout/not-ready errors, markConnectorDown() sets the latch. While down, tryFastFailOpen() bypasses singleflight and the DB entirely — returning the emergency user (if failOpen.enabled=true) or rejecting immediately. One probe per second is elected via CAS to run the real DB path. A successful probe calls markConnectorUp().

Config schema

Auth attachment points

AuthConfig

AuthStrategyConfig — common fields

secret strategy — SecretStrategyConfig

YAML prefix: auth.strategies[*].secret

Supports: AuthTypeSecret only. SetDefaults: no-op.

jwt strategy — JwtStrategyConfig

YAML prefix: auth.strategies[*].jwt

Supports: AuthTypeJwt only. SetDefaults: sets rateLimitBudgetClaimName = "rlm" if empty.

siwe strategy — SiweStrategyConfig

YAML prefix: auth.strategies[*].siwe

Supports: AuthTypeSiwe only. SetDefaults: no-op.

network strategy — NetworkStrategyConfig

YAML prefix: auth.strategies[*].network

Supports: AuthTypeNetwork only (credential-less fallback). SetDefaults: no-op.

database strategy — DatabaseStrategyConfig

YAML prefix: auth.strategies[*].database

Negative cache: hardcoded 5-second TTL, 1 MiB MaxCost. Not configurable. Disabled/invalid keys stay rejected up to 5 seconds after change.

database strategy Supports: accepts both AuthTypeSecret (token delivered via header/query) and AuthTypeDatabase. The AuthTypeDatabase enum value is never set by any current HTTP or gRPC payload extractor — it is reserved for future or programmatic use. auth/strategy_database.go:L118-120

database connector error classification — determines whether connectorDown latch is set (auth/strategy_database.go:L487-L517 (opens in a new tab)):

getWithRetries abort conditions (auth/strategy_database.go:L367-L417 (opens in a new tab)):

• ErrRecordNotFound → abort immediately (DB is healthy; no retry needed).
• data.ErrConnectorNotReady → abort immediately (connector's own reconnect loop handles recovery).
• Context done → abort immediately.
• Any other error → retry with baseBackoff << (attempt-1) up to maxAttempts.

Connector failsafe wrapping. Auth-scope connectors support the same failsafeForGets and failsafeForSets wrapping as cache-scope connectors (ConnectorConfig.failsafeForGets[*] and failsafeForSets[*]). Each entry is a FailsafeConfig with fields matchMethod (default "*"), matchFinality, retry, circuitBreaker, timeout, hedge, and consensus. common/config.go:L349-350

PostgreSQL auth-scope defaults (connector.postgresql.*):

Memory connector (connector.memory.*):

DynamoDB auth-scope defaults (connector.dynamodb.*):

AwsAuthConfig (used by connector.dynamodb.auth):

Redis auth-scope defaults (connector.redis.*):

gRPC connector (connector.grpc.*):

Worked examples

All patterns below are distilled from real production fleets; comments explain the non-obvious choices.

1. Production database auth with fail-open and extended cache TTL. The customer-facing edge fleet uses PostgreSQL-backed dynamic API keys. The cache TTL was raised from 5s to 1m after a 2026-05-13 incident where transient pgbouncer disruption caused a reconnect storm across all 32 replicas simultaneously — lower query rate means transient errors are far less likely to cascade. Trade-off: revoked/disabled keys take up to 1m to stop working:

- type: database  database:    connector:      id: auth-postgresql      driver: postgresql      postgresql:        connectionUri: ${DATABASE_URL}        # table defaults to "erpc_auth" at auth scope (differs from cache scope)    cache:      # Raised from 5s to 1m to cut the Postgres query rate ~12× and prevent      # connector reconnect storms under transient pgbouncer disruptions.      # Trade-off: revoked keys stay valid for up to 1 minute.      ttl: 1m    failOpen:      # Keep traffic flowing under an emergency budget if the auth DB goes down;      # the connector-down circuit-breaker limits real DB probes to ~1/second.      enabled: true      userId: emergency-failopen      # Cap emergency traffic so a DB outage can't become a free-for-all      rateLimitBudget: emergency-tier

2. Admin endpoint secret. All production deployments share a single secret strategy on the admin scope; the token is injected from an environment variable at deploy time. Note: admin.auth being nil hard-errors the endpoint with no useful error code — always configure it even in internal-only deployments:

# admin.auth — nil = admin always returns 500, not 401admin:  auth:    strategies:      - type: secret        secret:          # admin endpoints only need identity; no rate-limit budget required          value: ${ADMIN_SECRET_TOKEN}

3. Multi-secret staging setup with per-identity budgets. The staging environment uses multiple named secrets bound to the same rate-limit budget — useful for smoke-testing different client identities without a database. Each id surfaces separately in Prometheus labels so you can see per-client RPS in dashboards:

- type: secret  secret:    id: client-a    value: ${CLIENT_A_TOKEN}    # each secret gets its own budget so one client can't starve others    rateLimitBudget: edge-tier-60krpm-total-unlimited-per-ip- type: secret  secret:    id: client-b    value: ${CLIENT_B_TOKEN}    rateLimitBudget: edge-tier-60krpm-total-unlimited-per-ip

4. Network strategy as credential-less fallback for internal services. The staging deployment allows all internal traffic via CIDR while still accepting named secrets for external test callers. The network strategy must come first — it matches any request with no credential, so placing it later would shadow secrets on credential-less paths:

# Place network strategy FIRST — it is the credential-less fallback;# any request without a token, JWT, or SIWE payload lands here.- type: network  network:    allowedCIDRs: ["10.0.0.0/8", "172.16.0.0/12"]    allowLocalhost: true    # ipAsUser: true gives each IP its own User.Id in Prometheus labels    ipAsUser: true    rateLimitBudget: internal-tier# External callers still use named secrets- type: secret  secret:    id: external-service    value: ${EXTERNAL_SECRET_TOKEN}    rateLimitBudget: external-tier

5. JWT with per-user rate-limit tiers and key rotation. Embed the budget ID in the token's rlm claim so a single strategy entry handles thousands of users. Rotate signing keys by adding a new kid entry — old tokens continue to verify against the old key until they naturally expire. Always set allowedAlgorithms to prevent algorithm-confusion attacks:

- type: jwt  jwt:    verificationKeys:      # Add a new kid here when rotating; keep the old entry until tokens expire      rsa-2024: "file:///etc/erpc/public-2024.pem"      rsa-2025: "file:///etc/erpc/public-2025.pem"    # ALWAYS restrict algorithms — omitting this allows algorithm-confusion attacks    allowedAlgorithms: ["RS256"]    allowedIssuers: ["https://auth.myapp.com"]    allowedAudiences: ["https://rpc.myapp.com"]    # Extract User.RateLimitBudget from this JWT claim; missing claim = no budget    rateLimitBudgetClaimName: rlm

Request/response behavior

• A successful auth attaches User{Id, RateLimitBudget} to the request; User.Id flows into log context and Prometheus labels on every downstream metric. [auth/registry.go:L74-76]
• ErrAuthUnauthorized → HTTP 401. Carries {strategy} in Details. [common/errors.go:L524-542]
• ErrAuthRateLimitRuleExceeded → HTTP 429. Carries {projectId, strategy, budget, rule, userId, clientIp} in Details. The rule value is formatted as "method:<rpc_method>". [common/errors.go:L545-568]
• If no strategy's Supports returns true (e.g., a JWT token arrives but only network is configured), the response is "no auth strategy matched" — not a per-strategy auth failure. [auth/registry.go:L46-96]
• For admin scope, when adminCfg != nil but adminAuthRegistry == nil, AdminAuthenticate returns a plain fmt.Errorf with no typed error code → HTTP 200 (not 401/500). When adminCfg is nil, the path returns ErrAuthUnauthorized → HTTP 401. [erpc/admin.go:L26-30]
• erpc_rate_limits_total fires for auth-level budget exhaustion with origin="auth" and auth="<type>:<index>" (e.g. "secret:0", "database:1"). [auth/authorizer.go:L137]
• ErrAuthRateLimitRuleExceeded is auth-scope only — it fires when the auth-strategy-level rate-limit budget is exceeded. It does NOT fire for upstream/network rate-limit budgets (those produce ErrProjectRateLimitRuleExceeded or ErrNetworkRateLimitRuleExceeded). Retryability: U:no (upstreams will not retry), N:yes (network propagates 429 to caller). [common/errors.go:L545-568]
• gRPC required metadata: x-erpc-project (required; missing → codes.InvalidArgument "missing metadata"), x-erpc-chain-id (required), x-erpc-architecture (optional, defaults to "evm"). [erpc/grpc_server.go:L138-145]

Best practices

• Use database for user-facing APIs — dynamic key management without redeploys, per-user rate-limit budgets via the DB record's rateLimitBudget field, and the built-in cache means sub-millisecond auth on cache hits.
• Always set allowedAlgorithms on jwt — leaving it nil accepts any algorithm, opening the door to algorithm-confusion attacks (e.g., RS256 public key forged as HS256 secret).
• Always list at least one allowedDomains on siwe — an empty or absent list silently rejects every SIWE request with no config-level indication.
• Never set rateLimitBudget on a healthCheck.auth strategy — the healthcheck auth registry is created with a nil rate-limiter registry; reaching the budget-acquisition path causes a nil pointer panic.
• Enable failOpen with a capped emergency budget on database — a DB outage should not make your RPC endpoint unreachable; the circuit-breaker bounds probe load to ~1 query/second per replica.
• DynamoDB lockRetryInterval defaults to 0 — zero means busy-spin retries during lock contention; set to 100ms or higher in production to avoid rapid API calls and unexpected cost.
• Use secret only for private, server-side callers — the plain string comparison is not timing-safe; for browser-reachable endpoints, prefer jwt or database.

Edge cases & gotchas

1. No strategies = allow-all. AuthRegistry.Authenticate returns nil, nil when the strategy list is empty. All requests pass. Auth is opt-in.
2. network strategy is the credential-less fallback. Requests without any recognizable credential get AuthTypeNetwork. If no network strategy is configured and only a secret strategy exists, credential-less requests get "no auth strategy matched", not "invalid secret".
3. secret and database both consume AuthTypeSecret. If both are configured, declaration order determines which runs first. To use only database, omit the secret strategy.
4. JWT allowedAudiences only supports scalar aud. The implementation casts claims["aud"] to string. Tokens with "aud": ["a","b"] (array form) always fail the cast and are rejected even if a matching audience is in the array.
5. SIWE allowedDomains nil/empty = deny-all. Visual appearance of siwe: {} gives no indication it is a blanket deny.
6. network.trustedProxies is an intentional no-op. Configure server.trustedIPForwarders / server.trustedIPHeaders instead.
7. Healthcheck auth cannot use rateLimitBudget. The healthcheck auth registry is created with rateLimitersRegistry = nil. Setting a budget on a healthcheck strategy reaches a nil pointer dereference at acquireRateLimitPermit.
8. secret uses non-constant-time comparison. Plain != is timing-side-channel vulnerable for public internet exposures.
9. Database negative cache TTL is hardcoded at 5 seconds. Not configurable. Re-enabled keys are rejected for up to 5 seconds.
10. Connector-down probe is per-process. One probe/second per replica, no cross-replica coordination.
11. type inference conflict. Setting multiple sub-config blocks (e.g. both secret: and jwt:) in one strategy entry causes the last-evaluated block to silently overwrite type. Evaluation order: secret → database → jwt → siwe. Never set multiple sub-config blocks in one strategy entry.
12. Authorization: Basic username is silently discarded. Only the password field is used as the secret value. alice:mysecret and bob:mysecret are treated identically.
13. JWT requires keys. Configure verificationKeys and/or verificationJwksUrl. With neither, startup validation fails. An empty resolved key map rejects every JWT (deny-all, not allow-all).
14. SIWE requires both signature and message together. Missing either one causes silent fallthrough to network-strategy payload extraction.
15. ?token= query param is deprecated. Alias for ?secret=. Continues to work but may be removed; use ?secret= or X-ERPC-Secret-Token header in new implementations.
16. Redis addr/username/password/db are cleared after SetDefaults. After initialization only uri is set. Config exports show only the URI (with credentials URL-encoded in it).
17. DynamoDB lockRetryInterval defaults to 0. Zero = busy-spin during lock contention. Set to a non-zero value (e.g. 100ms) in production.
18. database.cache, database.retry, and database.failOpen are always auto-created. Caching is always on with 1h TTL unless ttl is explicitly changed. There is no config to disable caching by omitting the block.
19. type: "network" auto-creates the network {} sub-struct; the converse is asymmetric. Adding a network: block does NOT overwrite type — unlike secret/database/jwt/siwe which force-overwrite type when their sub-block is present.
20. When admin.auth is nil the admin endpoint hard-errors with HTTP 500. AdminAuthenticate returns a plain fmt.Errorf (no typed error code) → HTTP 200 wire, not 401. Configure admin.auth to protect it properly.
21. database strategy also accepts AuthTypeDatabase in Supports. The enum value AuthTypeDatabase exists but is never produced by any current HTTP or gRPC payload extractor. It is reserved for future or programmatic injection. In practice, database auth is triggered via AuthTypeSecret credentials (header/query token). [auth/strategy_database.go:L118-120]
22. Singleflight scope is per API key. The singleflight group inside DatabaseStrategy uses the raw API key string as the deduplication key. Concurrent requests with the same API key during a cache miss are coalesced into a single DB lookup. Requests with different API keys run in parallel. [auth/strategy_database.go:L173-178]
23. AuthConfig is shared across all three scopes. The same AuthConfig type is used for projects[*].auth, admin.auth, and healthCheck.auth. All five strategy types can be configured in any scope. The only scope-specific hazard is healthCheck.auth — the healthcheck auth registry is created with a nil rateLimitersRegistry, so setting rateLimitBudget on any healthcheck strategy causes a nil pointer panic.
24. Redis addr/username/password/db are cleared after SetDefaults. After initialization, only uri is set; all discrete fields are zeroed. Config exports show only the URI (with credentials URL-encoded in it). Because password has json:"-", a JSON export shows the URI but not the password field. [common/defaults.go:L1012-1015]
25. Admin auth registry DOES support rate-limit budgets. Unlike the healthcheck scope, the admin AuthRegistry is created with the same rateLimitersRegistry as projects. Rate-limit budgets on admin auth strategies are applied when configured.
26. verificationJwksUrl must be absolute HTTP(S). Non-empty values are parsed at startup; scheme must be http or https and a host is required. Scheme-less hosts, file://, and other schemes fail validation even when static verificationKeys are also set. [common/validation.go]

Observability

Log messages (database strategy):

No dedicated auth trace spans — auth runs inline inside the HTTP handler goroutine within the OTel request span.

Source code entry points

• auth/registry.go:L46-L96 (opens in a new tab) — AuthRegistry.Authenticate: first-win loop, error accumulation
• auth/authorizer.go:L83-L157 (opens in a new tab) — shouldApplyToMethod, acquireRateLimitPermit, budget cascade
• auth/http.go:L13-L88 (opens in a new tab) — NewPayloadFromHttp: credential extraction priority order
• auth/strategy_database.go:L271-L357 (opens in a new tab) — connector-down circuit-breaker, probe election, fail-open
• auth/strategy_jwt.go:L100-L116 (opens in a new tab) — JWT key selection (kid lookup + type-compatibility scan)
• auth/strategy_siwe.go:L22-L67 (opens in a new tab) — SIWE signature verification + domain allowlist
• auth/strategy_network.go:L47-L93 (opens in a new tab) — NetworkStrategy: localhost/IP/CIDR checks, ipAsUser mode
• common/config.go:L2433-L2534 (opens in a new tab) — all auth config type declarations
• common/defaults.go:L2611-L2761 (opens in a new tab) — SetDefaults for all auth types
• auth/strategy_database_test.go (opens in a new tab) — circuit-breaker, probe election, fail-open, classifyDbError label tests

Related pages

• Rate limiters — define the budgets that auth strategies assign to each identity.
• Projects — auth lives at projects[*].auth; project-level config context.
• Use cases: Multi-tenant RPC — end-to-end example combining auth + rate limiters.