jwt

Documentation

Overview

Package jwt provides primitives for working with JWT (Parser, Claims, and so on).

Index

• Constants
• type AccessPolicy
• type AudienceMissingError
  • func (e *AudienceMissingError) Error() string
• type AudienceNotExpectedError
  • func (e *AudienceNotExpectedError) Error() string
• type AudienceValidator
  • func NewAudienceValidator(requireAudience bool, audiencePatterns []string) *AudienceValidator
  • func (av *AudienceValidator) Validate(claims Claims) error
• type CachingKeysProvider
• type CachingParser
  • func NewCachingParser(keysProvider KeysProvider) (*CachingParser, error)
  • func NewCachingParserWithOpts(keysProvider KeysProvider, opts CachingParserOpts) (*CachingParser, error)
  • func (cp *CachingParser) InvalidateClaimsCache()
  • func (cp *CachingParser) Parse(ctx context.Context, token string) (Claims, error)
• type CachingParserOpts
• type Claims
• type ClaimsCache
• type DefaultClaims
  • func (c *DefaultClaims) ApplyScopeFilter(filter ScopeFilter)
  • func (c *DefaultClaims) Clone() Claims
  • func (c *DefaultClaims) GetID() string
  • func (c *DefaultClaims) GetScope() Scope
• type IssuerMissingError
  • func (e *IssuerMissingError) Error() string
• type IssuerUntrustedError
  • func (e *IssuerUntrustedError) Error() string
• type KeysProvider
• type Parser
  • func NewParser(keysProvider KeysProvider) *Parser
  • func NewParserWithOpts(keysProvider KeysProvider, opts ParserOpts) *Parser
  • func (p *Parser) AddTrustedIssuer(issName, issURL string)
  • func (p *Parser) AddTrustedIssuerURL(issURL string) error
  • func (p *Parser) GetURLForIssuer(issuer string) (string, bool)
  • func (p *Parser) Parse(ctx context.Context, token string) (Claims, error)
• type ParserOpts
• type Scope
• type ScopeFilter
• type ScopeFilterAccessPolicy
• type SignAlgUnknownError
  • func (e *SignAlgUnknownError) Error() string
• type TrustedIssNotFoundFallback

Constants

const DefaultClaimsCacheMaxEntries = 1000

Types

type AccessPolicy

type AccessPolicy struct {
	// TenantID is a unique identifier of tenant for which access is granted (if resource is not specified)
	// or which the resource is owned by (if resource is specified).
	TenantID string `json:"tid,omitempty"`

	// TenantUUID is a UUID of tenant for which access is granted (if the resource is not specified)
	// or which the resource is owned by (if the resource is specified).
	TenantUUID string `json:"tuid,omitempty"`

	// ResourceServerID is a unique resource server instance or cluster ID.
	ResourceServerID string `json:"rs,omitempty"`

	// ResourceNamespace is a namespace to which resource belongs within resource server.
	// E.g.: account-server, storage-manager, task-manager, alert-manager, etc.
	ResourceNamespace string `json:"rn,omitempty"`

	// ResourcePath is a unique identifier of or path to a single resource or resource collection
	// in the scope of the resource server and namespace.
	ResourcePath string `json:"rp,omitempty"`

	// Role determines what actions are allowed to be performed on the specified tenant or resource.
	Role string `json:"role,omitempty"`
}

AccessPolicy represents a single access policy which specifies access rights to a tenant or resource in the scope of a resource server.

type AudienceMissingError

type AudienceMissingError struct {
	Claims Claims
}

AudienceMissingError represents an error when JWT audience is missing, but it's required.

func (*AudienceMissingError) Error

func (e *AudienceMissingError) Error() string

type AudienceNotExpectedError

type AudienceNotExpectedError struct {
	Claims   Claims
	Audience jwtgo.ClaimStrings
}

AudienceNotExpectedError represents an error when JWT contains not expected audience.

func (*AudienceNotExpectedError) Error

func (e *AudienceNotExpectedError) Error() string

type AudienceValidator

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

AudienceValidator is a validator that checks if the audience claim ("aud") of the token is expected. It validates that the audience claim is presented and/or matches one of the expected glob patterns (e.g. "*.my-service.com").

func NewAudienceValidator

func NewAudienceValidator(requireAudience bool, audiencePatterns []string) *AudienceValidator

NewAudienceValidator creates a new AudienceValidator. If requireAudience is true, the audience claim must be presented in the token. If audiencePatterns is not empty, the audience claim must match at least one of the patterns.

func (*AudienceValidator) Validate

func (av *AudienceValidator) Validate(claims Claims) error

Validate checks if the audience claim of the token is expected.

type CachingKeysProvider

type CachingKeysProvider interface {
	KeysProvider
	InvalidateCacheIfNeeded(ctx context.Context, issuer string) error
}

CachingKeysProvider is an interface for providing keys for verifying JWT. Unlike KeysProvider, it supports caching of obtained keys.

type CachingParser

type CachingParser struct {
	*Parser
	ClaimsCache ClaimsCache
	// contains filtered or unexported fields
}

CachingParser uses the functionality of Parser to parse JWT, but stores resulted Claims objects in the cache.

func NewCachingParser

func NewCachingParser(keysProvider KeysProvider) (*CachingParser, error)

func NewCachingParserWithOpts

func NewCachingParserWithOpts(
	keysProvider KeysProvider, opts CachingParserOpts,
) (*CachingParser, error)

func (*CachingParser) InvalidateClaimsCache

func (cp *CachingParser) InvalidateClaimsCache()

InvalidateClaimsCache removes all preserved parsed Claims objects from cache.

func (*CachingParser) Parse

func (cp *CachingParser) Parse(ctx context.Context, token string) (Claims, error)

Parse calls Parse method of embedded original Parser but stores result into cache.

type CachingParserOpts

type CachingParserOpts struct {
	ParserOpts
	CacheMaxEntries              int
	CachePrometheusInstanceLabel string
}

type Claims

type Claims interface {
	jwtgo.Claims

	// GetID returns the JTI field of the claims.
	GetID() string

	// GetScope returns the scope of the claims as a slice of access policies.
	GetScope() Scope

	// Clone returns a deep copy of the claims.
	Clone() Claims

	// ApplyScopeFilter filters (in-place) the scope of the claims by the specified filter.
	ApplyScopeFilter(filter ScopeFilter)
}

Claims is an interface that extends jwt.Claims from the "github.com/golang-jwt/jwt/v5" with additional methods for working with access policies.

type ClaimsCache

type ClaimsCache interface {
	Get(key [sha256.Size]byte) (Claims, bool)
	Add(key [sha256.Size]byte, claims Claims)
	Purge()
	Len() int
}

ClaimsCache is an interface that must be implemented by used cache implementations.

type DefaultClaims

type DefaultClaims struct {
	jwtgo.RegisteredClaims
	Scope Scope `json:"scope,omitempty"`
}

DefaultClaims is a struct that extends jwt.RegisteredClaims with a custom scope field. It may be embedded into custom claims structs if additional fields are required.

func (*DefaultClaims) ApplyScopeFilter

func (c *DefaultClaims) ApplyScopeFilter(filter ScopeFilter)

ApplyScopeFilter filters (in-place) the scope of the DefaultClaims by the specified filter.

func (*DefaultClaims) Clone

func (c *DefaultClaims) Clone() Claims

Clone returns a deep copy of the DefaultClaims.

func (*DefaultClaims) GetID

func (c *DefaultClaims) GetID() string

GetID returns the JTI field of the DefaultClaims.

func (*DefaultClaims) GetScope

func (c *DefaultClaims) GetScope() Scope

GetScope returns the scope of the DefaultClaims as a slice of access policies.

type IssuerMissingError

type IssuerMissingError struct {
	Claims Claims
}

IssuerMissingError represents an error when JWT issuer is missing.

func (*IssuerMissingError) Error

func (e *IssuerMissingError) Error() string

type IssuerUntrustedError

type IssuerUntrustedError struct {
	Claims Claims
	Issuer string
}

IssuerUntrustedError represents an error when JWT issuer is untrusted.

func (*IssuerUntrustedError) Error

func (e *IssuerUntrustedError) Error() string

type KeysProvider

type KeysProvider interface {
	GetRSAPublicKey(ctx context.Context, issuer, keyID string) (interface{}, error)
}

KeysProvider is an interface for providing keys for verifying JWT.

type Parser

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

Parser is an object for parsing, validation and verification JWT.

func NewParser

func NewParser(keysProvider KeysProvider) *Parser

NewParser creates new JWT parser with specified keys provider.

func NewParserWithOpts

func NewParserWithOpts(keysProvider KeysProvider, opts ParserOpts) *Parser

NewParserWithOpts creates new JWT parser with specified keys provider and additional options.

func (*Parser) AddTrustedIssuer

func (p *Parser) AddTrustedIssuer(issName, issURL string)

AddTrustedIssuer adds trusted issuer with specified name and URL.

func (*Parser) AddTrustedIssuerURL

func (p *Parser) AddTrustedIssuerURL(issURL string) error

AddTrustedIssuerURL adds trusted issuer URL.

func (*Parser) GetURLForIssuer

func (p *Parser) GetURLForIssuer(issuer string) (string, bool)

GetURLForIssuer returns URL for issuer if it is trusted.

func (*Parser) Parse

func (p *Parser) Parse(ctx context.Context, token string) (Claims, error)

Parse parses, validates and verifies passed token (it's string representation). Parsed claims is returned.

type ParserOpts

type ParserOpts struct {
	// SkipClaimsValidation allows skipping claims validation (e.g., checking expiration time).
	// Use it with caution, and only if you know what you are doing.
	// For example, if you want to validate claims by yourself.
	// It doesn't affect signature verification.
	SkipClaimsValidation bool

	// RequireAudience specifies whether audience should be required. If true, "aud" claim must be present in the token.
	RequireAudience bool

	// ExpectedAudience is a list of expected audience values.
	// It's allowed to use glob patterns (*.my-service.com) for audience matching.
	// If it's not empty, "aud" JWT claim must match at least one of the patterns.
	ExpectedAudience []string

	// TrustedIssuerNotFoundFallback is a function called when given issuer is not found in the list of trusted ones.
	// For example, it could be analyzed, fetched from the external source
	// and then added to the list by calling AddTrustedIssuerURL method.
	TrustedIssuerNotFoundFallback TrustedIssNotFoundFallback

	// LoggerProvider is a function that provides a logger for the Parser.
	LoggerProvider func(ctx context.Context) log.FieldLogger

	// ClaimsTemplate is a template for claims object.
	// It usually used for the custom claims object that implements Claims interface.
	// If it's not specified, DefaultClaims will be used.
	ClaimsTemplate Claims

	// ScopeFilter is a filter that will be applied to access policies in JWT scope after parsing.
	// If it's set, then only access policies in scope that match at least one of the filtering policies will be returned.
	// It's useful when the CachingParser is used, and we want to store only some of the access policies in the cache to reduce memory usage.
	ScopeFilter ScopeFilter
}

ParserOpts additional options for parser.

type Scope

type Scope []AccessPolicy

Scope is a slice of access policies.

type ScopeFilter

type ScopeFilter []ScopeFilterAccessPolicy

ScopeFilter is a slice of access policy filters.

type ScopeFilterAccessPolicy

type ScopeFilterAccessPolicy struct {
	ResourceNamespace string
}

ScopeFilterAccessPolicy is a struct that represents a single access policy filter.

type SignAlgUnknownError

type SignAlgUnknownError struct {
	Alg string
}

SignAlgUnknownError represents an error when JWT signing algorithm is unknown.

func (*SignAlgUnknownError) Error

func (e *SignAlgUnknownError) Error() string

type TrustedIssNotFoundFallback

type TrustedIssNotFoundFallback func(ctx context.Context, p *Parser, iss string) (issURL string, issFound bool)

TrustedIssNotFoundFallback is a function called when given issuer is not found in the list of trusted ones. For example, it could be analyzed and then added to the list by calling AddTrustedIssuerURL method.