tok

Documentation

Overview

Package tok provides AuthN token (structure and methods) for validation by AIS gateways

• Copyright (c) 2025, NVIDIA CORPORATION. All rights reserved.

Package tok provides AuthN token (structure and methods) for validation by AIS gateways

• Copyright (c) 2018-2026, NVIDIA CORPORATION. All rights reserved.

Index

• Variables
• func CreateHMACTokenStr(c jwt.Claims, secret cmn.Censored) (string, error)
• func CreateRSATokenStr(c jwt.Claims, rsaKey *rsa.PrivateKey) (string, error)
• type AISClaims
  • func AdminClaims(expires time.Time, userID, aud string) *AISClaims
  • func StandardClaims(expires time.Time, userID, aud string, bucketACLs []*authn.BckACL, ...) *AISClaims
  • func (c *AISClaims) CheckPermissions(clusterID string, bck *cmn.Bck, perms apc.AccessAttrs) error
  • func (c *AISClaims) GetExpirationTime() (*jwt.NumericDate, error)
  • func (c *AISClaims) GetSubject() (string, error)
  • func (c *AISClaims) IsExpired() bool
  • func (c *AISClaims) IsUser(user string) bool
  • func (c *AISClaims) String() string
  • func (c *AISClaims) Validate() error
• type CacheConfig
• type DiscoveryConf
• type JWKSRoundTripper
  • func NewJWKSRoundTripper(base http.RoundTripper, statsT stats.Tracker) *JWKSRoundTripper
  • func (jrt *JWKSRoundTripper) RoundTrip(req *http.Request) (*http.Response, error)
• type KeyCacheManager
  • func NewKeyCacheManager(oidc *cmn.OIDCConf, client *http.Client, cacheConf *CacheConfig, ...) *KeyCacheManager
  • func (km *KeyCacheManager) IncCounter(metric string)
  • func (km *KeyCacheManager) Init(rootCtx context.Context)
  • func (km *KeyCacheManager) PopulateJWKSCache(ctx context.Context) error
• type Parser
• type SigConfig
• type TokenHdr
  • func ExtractToken(hdr http.Header) (*TokenHdr, error)
• type TokenParser
  • func NewTokenParser(conf *cmn.AuthConf, cacheManager *KeyCacheManager) *TokenParser
  • func (tm *TokenParser) IsPublicKeyValid(pubKeyStr string) (bool, error)
  • func (tm *TokenParser) IsSecretCksumValid(cksumVal string) bool
  • func (tm *TokenParser) ValidateToken(ctx context.Context, tokenStr string) (*AISClaims, error)

Variables

var (
	ErrNoPermissions = errors.New("insufficient permissions")
	ErrInvalidToken  = errors.New("invalid token")
	ErrNoSubject     = errors.New("missing 'sub' or 'username' claims")
	ErrNoToken       = errors.New("token required")
	ErrTokenExpired  = errors.New("token expired")
	ErrTokenRevoked  = errors.New("token revoked")
)

var ErrNoJWKSForIssuer = errors.New("no JWKS entry exists for issuer")

Functions

func CreateHMACTokenStr

func CreateHMACTokenStr(c jwt.Claims, secret cmn.Censored) (string, error)

func CreateRSATokenStr

func CreateRSATokenStr(c jwt.Claims, rsaKey *rsa.PrivateKey) (string, error)

Types

type AISClaims

type AISClaims struct {
	// Deprecated: Use RegisteredClaims.Subject instead, mapped to 'sub' claim.
	UserID string `json:"username"`
	// Deprecated: Use RegisteredClaims.ExpiresAt instead, mapped to 'exp' claim.
	Expires     time.Time       `json:"expires"`
	ClusterACLs []*authn.CluACL `json:"clusters"`
	BucketACLs  []*authn.BckACL `json:"buckets,omitempty"`
	IsAdmin     bool            `json:"admin"`
	jwt.RegisteredClaims
}

func AdminClaims

func AdminClaims(expires time.Time, userID, aud string) *AISClaims

func StandardClaims

func StandardClaims(expires time.Time, userID, aud string, bucketACLs []*authn.BckACL, clusterACLs []*authn.CluACL) *AISClaims

func (*AISClaims) CheckPermissions

func (c *AISClaims) CheckPermissions(clusterID string, bck *cmn.Bck, perms apc.AccessAttrs) error

func (*AISClaims) GetExpirationTime

func (c *AISClaims) GetExpirationTime() (*jwt.NumericDate, error)

GetExpirationTime implements Claims interface with backwards-compatible support for 'expires'

func (*AISClaims) GetSubject

func (c *AISClaims) GetSubject() (string, error)

GetSubject implements Claims interface with backwards-compatible support for 'username'

func (*AISClaims) IsExpired

func (c *AISClaims) IsExpired() bool

func (*AISClaims) IsUser

func (c *AISClaims) IsUser(user string) bool

func (*AISClaims) String

func (c *AISClaims) String() string

func (*AISClaims) Validate

func (c *AISClaims) Validate() error

Validate implements Claims interface to add extra claims validation after parsing a token

type CacheConfig

type CacheConfig struct {
	DiscoveryConf           *DiscoveryConf
	MinCacheRefreshInterval *time.Duration
}

type DiscoveryConf

type DiscoveryConf struct {
	Retries   int
	BaseDelay time.Duration
}

type JWKSRoundTripper

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

JWKSRoundTripper wraps http.RoundTripper to track latency of JWKS fetches

func NewJWKSRoundTripper

func NewJWKSRoundTripper(base http.RoundTripper, statsT stats.Tracker) *JWKSRoundTripper

func (*JWKSRoundTripper) RoundTrip

func (jrt *JWKSRoundTripper) RoundTrip(req *http.Request) (*http.Response, error)

RoundTrip implements http.RoundTripper with additional stats wrapping

type KeyCacheManager

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

func NewKeyCacheManager

func NewKeyCacheManager(oidc *cmn.OIDCConf, client *http.Client, cacheConf *CacheConfig, statsT stats.Tracker) *KeyCacheManager

NewKeyCacheManager creates an instance of KeyCacheManager with an unpopulated cache After creating, call Init with a long-lived context to create a key cache Optionally, also pre-populate the cache to register and preload the allowed issuers

func (*KeyCacheManager) IncCounter

func (km *KeyCacheManager) IncCounter(metric string)

func (*KeyCacheManager) Init

func (km *KeyCacheManager) Init(rootCtx context.Context)

Init prepares a key cache manager to provide to a token parser The provided context must be valid for the life of the cache for automatic refresh

func (*KeyCacheManager) PopulateJWKSCache

func (km *KeyCacheManager) PopulateJWKSCache(ctx context.Context) error

PopulateJWKSCache looks up JWKS URLs, adds them to the cache, and preloads JWKS Returns error only on context cancellation or invalid config

type Parser

type Parser interface {
	// ValidateToken verifies JWT signature and extracts token claims.
	ValidateToken(ctx context.Context, tokenStr string) (*AISClaims, error)
	// IsSecretCksumValid checks if a provided secret checksum is valid.
	IsSecretCksumValid(cksumVal string) bool
	// IsPublicKeyValid checks if a provided public key matches the parser's key.
	IsPublicKeyValid(pubKeyStr string) (bool, error)
}

type SigConfig

type SigConfig struct {
	HMACSecret   cmn.Censored
	RSAPublicKey *rsa.PublicKey
}

type TokenHdr

type TokenHdr struct {
	// Request header containing token string
	Header string
	// Raw token string from request
	Token string
}

func ExtractToken

func ExtractToken(hdr http.Header) (*TokenHdr, error)

ExtractToken extracts JWT token from either Authorization header (Bearer token) or X-Amz-Security-Token header with the following priority:

1. Authorization: Bearer <token> (standard JWT auth)
2. X-Amz-Security-Token: enables native AWS SDK clients to authenticate using AIS-compatible JWT tokens passed when using SigV4 authentication.

type TokenParser

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

func NewTokenParser

func NewTokenParser(conf *cmn.AuthConf, cacheManager *KeyCacheManager) *TokenParser

NewTokenParser creates a new instance of TokenParser. If using allowed issuers and public key lookups, call InitKeyCache after creation

func (*TokenParser) IsPublicKeyValid

func (tm *TokenParser) IsPublicKeyValid(pubKeyStr string) (bool, error)

IsPublicKeyValid Checks if a provided public key matches what this cluster will use to validate tokens

func (*TokenParser) IsSecretCksumValid

func (tm *TokenParser) IsSecretCksumValid(cksumVal string) bool

IsSecretCksumValid Checks if a provided secret checksum is valid for signing requests to be parsed by this cluster

func (*TokenParser) ValidateToken

func (tm *TokenParser) ValidateToken(ctx context.Context, tokenStr string) (*AISClaims, error)

ValidateToken verifies JWT signature and extracts token claims (supporting both HMAC (HS256) and RSA (RS256) signing methods) - HS256: validates with secret (symmetric) - RS256: validates with pubKey (asymmetric)