Documentation
¶
Index ¶
- Constants
- Variables
- func ContextWithClaims(ctx context.Context, claims *Claims) context.Context
- func GenerateAdminTestToken() string
- func GenerateTestToken(role string, permissions []string) string
- func NewSecurityHandlerModule(opts ...Option) fx.Option
- type Claims
- type Config
- type Option
- type S2SConfig
- type SecurityHandler
- type Validator
Constants ¶
const WildcardPermission = "*"
WildcardPermission grants access to all permissions.
Variables ¶
var ( // ErrInvalidToken is returned when the token cannot be parsed or verified. ErrInvalidToken = errors.New("invalid token") // ErrTenantMismatch is returned when the token's tenant claim doesn't match the request tenant. ErrTenantMismatch = errors.New("token tenant mismatch") // ErrInvalidPublicKey is returned when the public key is invalid. ErrInvalidPublicKey = errors.New("invalid public key") )
var ErrInsufficientPermissions = errors.New("insufficient permissions")
ErrInsufficientPermissions is returned when user lacks required permissions.
Functions ¶
func ContextWithClaims ¶
ContextWithClaims returns a new context with the claims stored.
func GenerateAdminTestToken ¶ added in v0.4.3
func GenerateAdminTestToken() string
GenerateAdminTestToken creates a test token with admin role and wildcard permissions.
func GenerateTestToken ¶ added in v0.4.3
GenerateTestToken creates a base64-encoded JSON token from claims. Use this in tests to create tokens that testValidator can decode.
func NewSecurityHandlerModule ¶ added in v0.4.3
NewSecurityHandlerModule provides a SecurityHandler for dependency injection. This is the recommended way to handle authentication in services. Also provides Validator for services that need direct token validation (e.g., refresh tokens).
Options:
- WithTokenConfig: provide static token Config (useful for tests)
- WithDisableValidation: bypass all security, returns admin claims
- WithTestValidator: use base64 JSON tokens (for e2e tests with realistic flow)
Example usage:
// Production - validates JWT tokens via JWKS token.NewSecurityHandlerModule() // Testing - bypass security completely token.NewSecurityHandlerModule(token.WithDisableValidation()) // E2E testing - use base64 JSON tokens token.NewSecurityHandlerModule(token.WithTestValidator())
Types ¶
type Claims ¶
type Claims struct {
// Tenant is the tenant slug this token was issued for.
// Empty for service tokens (they operate cross-tenant).
Tenant string
// Role is the user's role (e.g., "super_admin", "catalog_manager", "viewer").
Role string
// Permissions is the list of permissions granted to the user.
Permissions []string
}
Claims represents the token claims. This is used across all services for authentication.
func ClaimsFromContext ¶
ClaimsFromContext retrieves claims from the context. Returns nil if no claims are present.
func (*Claims) HasAnyPermission ¶
HasAnyPermission checks if the user has at least one of the required permissions. Returns true if the user has any of the specified permissions or the wildcard permission.
func (*Claims) IsTenantScoped ¶ added in v0.6.9
IsTenantScoped returns true if the token is bound to a specific tenant. Returns false for service accounts and platform admins (they operate cross-tenant).
type Config ¶
type Config struct {
// JwksURL is the URL to fetch the JSON Web Key Set for verifying tokens.
// Example: "http://zitadel:8080/oauth/v2/keys"
JwksURL string `koanf:"jwks-url"`
// HostOverride overrides the Host header in HTTP requests to the JWKS endpoint.
// Use when the server requires a specific Host header (e.g. Zitadel with ExternalDomain).
HostOverride string `koanf:"host-override"`
}
Config holds the configuration for JWT token validation (incoming requests).
type Option ¶ added in v0.4.3
type Option func(*tokenOptions)
Option is a functional option for configuring the token module.
func WithDisableValidation ¶ added in v0.4.3
func WithDisableValidation() Option
WithDisableValidation disables token validation and returns noop validator. Useful for tests where token validation should be bypassed.
func WithTestClaims ¶ added in v0.4.3
WithTestClaims provides a validator that always returns the given claims. Useful for tests that need specific user context.
func WithTestValidator ¶ added in v0.4.3
func WithTestValidator() Option
WithTestValidator enables the test validator that decodes base64-encoded JSON tokens. Use GenerateTestToken or GenerateAdminTestToken to create tokens for this validator. Useful for e2e/integration tests where you want realistic token flow without JWT JWKS.
func WithTokenConfig ¶ added in v0.4.3
WithTokenConfig provides a static Config (useful for tests).
type S2SConfig ¶ added in v0.6.9
type S2SConfig struct {
// ClientID is the OAuth2 client ID (Zitadel machine user ID).
ClientID string `koanf:"client-id"`
// ClientSecret is the OAuth2 client secret for the client_credentials flow.
ClientSecret string `koanf:"client-secret"`
// TokenURL is the OAuth2 token endpoint.
// Example: "http://zitadel:8080/oauth/v2/token"
TokenURL string `koanf:"token-url"`
// HostOverride overrides the Host header in HTTP requests to the token endpoint.
// Use when the server requires a specific Host header (e.g. Zitadel with ExternalDomain).
HostOverride string `koanf:"host-override"`
}
S2SConfig holds the configuration for service-to-service authentication (outgoing requests).
type SecurityHandler ¶ added in v0.4.3
type SecurityHandler interface {
// HandleBearerAuth validates a token and checks permissions.
// Returns the context with claims stored, the claims, and any error.
HandleBearerAuth(ctx context.Context, token string, requiredPermissions []string) (context.Context, *Claims, error)
}
SecurityHandler handles bearer token authentication and authorization. Different validators provide different behaviors for production vs testing.
Source Files