token

Documentation

Overview

Package token defines types and utilities for JWT-based authentication in microservices. It supports standard JWT claims (RFC 7519), OpenID Connect fields (OIDC Core 1.0), OAuth2/JWT Bearer extensions (RFC 7523), and NIST SP 800-63B–compliant claims. All validation logic should follow JSON Web Token Best Current Practices (RFC 8725) for algorithm selection, header/claim validation, and cryptographic hygiene, using only FIPS 140-2 or FIPS 140-3–validated modules and approved algorithms.

Index

• Constants
• Variables
• type ExtendedClaims
  • func (ec *ExtendedClaims) MarshalJSON() ([]byte, error)
• type TSClaims
  • func NewClaims() *TSClaims
  • func (c *TSClaims) Validate(enforce bool) error
  • func (c *TSClaims) ValidateAt(enforce bool, now time.Time) error
• type TokenManager
  • func NewTokenManager(keyManager *keys.KeyManager, issuer string, clusterID string, ...) *TokenManager
  • func (tm *TokenManager) GenerateServiceToken(serviceID, targetService string, scopes []string) (string, error)
  • func (tm *TokenManager) GenerateToken(claims *TSClaims) (string, error)
  • func (tm *TokenManager) GenerateTokenWithClaims(claims *TSClaims, additionalClaims map[string]interface{}) (string, error)
  • func (tm *TokenManager) GetKeyManager() *keys.KeyManager
  • func (tm *TokenManager) GetSigningAlgorithm() string
  • func (tm *TokenManager) ParseToken(tokenString string) (*TSClaims, map[string]interface{}, error)
  • func (tm *TokenManager) SetSigningAlgorithm(algorithm string) error

Constants

const (
	// RSASSA-PSS with SHA-256 (FIPS 186-4)
	DefaultSigningAlgorithm = "PS256"
	// RSASSA-PKCS1-v1_5 with SHA-256 (FIPS 186-4)
	LegacySigningAlgorithm = "RS256"
)

FIPS-approved algorithms for JWT signing

Variables

var (
	// ErrTokenExpired indicates that the token has expired
	ErrTokenExpired = errors.New("token has expired")

	// ErrTokenNotValidYet indicates that the token is not yet valid
	ErrTokenNotValidYet = errors.New("token is not yet valid")

	// ErrMissingIssuer indicates that the issuer claim is missing
	ErrMissingIssuer = errors.New("missing issuer claim")

	// ErrMissingSubject indicates that the subject claim is missing
	ErrMissingSubject = errors.New("missing subject claim")

	// ErrMissingAudience indicates that the audience claim is missing
	ErrMissingAudience = errors.New("missing audience claim")

	// ErrInvalidSignature indicates that the token signature is invalid
	ErrInvalidSignature = errors.New("invalid token signature")

	// ErrInvalidToken indicates that the token is invalid
	ErrInvalidToken = errors.New("invalid token")

	// ErrInvalidKey indicates that the key is invalid
	ErrInvalidKey = errors.New("invalid key")

	// ErrTokenIntrospectionFailed indicates that token introspection failed
	ErrTokenIntrospectionFailed = errors.New("token introspection failed")
)

Types

type ExtendedClaims

type ExtendedClaims struct {
	*TSClaims
	AdditionalClaims map[string]interface{} `json:"-"`
}

ExtendedClaims extends TSClaims with additional custom claims

func (*ExtendedClaims) MarshalJSON

func (ec *ExtendedClaims) MarshalJSON() ([]byte, error)

MarshalJSON implements custom JSON marshaling to include additional claims

type TSClaims

type TSClaims struct {
	jwt.RegisteredClaims // Embedded RegisteredClaims provides standard JWT fields like "iss", "sub", "aud", etc.

	// Nonce is an optional value to mitigate replay attacks in interactive flows.
	// JSON key: "nonce"
	// RFC 8725 §3.5: use when tokens may be replayed in browser-based contexts.
	Nonce string `json:"nonce,omitempty"`

	// Name is the end-user's full name.
	// JSON key: "name"
	// OIDC Core 1.0; include only if needed by downstream services.
	Name string `json:"name,omitempty"`

	// Email is the end-user's email address.
	// JSON key: "email"
	// OIDC Core 1.0; include only if needed by downstream services.
	Email string `json:"email,omitempty"`

	// EmailVerified indicates whether the email address is verified.
	// JSON key: "email_verified"
	// OIDC Core 1.0; RFC 8725 §3.2: consider as part of trust decisions.
	EmailVerified bool `json:"email_verified,omitempty"`

	// AuthTime is when the end-user authentication occurred, in Unix seconds.
	// JSON key: "auth_time"
	// OIDC Core 1.0 §2; RFC 8725 §3.5: use for step-up/auth freshness checks.
	AuthTime int64 `json:"auth_time,omitempty"`

	// AMR lists the authentication methods used (e.g., ["pwd","otp","fido2"]).
	// JSON key: "amr"
	// OIDC Core 1.0 §3; RFC 8725 §3.2: validate each method reference.
	AMR []string `json:"amr,omitempty"`

	// ACR indicates the authentication context class reference (e.g., "AAL2").
	// JSON key: "acr"
	// OIDC Core 1.0 §3; NIST SP 800-63B §5.2.4; RFC 8725 §3.2: ensure it meets policy.
	ACR string `json:"acr,omitempty"`

	// Scope lists permissions or scopes granted.
	// JSON key: "scope"
	// OAuth 2.0 JWT Bearer (RFC 7523); RFC 8725 §3.2: validate scopes against client entitlements.
	Scope []string `json:"scope,omitempty"`

	// AuthLevel indicates the Identity Assurance Level (IAL1, IAL2, IAL3).
	// JSON key: "auth_level"
	// NIST SP 800-63B §5.2.4; RFC 8725 §3.2: enforce minimum IAL for sensitive operations.
	AuthLevel string `json:"auth_level,omitempty"`

	// AuthFactors is the number of distinct auth factors presented.
	// JSON key: "auth_factors"
	// NIST SP 800-63B; RFC 8725 §3.2: require at least 2 factors for IAL2+.
	AuthFactors int `json:"auth_factors,omitempty"`

	// AuthMethods lists the methods used (e.g., ["password","sms","webauthn"]).
	// JSON key: "auth_methods"
	// NIST SP 800-63B §5.2.4; RFC 8725 §3.2: validate values before use.
	AuthMethods []string `json:"auth_methods,omitempty"`

	// SessionID is a unique session identifier for lifecycle management.
	// JSON key: "session_id"
	// NIST SP 800-63B session guidance; RFC 8725 §3.5: use for server-side session tracking.
	SessionID string `json:"session_id,omitempty"`

	// SessionExp is the session expiration, in Unix seconds.
	// JSON key: "session_exp"
	// NIST SP 800-63B session guidance; RFC 8725 §3.5: enforce max session duration.
	SessionExp int64 `json:"session_exp,omitempty"`

	// AuthEvents records past authentication events (e.g., ["login","reset_pwd"]).
	// JSON key: "auth_events"
	// NIST SP 800-63B; RFC 8725 §3.2: maintain history for anomaly detection.
	AuthEvents []string `json:"auth_events,omitempty"`

	// ClusterID is an OpenCHAMI claim for the requesting cluster.
	// JSON key: "cluster_id"
	ClusterID string `json:"cluster_id,omitempty"`

	// OpenCHAMIID is an OpenCHAMI claim for the unique entity ID.
	// JSON key: "openchami_id"
	OpenCHAMIID string `json:"openchami_id,omitempty"`
}

Claims represents the JWT claims structure used for user authentication.

Standards referenced:

• Core JWT: RFC 7519 https://datatracker.ietf.org/doc/html/rfc7519
• JWT Bearer: RFC 7523 https://datatracker.ietf.org/doc/html/rfc7523
• OpenID Connect: Core 1.0 https://openid.net/specs/openid-connect-core-1_0.html#IDToken
• NIST SP 800-63B: §§5.2.4 (Authentication Context), session management
• JWT Best Practices: RFC 8725 (§3.1–3.5, §3.2 header & claim rules)
• FIPS 140-2/3: Approved security functions (e.g., RSA-PSS, ECDSA P-256, AES-GCM) https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.140-3.pdf and https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.140-2.pdf

func NewClaims

func NewClaims() *TSClaims

NewClaims creates a new Claims instance with default timestamps: IssuedAt = now, NotBefore = now, ExpirationTime = now + 1h.

func (*TSClaims) Validate

func (c *TSClaims) Validate(enforce bool) error

Validate checks if the claims are valid according to RFC 7519, RFC 8725, and NIST SP 800-63B. If enforce is false, violations are logged but do not cause errors.

func (*TSClaims) ValidateAt

func (c *TSClaims) ValidateAt(enforce bool, now time.Time) error

ValidateAt checks if the claims are valid at the provided time according to RFC 7519, RFC 8725, and NIST SP 800-63B.

type TokenManager

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

TokenManager handles JWT token operations

func NewTokenManager

func NewTokenManager(keyManager *keys.KeyManager, issuer string, clusterID string, openchamiID string, enforce bool) *TokenManager

NewTokenManager creates a new TokenManager instance

func (*TokenManager) GenerateServiceToken

func (tm *TokenManager) GenerateServiceToken(serviceID, targetService string, scopes []string) (string, error)

GenerateServiceToken generates a token for service-to-service communication

func (*TokenManager) GenerateToken

func (tm *TokenManager) GenerateToken(claims *TSClaims) (string, error)

GenerateToken generates a new JWT token with the given claims

func (*TokenManager) GenerateTokenWithClaims

func (tm *TokenManager) GenerateTokenWithClaims(claims *TSClaims, additionalClaims map[string]interface{}) (string, error)

GenerateTokenWithClaims generates a new JWT token with the given claims and additional claims

func (*TokenManager) GetKeyManager

func (tm *TokenManager) GetKeyManager() *keys.KeyManager

GetKeyManager returns the underlying KeyManager instance

func (*TokenManager) GetSigningAlgorithm

func (tm *TokenManager) GetSigningAlgorithm() string

GetSigningAlgorithm returns the current signing algorithm

func (*TokenManager) ParseToken

func (tm *TokenManager) ParseToken(tokenString string) (*TSClaims, map[string]interface{}, error)

ParseToken parses a JWT token string into Claims

func (*TokenManager) SetSigningAlgorithm

func (tm *TokenManager) SetSigningAlgorithm(algorithm string) error

SetSigningAlgorithm sets the signing algorithm to use