Tenant configuration reference

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

Required fields

• Config.Member: needed for request-selected tenants unless the credential fixes the tenant.
• AuthorizeConfig: Authorizer, Action and Resource, which resolves the resource owner.
• HTTPConfig: a caller-owned Client and an explicit http(s) origin in URL.

A zero Config does not let a request choose any tenant; the Cerbos and OpenFGA adapters start no goroutines and never close clients.

tenant.Config

Import echo.labstack.com/pro/tenant.

tenant.Config · tenant/tenant.go:179 · echo.labstack.com/[email protected]

Config evaluates every selector and refuses conflicts. A credential restriction supplies the tenant when selectors are absent. AnonymousSelector explicitly permits public tenant addressing; ordinary selectors cannot confer tenant authority on anonymous requests. Callbacks remain caller-owned and concurrency safe.

Fields from package source

Field	Type	Description	Defaults / requirements	Source
Selectors	[]Selector	Selectors is copied; nil selects only a credential restriction. At most 16 non-nil, concurrency-safe callbacks are accepted.	Selectors is copied; nil selects only a credential restriction. At most 16 non-nil, concurrency-safe callbacks are accepted.	tenant/tenant.go:182
Member	func(context.Context, auth.Principal, ID) (bool, error)	Member checks authenticated principals only. If nil, it refuses request-selected tenants unless the credential restricts the tenant. The callback is retained, must support concurrent calls and must honor ctx. An error refuses the request, even when Member also returns true.	If nil, it refuses request-selected tenants unless the credential restricts the tenant.	tenant/tenant.go:187
Required	bool	Required refuses an absent tenant except on public operations; default false.	Required refuses an absent tenant except on public operations; default false.	tenant/tenant.go:190
AnonymousSelector	Selector	AnonymousSelector is an optional retained selector for anonymous traffic; nil disables anonymous tenant selection.	AnonymousSelector is an optional retained selector for anonymous traffic; nil disables anonymous tenant selection.	tenant/tenant.go:193

Functions from package source

Type	Source
func (c Config) ToMiddleware() (echo.MiddlewareFunc, error)	tenant/tenant.go:197

tenant.AuthorizeConfig

Import echo.labstack.com/pro/tenant.

tenant.AuthorizeConfig · tenant/authorize.go:61 · echo.labstack.com/[email protected]

AuthorizeConfig configures fail-closed resource authorization. Resource receives the deadline through the Echo request context. The middleware restores the original context before calling the handler. Resolver request changes and parsed form state are preserved. Callbacks must honor cancellation and be concurrency safe; no detached work is started. Resolvers must establish resource ownership, not merely operation ID, and must not retain the Echo context.

Fields from package source

Field	Type	Description	Defaults / requirements	Source
Authorizer	Authorizer	Authorizer is required, caller-owned and must be concurrency safe and honor ctx.	Authorizer is required, caller-owned and must be concurrency safe and honor ctx.	tenant/authorize.go:64
Action	string	Action is required and contains 1–128 bytes.	Action is required and contains 1–128 bytes.	tenant/authorize.go:66
Resource	func(*echo.Context) (Resource, error)	Resource is a required, concurrency-safe resolver. It borrows the Echo context for the call and must honor its request deadline.	Resource is a required, concurrency-safe resolver.	tenant/authorize.go:69
Timeout	time.Duration	Timeout bounds resource resolution and authorization; defaults to 2s, valid range 1ms–30s.	Timeout bounds resource resolution and authorization; defaults to 2s, valid range 1ms–30s.	tenant/authorize.go:72

Functions from package source

Type	Source
func (c AuthorizeConfig) ToMiddleware() (echo.MiddlewareFunc, error)	tenant/authorize.go:76

tenant.HTTPConfig

Import echo.labstack.com/pro/tenant.

tenant.HTTPConfig · tenant/http.go:31 · echo.labstack.com/[email protected]

HTTPConfig bounds a caller-owned client's authorization work. Responses are limited to 64 KiB after decompression. Redirects must keep scheme and host, with at most five hops. No retries or goroutines run. Service credentials are never logged.

Fields from package source

Field	Type	Description	Defaults / requirements	Source
Client	*http.Client	Client is required and caller-owned. A shallow private copy shares its transport and disables its cookie jar; configure it before calling Cerbos or OpenFGA. Later field changes are not observed.	Client is required and caller-owned.	tenant/http.go:35
URL	string	URL is a required http(s) origin without credentials, query or fragment. Plain http supports private service meshes.	URL is a required http(s) origin without credentials, query or fragment.	tenant/http.go:38
Timeout	time.Duration	Timeout defaults to 2s; valid range 1ms–30s, bounded by caller cancellation.	Timeout defaults to 2s; valid range 1ms–30s, bounded by caller cancellation.	tenant/http.go:41
MaxConcurrent	int	MaxConcurrent defaults to 16; valid range 1–256. Excess calls deny immediately.	MaxConcurrent defaults to 16; valid range 1–256.	tenant/http.go:44
AuthHeader	string	AuthHeader and AuthValue must be both empty or both set. AuthHeader is 1–64 ASCII letters, digits or hyphens. AuthValue is at most 8192 bytes without CR or LF.	AuthHeader and AuthValue must be both empty or both set.	tenant/http.go:47
AuthValue	string	AuthHeader and AuthValue must be both empty or both set. AuthHeader is 1–64 ASCII letters, digits or hyphens. AuthValue is at most 8192 bytes without CR or LF.	AuthHeader and AuthValue must be both empty or both set.	tenant/http.go:47
AllowInsecure	bool	AllowInsecure permits credentials over HTTP for local tests; default false.	AllowInsecure permits credentials over HTTP for local tests; default false.	tenant/http.go:50

tenant.CerbosConfig

Import echo.labstack.com/pro/tenant.

tenant.CerbosConfig · tenant/http.go:146 · echo.labstack.com/[email protected]

CerbosConfig requires an explicit trusted mapping, so arbitrary claims are never forwarded. The adapter adds the resolved tenant as resource attr tenant.

Fields from package source

Field	Type	Description	Defaults / requirements	Source
HTTP	HTTPConfig	HTTP supplies the required client, origin and bounded request settings.	HTTP supplies the required client, origin and bounded request settings.	tenant/http.go:149
Principal	func(Check) (CerbosPrincipal, error)	Principal is a required retained mapping and must be concurrency safe. Returned roles and attributes are borrowed only during the authorization call.	Principal is a required retained mapping and must be concurrency safe.	tenant/http.go:153

tenant.OpenFGAConfig

Import echo.labstack.com/pro/tenant.

tenant.OpenFGAConfig · tenant/http.go:217 · echo.labstack.com/[email protected]

OpenFGAConfig pins the store and authorization model. User optionally maps a trusted principal to a complete OpenFGA user; nil uses user:<base32 principal ID>, avoiding ':'/'#' ambiguity in principal IDs.

Fields from package source

Field	Type	Description	Defaults / requirements	Source
HTTP	HTTPConfig	HTTP supplies the required client, origin and bounded request settings.	HTTP supplies the required client, origin and bounded request settings.	tenant/http.go:220
StoreID	string	StoreID and AuthorizationModelID are required, each 1–64 ASCII letters, digits, underscores or hyphens.	StoreID and AuthorizationModelID are required, each 1–64 ASCII letters, digits, underscores or hyphens.	tenant/http.go:223
AuthorizationModelID	string	StoreID and AuthorizationModelID are required, each 1–64 ASCII letters, digits, underscores or hyphens.	StoreID and AuthorizationModelID are required, each 1–64 ASCII letters, digits, underscores or hyphens.	tenant/http.go:223
ActionRelations	map[string]string	ActionRelations is copied; require 1–256 entries. Actions are 1–128 bytes; relations start with an ASCII letter or underscore followed by up to 49 ASCII letters, digits or underscores. Missing actions deny.	ActionRelations is copied; require 1–256 entries.	tenant/http.go:227
User	func(Check) (string, error)	User is a retained, concurrency-safe mapping; nil selects the default principal mapping described above. Its result must be a valid OpenFGA user.	User is a retained, concurrency-safe mapping; nil selects the default principal mapping described above.	tenant/http.go:231

Adapter limits

Setting	Default or limit
Config.Selectors	At most 16; copied during construction
tenant.ID	[A-Za-z0-9._:-]{1,128}
AuthorizeConfig.Timeout	Two seconds by default; at most 30 seconds
HTTPConfig.Timeout	Two seconds by default
HTTPConfig.MaxConcurrent	16 by default; excess calls return *AdapterError with category busy
HTTP adapter bodies	At most 64 KiB
HTTP adapter redirects	Same host and scheme; at most five hops
HTTP adapter work	None

Keep the authorization client open while requests are using it.

Error types

Tenant selection refusals use *tenant.FailureError.

Related pages

Package explanation · Task guide · Problem catalog