Documentation
¶
Overview ¶
Package jwt provides primitives for working with JWT (Parser, Claims, and so on).
Index ¶
- Constants
- type AccessPolicy
- type AudienceMissingError
- type AudienceNotExpectedError
- type CachingKeysProvider
- type CachingParser
- type CachingParserOpts
- type Claims
- type ClaimsCache
- type DefaultClaims
- type IssuerMissingError
- type IssuerUntrustedError
- type KeysProvider
- type Parser
- type ParserOpts
- type Scope
- type ScopeFilter
- type ScopeFilterAccessPolicy
- type SignAlgUnknownError
- type TrustedIssNotFoundFallback
Constants ¶
const DefaultClaimsCacheMaxEntries = 1000
Variables ¶
This section is empty.
Functions ¶
This section is empty.
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 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.
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 ¶ added in v0.10.0
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 ¶ added in v0.10.0
func (c *DefaultClaims) ApplyScopeFilter(filter ScopeFilter)
ApplyScopeFilter filters (in-place) the scope of the DefaultClaims by the specified filter.
func (*DefaultClaims) Clone ¶ added in v0.10.0
func (c *DefaultClaims) Clone() Claims
Clone returns a deep copy of the DefaultClaims.
func (*DefaultClaims) GetID ¶ added in v0.11.0
func (c *DefaultClaims) GetID() string
GetID returns the JTI field of the DefaultClaims.
func (*DefaultClaims) GetScope ¶ added in v0.10.0
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 ¶
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 ¶
AddTrustedIssuer adds trusted issuer with specified name and URL.
func (*Parser) AddTrustedIssuerURL ¶
AddTrustedIssuerURL adds trusted issuer URL.
func (*Parser) GetURLForIssuer ¶
GetURLForIssuer returns URL for issuer if it is trusted.
type ParserOpts ¶
type ParserOpts struct {
// SkipClaimsValidation is a flag that indicates whether claims validation (e.g. checking expiration time) should be skipped.
// It doesn't affect signature verification.
SkipClaimsValidation bool
// RequireAudience is a flag that indicates whether audience should be required.
RequireAudience bool
// ExpectedAudience is a list of expected audience patterns.
// If it's set, then only tokens with audience that matches at least one of the patterns will be accepted.
ExpectedAudience []string
// TrustedIssuerNotFoundFallback is a function called when given issuer is not found in the list of trusted ones.
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 that will be used for unmarshalling JWT.
// By default, DefaultClaims is 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 ScopeFilter ¶ added in v0.10.0
type ScopeFilter []ScopeFilterAccessPolicy
ScopeFilter is a slice of access policy filters.
type ScopeFilterAccessPolicy ¶ added in v0.10.0
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.