iam

Documentation

Overview

Package iam authenticates requests using IAM (Keycloak) service JWTs.

Index

• type Authenticator
  • func New[U any](cfg Config, p authentication.UserResolver[U], opts ...Option) *Authenticator[U]
  • func (a *Authenticator[U]) Authenticate(ctx context.Context, token string) (*authorization.Actor, *U, error)
  • func (a *Authenticator[U]) EnsureRoles(ctx context.Context, token string, actor *authorization.Actor) (*authorization.Actor, error)
• type Claims
• type Config
• type Option
  • func WithHTTPClient(c *http.Client) Option
  • func WithJWKSCooldown(d time.Duration) Option
• type RealmAccess

Types

type Authenticator

type Authenticator[U any] struct {
	// contains filtered or unexported fields
}

Authenticator validates Bearer tokens against the IAM (Keycloak) JWKS endpoint and resolves the service's user entity via the UserResolver.

func New

func New[U any](cfg Config, p authentication.UserResolver[U], opts ...Option) *Authenticator[U]

func (*Authenticator[U]) Authenticate

func (a *Authenticator[U]) Authenticate(
	ctx context.Context, token string,
) (*authorization.Actor, *U, error)

Authenticate verifies the token signature and claims, then builds the caller's identity from the token alone: a service actor for service-account tokens, or a user actor plus the resolved user entity for user tokens.

Realm roles are taken as-is from the token; routes that need them complete call EnsureRoles.

func (*Authenticator[U]) EnsureRoles

func (a *Authenticator[U]) EnsureRoles(
	ctx context.Context, token string, actor *authorization.Actor,
) (*authorization.Actor, error)

EnsureRoles guarantees the actor's realm roles are populated, fetching them from the userinfo endpoint when the access token carried none. It is a no-op for actors that already have roles, for service actors, and when no userinfo endpoint is configured — so it is safe to call on any actor.

type Claims

type Claims struct {
	Sub                    string      `json:"sub"`
	Iss                    string      `json:"iss"`
	AuthorizedParty        string      `json:"azp"`
	Email                  string      `json:"email"`
	PhoneNumber            string      `json:"phone_number"`
	PreferredUsername      string      `json:"preferred_username"`
	GivenName              string      `json:"given_name"`
	FamilyName             string      `json:"family_name"`
	CountryISO             string      `json:"country_iso"`
	Locale                 string      `json:"locale"`
	Exp                    int64       `json:"exp"`
	Scope                  string      `json:"scope"`
	RealmAccess            RealmAccess `json:"realm_access"`
	ServiceAccountClientID string      `json:"service_account_client_id"`
}

Claims holds the parsed JWT payload fields used by platform services.

type Config

type Config struct {
	Issuer      string
	JwksUrl     string
	ServiceName string
}

Config carries the IAM endpoints and the auth configurations.

type Option

type Option func(*options)

Option customizes the authenticator. The defaults are production-ready; options exist mainly for tests and unusual network setups.

func WithHTTPClient

func WithHTTPClient(c *http.Client) Option

WithHTTPClient replaces the HTTP client used for the JWKS and userinfo endpoints (e.g. an in-process round-tripper in tests).

func WithJWKSCooldown

func WithJWKSCooldown(d time.Duration) Option

WithJWKSCooldown sets the minimum interval between JWKS refetches triggered by unknown key IDs. Zero disables the cooldown. Default: 30s.

type RealmAccess

type RealmAccess struct {
	Roles []string `json:"roles"`
}

RealmAccess represents the realm-level role assignments in a Keycloak JWT token.