Auth configuration reference

echo.labstack.com/pro v0.2.0. See the task guide for setup examples.

Required fields

• Config.Fallback: Deny, Anonymous or Require; the zero value is invalid.
• APIKey: Namespace, Prefix, Peppers and Store.
• Bearer: one trusted issuer, audiences and either JWKSURL or DiscoveryURL.

An empty APIKey.Header reads Authorization: ApiKey; bearer construction fetches JWKS once, and middleware construction starts no goroutines.

auth.Config

Import echo.labstack.com/pro/auth.

auth.Config · auth/middleware.go:56 · echo.labstack.com/[email protected]

Config authenticates before quota. Maps and slices are copied. Caller-owned stores, logger and clock must be concurrency safe. ToMiddleware starts no work.

Fields from package source

Field	Type	Description	Defaults / requirements	Source
Schemes	map[string]Scheme	Schemes requires 1–32 named schemes with distinct namespaces. Construction compiles a private map and retains constructed Bearers and APIKey stores.	Schemes requires 1–32 named schemes with distinct namespaces.	auth/middleware.go:60
Fallback	Requirement	Fallback is required; choose Deny, Anonymous or Require. Its zero value is invalid.	Fallback is required; choose Deny, Anonymous or Require. Its zero value is invalid.	auth/middleware.go:63
Report	*openapi.Report	Report is an optional OpenAPI report. If set, construction checks each operation's scheme names and scope alternatives. Construction copies its policies; do not change Report during the call.	Report is an optional OpenAPI report.	auth/middleware.go:67
Logger	*slog.Logger	Logger is retained and caller-owned; nil is silent.	Logger is retained and caller-owned; nil is silent.	auth/middleware.go:69
Now	func() time.Time	Now is retained and must be concurrency safe; nil uses each scheme's clock (time.Now unless a BearerConfig.Now was supplied).	Now is retained and must be concurrency safe; nil uses each scheme's clock (time.Now unless a BearerConfig.Now was supplied).	auth/middleware.go:72

Functions from package source

Type	Source
func (c Config) ToMiddleware() (echo.MiddlewareFunc, error)	auth/middleware.go:117

auth.APIKey

Import echo.labstack.com/pro/auth.

auth.APIKey · auth/apikey.go:205 · echo.labstack.com/[email protected]

APIKey configures a key-store scheme. Header sets an optional alternative to Authorization: ApiKey. Supplying credentials in both headers is rejected. LookupTimeout defaults to 2s (1ms–30s). The store stays caller-owned and must honor cancellation. No goroutines start. Construction copies the pepper ring and key bytes. Cancellation and lookup failures return a sanitized *FailureError without exposing store or context errors.

Fields from package source

Field	Type	Description	Defaults / requirements	Source
Namespace	string	Namespace and Prefix are required and validated during middleware construction.	Namespace and Prefix are required and validated during middleware construction.	auth/apikey.go:207
Prefix	string	Namespace and Prefix are required and validated during middleware construction.	Namespace and Prefix are required and validated during middleware construction.	auth/apikey.go:207
Header	string	Header selects an optional alternative to Authorization: ApiKey. If empty, only Authorization: ApiKey is accepted. With Header set, clients may use either header. Supplying both is rejected.	Header selects an optional alternative to Authorization: ApiKey. If empty, only Authorization: ApiKey is accepted.	auth/apikey.go:211
Peppers	PepperRing	Peppers is required; construction copies its versions and key bytes.	Peppers is required; construction copies its versions and key bytes.	auth/apikey.go:213
Store	KeyStore	Store is required, caller-owned and must return current revocation state.	Store is required, caller-owned and must return current revocation state.	auth/apikey.go:215
LookupTimeout	time.Duration	LookupTimeout defaults to 2s; valid range 1ms–30s.	LookupTimeout defaults to 2s; valid range 1ms–30s.	auth/apikey.go:217

auth.BearerConfig

Import echo.labstack.com/pro/auth.

auth.BearerConfig · auth/bearer.go:39 · echo.labstack.com/[email protected]

BearerConfig describes one trusted issuer. HTTPS is mandatory, including discovery jwks_uri.

Fields from package source

Field	Type	Description	Defaults / requirements	Source
Namespace	string	Namespace is required. It prefixes this issuer's principal IDs and matches [a-z][a-z0-9-]{0,31}.	Namespace is required.	auth/bearer.go:42
Issuer	string	Issuer is the exact trusted issuer string. It is required and at most 2048 bytes.	It is required and at most 2048 bytes.	auth/bearer.go:44
Audiences	[]string	Audiences is copied; require 1–32 accepted values, each 1–512 bytes.	Audiences is copied; require 1–32 accepted values, each 1–512 bytes.	auth/bearer.go:46
JWKSURL	string	JWKSURL and DiscoveryURL are HTTPS sources; set exactly one.	JWKSURL and DiscoveryURL are HTTPS sources; set exactly one.	auth/bearer.go:48
DiscoveryURL	string	JWKSURL and DiscoveryURL are HTTPS sources; set exactly one.	JWKSURL and DiscoveryURL are HTTPS sources; set exactly one.	auth/bearer.go:48
AllowedJWKSHosts	[]string	AllowedJWKSHosts is copied, with at most 32 exact jwks_uri hosts, including a port only when the URL has one. Empty permits only the discovery host for the discovered JWKS URL.	Empty permits only the discovery host for the discovered JWKS URL.	auth/bearer.go:52
Algorithms	[]jose.SignatureAlgorithm	Algorithms is copied; empty selects RS256, PS256, ES256 and EdDSA. At most ten RSA, RSA-PSS, ECDSA or EdDSA algorithms are accepted.	Algorithms is copied; empty selects RS256, PS256, ES256 and EdDSA.	auth/bearer.go:55
Profile	TokenProfile	Profile defaults to ProfileAccessToken; ProfileJWT is the other valid value.	Profile defaults to ProfileAccessToken; ProfileJWT is the other valid value.	auth/bearer.go:58
ClockSkew	time.Duration	ClockSkew defaults to 30s; nonzero values must be positive and at most 2m.	ClockSkew defaults to 30s; nonzero values must be positive and at most 2m.	auth/bearer.go:61
SubjectClaim	string	SubjectClaim defaults to sub. ScopeClaim defaults to scope, then scp if absent. If KindClaim is empty, every principal has kind User. TenantClaim is used only with TrustTenantClaim.	SubjectClaim defaults to sub. ScopeClaim defaults to scope, then scp if absent. If KindClaim is empty, every principal has kind User.	auth/bearer.go:65
ScopeClaim	string	SubjectClaim defaults to sub. ScopeClaim defaults to scope, then scp if absent. If KindClaim is empty, every principal has kind User. TenantClaim is used only with TrustTenantClaim.	SubjectClaim defaults to sub. ScopeClaim defaults to scope, then scp if absent. If KindClaim is empty, every principal has kind User.	auth/bearer.go:65
KindClaim	string	SubjectClaim defaults to sub. ScopeClaim defaults to scope, then scp if absent. If KindClaim is empty, every principal has kind User. TenantClaim is used only with TrustTenantClaim.	SubjectClaim defaults to sub. ScopeClaim defaults to scope, then scp if absent. If KindClaim is empty, every principal has kind User.	auth/bearer.go:65
TenantClaim	string	SubjectClaim defaults to sub. ScopeClaim defaults to scope, then scp if absent. If KindClaim is empty, every principal has kind User. TenantClaim is used only with TrustTenantClaim.	SubjectClaim defaults to sub. ScopeClaim defaults to scope, then scp if absent. If KindClaim is empty, every principal has kind User.	auth/bearer.go:65
TrustTenantClaim	bool	TrustTenantClaim explicitly permits TenantClaim to restrict the principal; default false.	TrustTenantClaim explicitly permits TenantClaim to restrict the principal; default false.	auth/bearer.go:68
ClaimAllowlist	[]string	ClaimAllowlist is copied; empty retains no extra claims. At most 32 names of 1–128 bytes are accepted; retained values must satisfy PrincipalConfig.	ClaimAllowlist is copied; empty retains no extra claims.	auth/bearer.go:72
Client	*http.Client	Client is optional; nil uses a zero http.Client. A private shallow copy shares its transport, disables cookies and restricts redirects.	Client is optional; nil uses a zero http.Client.	auth/bearer.go:75
Timeout	time.Duration	Timeout bounds each fetch independently: zero selects 5s; valid range 1ms–30s.	Timeout bounds each fetch independently: zero selects 5s; valid range 1ms–30s.	auth/bearer.go:78
Now	func() time.Time	Now is retained and must be concurrency safe; nil uses time.Now.	Now is retained and must be concurrency safe; nil uses time.Now.	auth/bearer.go:80
Logger	*slog.Logger	Logger is caller-owned; nil is silent. Only sanitized categories for skipped JWKS entries are logged.	Logger is caller-owned; nil is silent.	auth/bearer.go:83

Functions from package source

Type	Source
func NewBearer(ctx context.Context, c BearerConfig) (*Bearer, error)	auth/bearer.go:119

auth.KeyOptions

Import echo.labstack.com/pro/auth.

auth.KeyOptions · auth/apikey.go:59 · echo.labstack.com/[email protected]

KeyOptions controls issuance; Kind defaults to Service. A zero expiration permits a nonexpiring credential. Callers own revocation and record persistence.

Fields from package source

Field	Type	Description	Defaults / requirements	Source
Kind	Kind	Kind defaults to Service; User is the other accepted value.	Kind defaults to Service; User is the other accepted value.	auth/apikey.go:61
Scopes	[]string	Scopes is optional; empty grants none. IssueKey copies the slice.	Scopes is optional; empty grants none.	auth/apikey.go:63
TenantRestriction	string	TenantRestriction is optional; empty leaves membership resolution to the application.	TenantRestriction is optional; empty leaves membership resolution to the application.	auth/apikey.go:65
ExpiresAt	time.Time	ExpiresAt at zero permits a nonexpiring credential.	ExpiresAt at zero permits a nonexpiring credential.	auth/apikey.go:67

auth.PrincipalConfig

Import echo.labstack.com/pro/auth.

auth.PrincipalConfig · auth/principal.go:44 · echo.labstack.com/[email protected]

PrincipalConfig contains already verified principal data. Never populate it from unverified headers or tool arguments. Claims must be explicitly allowlisted by the verifier. Inputs are copied.

Fields from package source

Field	Type	Description	Defaults / requirements	Source
Namespace	string	Namespace is required and matches [a-z][a-z0-9-]{0,31}. Subject is required, valid UTF-8 and at most 16 KiB. Scheme is required and at most 64 bytes.	Namespace is required and matches [a-z][a-z0-9-]{0,31}. Subject is required, valid UTF-8 and at most 16 KiB. Scheme is required and at most 64 bytes.	auth/principal.go:48
Subject	string	Namespace is required and matches [a-z][a-z0-9-]{0,31}. Subject is required, valid UTF-8 and at most 16 KiB. Scheme is required and at most 64 bytes.	Namespace is required and matches [a-z][a-z0-9-]{0,31}. Subject is required, valid UTF-8 and at most 16 KiB. Scheme is required and at most 64 bytes.	auth/principal.go:48
Scheme	string	Namespace is required and matches [a-z][a-z0-9-]{0,31}. Subject is required, valid UTF-8 and at most 16 KiB. Scheme is required and at most 64 bytes.	Namespace is required and matches [a-z][a-z0-9-]{0,31}. Subject is required, valid UTF-8 and at most 16 KiB. Scheme is required and at most 64 bytes.	auth/principal.go:48
Kind	Kind	Kind must be User or Service; the zero value is invalid.	Kind must be User or Service; the zero value is invalid.	auth/principal.go:50
Scopes	[]string	Scopes is copied; empty grants none. At most 64 visible ASCII (0x21–0x7E) scopes of 1–128 bytes are accepted.	Scopes is copied; empty grants none.	auth/principal.go:53
TenantRestriction	string	TenantRestriction is optional and matches [A-Za-z0-9._:-]{1,128} when set. KeyID is optional and at most 256 bytes.	TenantRestriction is optional and matches [A-Za-z0-9._:-]{1,128} when set. KeyID is optional and at most 256 bytes.	auth/principal.go:56
KeyID	string	TenantRestriction is optional and matches [A-Za-z0-9._:-]{1,128} when set. KeyID is optional and at most 256 bytes.	TenantRestriction is optional and matches [A-Za-z0-9._:-]{1,128} when set. KeyID is optional and at most 256 bytes.	auth/principal.go:56
ExpiresAt	time.Time	ExpiresAt is the verified expiry; zero represents a nonexpiring API key. NewPrincipal stores it without checking whether it is in the future.	ExpiresAt is the verified expiry; zero represents a nonexpiring API key.	auth/principal.go:60
Claims	map[string]string	Claims is copied; nil retains none. At most 32 UTF-8 entries fit, with names of 1–128 bytes and values of at most 1024 bytes.	Claims is copied; nil retains none.	auth/principal.go:63

Functions from package source

Type	Source
func NewPrincipal(c PrincipalConfig) (Principal, error)	auth/principal.go:69

authbind.QuotaConfig

Import echo.labstack.com/pro/auth/authbind.

authbind.QuotaConfig · auth/authbind/bind.go:52 · echo.labstack.com/[email protected]

QuotaConfig controls trusted IP extraction and anonymous metering. Without a trusted IP extractor, quota records no IP for authenticated requests. AnonymousByIP needs a valid trusted IP.

Fields from package source

Field	Type	Description	Defaults / requirements	Source
IP	func(*echo.Context) string	IP is a retained, concurrency-safe trusted extractor. Nil uses c.RealIP only when Echo.IPExtractor is configured.	Nil uses c.RealIP only when Echo.IPExtractor is configured.	auth/authbind/bind.go:55
AnonymousByIP	bool	AnonymousByIP permits anonymous metering by a valid trusted IP; default false.	AnonymousByIP permits anonymous metering by a valid trusted IP; default false.	auth/authbind/bind.go:58

Token and key limits

Setting	Default or limit
APIKey.Prefix / StoredKey.ID	Prefix, 22-character base62 ID, 43-character base62 secret
APIKey.Peppers	At most eight versions; 32–1024 random bytes per key
APIKey.Namespace / BearerConfig.Namespace	[a-z][a-z0-9-]{0,31}
Principal.ID()	At most 233 bytes
BearerConfig.Algorithms	RS256, PS256, ES256, EdDSA
BearerConfig.ClockSkew	30 seconds by default; at most two minutes
Bearer token bytes	At most 8 KiB
JWT claims bytes	At most 16 KiB
Principal.Scopes()	At most 64; at most 128 bytes each
JWKS and discovery resp.Body	At most 64 KiB read from resp.Body
JWKS keys	At most 32 raw entries
RSA modulus size	2048–8192 bits
JWKS kid	Every entry with that ID is dropped
BearerConfig.Timeout	Five seconds by default
Unknown JWT kid	30 seconds
JWKS refresh failures	At most 32 minutes
Cached JWKS keys	Usable for at most 24 hours after loading

By default, bearer accepts a discovered jwks_uri only on the discovery URL’s host. A nonempty AllowedJWKSHosts replaces that rule. Each discovered host must match an exact list entry, including any port. The limit counts bytes after your transport decompresses the body. Bearer does not decompress.

Persistent key lookup

auth.KeyStore requires Lookup(context.Context, string) (auth.StoredKey, error). Lookups must support concurrent calls and return current revocation data. See the compiled SQL sketch.

Stores, clients, clocks and loggers must support concurrent calls.

Error types

Authentication and scope refusals use *auth.FailureError.

Related pages

Package explanation · Task guide · Problem catalog