Documentation
¶
Overview ¶
Package authtest provides a shared HTTP contract harness for the auth examples (400-auth). It exercises the behaviour every auth driver must satisfy — authorization, API keys, CSRF, tenant scoping, rate limiting, dual auth, security headers, CRUD/audit, admin self-protection and cookie transport — independent of who provides identity (manual, Zitadel, Kratos) or authorization (database, OpenFGA, Keto).
The driver-specific parts (how to obtain a subject token, how to grant a role, how to revoke it) are supplied by the caller through SubjectProvider, so the same contract runs unchanged across stacks. Optional capabilities (cross-org subjects, cookie transport) are negotiated through the OrgSubjectProvider and CookieSubjectProvider interfaces: stacks whose IdP cannot supply them skip those checks with an explicit log line instead of simulating an identity they do not have. Use Run to execute the whole suite from an example's test binary.
Index ¶
Constants ¶
const DefaultBaseURL = "http://localhost:23400/api"
DefaultBaseURL is the base URL the examples listen on.
const DefaultHealthURL = "http://localhost:23400/healthz"
DefaultHealthURL is the readiness endpoint the examples expose.
Variables ¶
This section is empty.
Functions ¶
func AssertStatus ¶
AssertStatus is a small helper for examples to reuse in their own tests.
Types ¶
type Config ¶
type Config struct {
// BaseURL is the API base, e.g. http://localhost:23400/api.
BaseURL string
// HealthURL is the readiness endpoint (default BaseURL + "/healthz" root).
HealthURL string
// Timeout for the readiness wait.
ReadyTimeout time.Duration
}
Config describes how to reach an example under test.
type CookieSubjectProvider ¶
type CookieSubjectProvider interface {
SubjectProvider
// Cookie returns the session cookie name and value for /cookie/profile.
Cookie(t *testing.T) (name, value string)
}
CookieSubjectProvider is an optional extension for stacks whose login flow issues a session cookie usable against cookie-transport endpoints. Stacks without one skip the cookie checks with a log line.
type OrgSubjectProvider ¶
type OrgSubjectProvider interface {
SubjectProvider
// PrincipalInOrg returns a subject authenticated inside the named org.
PrincipalInOrg(t *testing.T, org string, roles ...string) Subject
}
OrgSubjectProvider is an optional extension for stacks that can place subjects in different organizations (tenant scoping). Stacks whose IdP issues a single-org identity (a Zitadel machine key, one Kratos session) do not implement it: the cross-tenant checks are skipped with a log line.
type Subject ¶
type Subject struct {
// Token is the credential sent as "Authorization: Bearer <Token>".
Token string
// ID is the subject identifier (used for self-checks like "cannot delete
// yourself").
ID string
}
Subject is an authenticated caller the contract can act as.
type SubjectProvider ¶
type SubjectProvider interface {
// Principal returns a subject that should satisfy the roles named (by
// granting them if necessary). At least "admin", "editor" and "viewer" must
// be supported by the examples the contract targets.
Principal(t *testing.T, roles ...string) Subject
// Revoke removes the given role from a subject, if the stack can.
Revoke(t *testing.T, s Subject, role string)
// APIKey returns a raw API key string and its role, if the stack seeds keys.
// Return ("", "") when the stack has no API keys.
APIKey(t *testing.T, name string) (key, role string)
}
SubjectProvider supplies driver-specific identity and authorization actions. Each auth example implements this over its stack.
type T ¶
type T interface {
Helper()
Fatalf(format string, args ...any)
Errorf(format string, args ...any)
Logf(format string, args ...any)
Skipf(format string, args ...any)
}
T is the subset of *testing.T the contract uses, so it is testable itself.
type TenantSubjectProvider ¶
type TenantSubjectProvider interface {
SubjectProvider
// PrincipalWithTenant returns a subject whose token carries tenant as its
// org claim.
PrincipalWithTenant(t *testing.T, tenant string, roles ...string) Subject
}
TenantSubjectProvider is an optional extension for stacks whose identity carries an organization claim (so the tenant_scope CRUD entry can resolve it). Opaque-token stacks whose introspection returns no org — a Zitadel machine token — do not implement it and skip tenant checks with a log line.
Source Files