jwt

Documentation

Overview

Package jwt handles RS256 key management and ID token signing.

Index

• type IDClaims
• type JWK
• type JWKS
  • func BuildJWKS(ctx context.Context, st store.SigningKeyStore, kp bcrypto.KeyProvider) (*JWKS, error)
• type LogoutClaims
• type Signer
  • func LoadOrCreate(ctx context.Context, st store.SigningKeyStore, kp bcrypto.KeyProvider, ...) (*Signer, error)
  • func (s *Signer) KID() string
  • func (s *Signer) MintIDToken(userID, clientID, email, name, nonce string, scopes []string, mfaVerified bool, ...) (string, error)
  • func (s *Signer) MintLogoutToken(audience, sub, sid, jti string, now time.Time) (string, error)
  • func (s *Signer) PublicKey() *rsa.PublicKey

Types

type IDClaims

type IDClaims struct {
	gojwt.RegisteredClaims
	Nonce             string   `json:"nonce,omitempty"`
	AuthTime          int64    `json:"auth_time"`
	ACR               string   `json:"acr,omitempty"`
	AMR               []string `json:"amr,omitempty"`
	SID               string   `json:"sid,omitempty"`
	Email             string   `json:"email,omitempty"`
	Name              string   `json:"name,omitempty"`
	PreferredUsername string   `json:"preferred_username,omitempty"`
}

IDClaims holds standard OIDC ID token claims.

SID is the OIDC Back-Channel Logout 1.0 `sid` claim — a stable identifier for the user's session at the OP that's emitted on every ID token minted under that session (initial code grant + every refresh). RPs persist `sid` on their own session row at first issuance so a later logout_token POST can tell them which local session to invalidate. Omitted when the caller passes the empty string (e.g. session-less client-credentials flows).

type JWK

type JWK struct {
	KTY string `json:"kty"`
	USE string `json:"use"`
	ALG string `json:"alg"`
	KID string `json:"kid"`
	N   string `json:"n"`
	E   string `json:"e"`
}

JWK is a JSON Web Key (RFC 7517) for an RSA public key.

type JWKS

type JWKS struct {
	Keys []JWK `json:"keys"`
}

JWKS is the JSON Web Key Set returned at /.well-known/jwks.json.

func BuildJWKS

func BuildJWKS(ctx context.Context, st store.SigningKeyStore, kp bcrypto.KeyProvider) (*JWKS, error)

BuildJWKS loads all active signing keys and returns the key set.

type LogoutClaims

type LogoutClaims struct {
	gojwt.RegisteredClaims
	SID    string                    `json:"sid,omitempty"`
	Events map[string]map[string]any `json:"events"`
}

LogoutClaims is the JWT body of an OIDC Back-Channel Logout 1.0 logout_token.

Per §2.4 a logout_token MUST contain iss, aud, iat, jti, and `events` with the back-channel logout member set to an empty object; it MUST NOT contain a `nonce` claim. It SHOULD contain `sub` and/or `sid` — RPs use `sid` (when present) for session-scoped revocation and fall back to `sub` for whole-user revocation. Verifiers must reject any logout_token where `nonce` appears (replay-against-ID-token defence per §2.6).

type Signer

type Signer struct {
	// contains filtered or unexported fields
}

Signer holds an active RS256 private key and mints ID tokens.

func LoadOrCreate

func LoadOrCreate(ctx context.Context, st store.SigningKeyStore, kp bcrypto.KeyProvider, issuer string) (*Signer, error)

LoadOrCreate loads the active signing key from the store, decrypts it, and returns a Signer. If no active key exists, it generates a new one.

func (*Signer) KID

func (s *Signer) KID() string

KID returns the active key identifier.

func (*Signer) MintIDToken

func (s *Signer) MintIDToken(userID, clientID, email, name, nonce string, scopes []string, mfaVerified bool, amr []string, authTime time.Time, sid string) (string, error)

MintIDToken creates a signed RS256 JWT ID token. sid (empty string accepted) is emitted as the OIDC Back-Channel Logout 1.0 `sid` claim and lets RPs correlate a logout_token back to a specific local session row.

func (*Signer) MintLogoutToken

func (s *Signer) MintLogoutToken(audience, sub, sid, jti string, now time.Time) (string, error)

MintLogoutToken issues a signed RS256 JWT suitable for POSTing to an RP's backchannel_logout_uri. sid scopes the logout to a specific OP session row (empty = whole-user logout). exp defaults to 2 minutes per the spec's recommendation that logout_tokens be short-lived.

jti is supplied by the caller so the OP can log the same value that RPs use for replay detection — easier post-mortems when something goes wrong. Pass uuid.NewString() at the call site.

func (*Signer) PublicKey

func (s *Signer) PublicKey() *rsa.PublicKey

PublicKey returns the active RSA public key.