options

Documentation

Index

• type ClaimsContextKeyName
• type ErrorDescription
• type ErrorHandler
• type ErrorsContextKeyName
• type Option
  • func IsPermissive() Option
  • func WithAllowedTokenDrift(opt time.Duration) Option
  • func WithClaimsContextKeyName(opt string) Option
  • func WithDisableKeyID(opt bool) Option
  • func WithDiscoveryUri(opt string) Option
  • func WithErrorHandler(opt ErrorHandler) Option
  • func WithErrorsContextKeyName(opt string) Option
  • func WithFallbackSignatureAlgorithm(opt string) Option
  • func WithHttpClient(opt *http.Client) Option
  • func WithIssuer(opt string) Option
  • func WithJwksFetchTimeout(opt time.Duration) Option
  • func WithJwksRateLimit(opt uint) Option
  • func WithJwksUri(opt string) Option
  • func WithLazyLoadJwks(opt bool) Option
  • func WithRequiredAudience(opt string) Option
  • func WithRequiredClaims(opt map[string]interface{}) Option
  • func WithRequiredTokenType(opt string) Option
  • func WithTokenString(setters ...TokenStringOption) Option
• type Options
  • func New(setters ...Option) *Options
• type TokenStringOption
  • func WithTokenStringHeaderName(opt string) TokenStringOption
  • func WithTokenStringListSeparator(opt string) TokenStringOption
  • func WithTokenStringPostExtractionFn(opt func(string) (string, error)) TokenStringOption
  • func WithTokenStringTokenPrefix(opt string) TokenStringOption
• type TokenStringOptions
  • func NewTokenString(setters ...TokenStringOption) *TokenStringOptions

Types

type ClaimsContextKeyName

type ClaimsContextKeyName string

ClaimsContextKeyName is the type for they key value used to pass claims using request context. Using separate type because of the following: https://staticcheck.io/docs/checks#SA1029

const DefaultClaimsContextKeyName ClaimsContextKeyName = "claims"

DefaultClaimsContextKeyName is of type ClaimsContextKeyName and defaults to "claims"

type ErrorDescription

type ErrorDescription string

ErrorDescription is used to pass the description of the error to ErrorHandler

const (
	// GetTokenErrorDescription is returned to ErrorHandler if the middleware is unable to get a token from the request
	GetTokenErrorDescription ErrorDescription = "unable to get token string"
	// ParseTokenErrorDescription is returned to ErrorHandler if the middleware is unable to parse the token extracted from the request
	ParseTokenErrorDescription ErrorDescription = "unable to parse token string"
	// ConvertTokenErrorDescription is returned to ErrorHandler if the middleware is unable to convert the token to a map
	ConvertTokenErrorDescription ErrorDescription = "unable to convert token to map"
)

type ErrorHandler

type ErrorHandler func(description ErrorDescription, err error)

ErrorHandler is called by the middleware if not nil

type ErrorsContextKeyName

type ErrorsContextKeyName string

ErrosContextKeyName holds the key to pass errors under.

const DefaultErrorsContextKeyName ErrorsContextKeyName = "oidcerrors"

DefaultErrorsContextKeyName is of type ErrorsContextKeyName and defaults to "oidcerrors"

type Option

type Option func(*Options)

Option returns a function that modifies an Options pointer.

func IsPermissive

func IsPermissive() Option

IsPermissive allows incoming requests to pass even if the client does not provide a token.

func WithAllowedTokenDrift

func WithAllowedTokenDrift(opt time.Duration) Option

WithAllowedTokenDrift sets the AllowedTokenDrift parameter for an Options pointer. AllowedTokenDrift adds the duration to the token expiration to allow for time drift between parties. Defaults to 10 seconds

func WithClaimsContextKeyName

func WithClaimsContextKeyName(opt string) Option

WithClaimsContextKeyName sets the ClaimsContextKeyName parameter for an Options pointer. ClaimsContextKeyName is the name of key that will be used to pass claims using request context. Not supported by Echo JWT and will be ignored if used by it.

Important note: If you change this using `options.WithClaimsContextKeyName("foo")`, then you also need to use it like this: `claims, ok := r.Context().Value(options.ClaimsContextKeyName("foo")).(map[string]interface{})`

Default: `options.DefaultClaimsContextKeyName` Used like this: “claims, ok := r.Context().Value(options.DefaultClaimsContextKeyName).(map[string]interface{})“

When used with gin, it is converted to normal string - by default: `claimsValue, found := c.Get("claims")`

func WithDisableKeyID

func WithDisableKeyID(opt bool) Option

WithDisableKeyID sets the DisableKeyID parameter for an Options pointer. DisableKeyID adjusts if a KeyID needs to be extracted from the token or not Defaults to false and means KeyID is required to be present in both the jwks and token The OIDC specification doesn't require KeyID if there's only one key in the jwks: https://openid.net/specs/openid-connect-core-1_0.html#Signing

This also means that if enabled, refresh of the jwks will be done if the token can't be validated due to invalid key. The JWKS fetch will fail if there's more than one key present.

func WithDiscoveryUri

func WithDiscoveryUri(opt string) Option

WithDiscoveryUri sets the Issuer parameter for an Options pointer. DiscoveryUri is where the `jwks_uri` will be grabbed Defaults to `fmt.Sprintf("%s/.well-known/openid-configuration", strings.TrimSuffix(issuer, "/"))`

func WithErrorHandler

func WithErrorHandler(opt ErrorHandler) Option

WithErrorHandler sets the ErrorHandler parameter for an Options pointer. You can pass a function to run custom logic on errors, logging as an example. Defaults to nil

func WithErrorsContextKeyName

func WithErrorsContextKeyName(opt string) Option

WithErrorsContextKeyName sets the ErrorsContextKeyName parameter for an Options pointer. ErrorsContextKeyName is the name of the key that will be used to pass errors using the request context.

func WithFallbackSignatureAlgorithm

func WithFallbackSignatureAlgorithm(opt string) Option

WithFallbackSignatureAlgorithm sets the FallbackSignatureAlgorithm parameter for an Options pointer. FallbackSignatureAlgorithm needs to be used when the jwks doesn't contain the alg key. If not specified and jwks doesn't contain alg key, will default to: - RS256 for key type (kty) RSA - ES256 for key type (kty) EC

When specified and jwks contains alg key, alg key from jwks will be used.

Example values (one of them): RS256 RS384 RS512 ES256 ES384 ES512

func WithHttpClient

func WithHttpClient(opt *http.Client) Option

WithHttpClient sets the HttpClient parameter for an Options pointer. HttpClient takes a *http.Client for external calls Defaults to http.DefaultClient

func WithIssuer

func WithIssuer(opt string) Option

WithIssuer sets the Issuer parameter for Options. Issuer is the authority that issues the tokens

func WithJwksFetchTimeout

func WithJwksFetchTimeout(opt time.Duration) Option

WithJwksFetchTimeout sets the JwksFetchTimeout parameter for an Options pointer. JwksFetchTimeout sets the context timeout when downloading the jwks Defaults to 5 seconds

func WithJwksRateLimit

func WithJwksRateLimit(opt uint) Option

WithJwksRateLimit sets the JwksFetchTimeout parameter for an Options pointer. JwksRateLimit takes an uint and makes sure that the jwks will at a maximum be requested these many times per second. Defaults to 1 (Request Per Second) Please observe: Requests that force update of jwks (like wrong keyID) will be rate limited

func WithJwksUri

func WithJwksUri(opt string) Option

WithJwksUri sets the JwksUri parameter for an Options pointer. JwksUri is used to download the public key(s) Defaults to the `jwks_uri` from the response of DiscoveryUri

func WithLazyLoadJwks

func WithLazyLoadJwks(opt bool) Option

WithLazyLoadJwks sets the LazyLoadJwks parameter for an Options pointer. LazyLoadJwks makes it possible to use OIDC Discovery without being able to load the keys at startup. Default setting is disabled. Please observe: If enabled, it will always load even though settings may be wrong / not working.

func WithRequiredAudience

func WithRequiredAudience(opt string) Option

WithRequiredAudience sets the RequiredAudience parameter for an Options pointer. RequiredAudience is used to require a specific Audience `aud` in the claims. Defaults to empty string `""` and means all audiences are allowed.

func WithRequiredClaims

func WithRequiredClaims(opt map[string]interface{}) Option

WithRequiredClaims sets the RequiredClaims parameter for an Options pointer. RequiredClaims is used to require specific claims in the token Defaults to empty map (nil) and won't check for anything else Works with primitive types, slices and maps. Please observe: slices and strings checks that the token contains it, but more is allowed. Required claim []string{"bar"} matches token []string{"foo", "bar", "baz"} Required claim map[string]string{{"foo": "bar"}} matches token map[string]string{{"a": "b"},{"foo": "bar"},{"c": "d"}}

Example:

```go

map[string]interface{}{
	"foo": "bar",
	"bar": 1337,
	"baz": []string{"bar"},
	"oof": []map[string]string{
		{"bar": "baz"},
	},
},

```

func WithRequiredTokenType

func WithRequiredTokenType(opt string) Option

WithRequiredTokenType sets the RequiredTokenType parameter for an Options pointer. RequiredTokenType is used if only specific tokens should be allowed. Default is empty string `""` and means all token types are allowed. Use case could be to configure this if the TokenType (set in the header of the JWT) should be `JWT` or maybe even `JWT+AT` to differentiate between access tokens and id tokens. Not all providers support or use this.

func WithTokenString

func WithTokenString(setters ...TokenStringOption) Option

WithTokenString sets the TokenString parameter for an Options pointer. TokenString makes it possible to configure how the JWT token should be extracted from an http header. Not supported by Echo JWT and will be ignored if used by it. Defaults to: 'Authorization: Bearer JWT'

type Options

type Options struct {
	Issuer                     string
	DiscoveryUri               string
	JwksUri                    string
	JwksFetchTimeout           time.Duration
	JwksRateLimit              uint
	FallbackSignatureAlgorithm string
	AllowedTokenDrift          time.Duration
	LazyLoadJwks               bool
	RequiredTokenType          string
	RequiredAudience           string
	RequiredClaims             map[string]interface{}
	DisableKeyID               bool
	HttpClient                 *http.Client
	TokenString                [][]TokenStringOption
	ClaimsContextKeyName       ClaimsContextKeyName
	ErrorHandler               ErrorHandler
	Permissive                 bool
	ErrorsContextKeyName       ErrorsContextKeyName
}

Options defines the options for OIDC Middleware.

func New

func New(setters ...Option) *Options

New takes Option setters and returns an Options pointer. Mainly used by the internal functions and most likely not needed by any external application using this library.

type TokenStringOption

type TokenStringOption func(*TokenStringOptions)

TokenStringOption returns a function that modifies a TokenStringOptions pointer.

func WithTokenStringHeaderName

func WithTokenStringHeaderName(opt string) TokenStringOption

WithTokenStringHeaderName sets the HeaderName parameter for a TokenStringOptions pointer. HeaderName is the name of the header. Default: "Authorization"

func WithTokenStringListSeparator

func WithTokenStringListSeparator(opt string) TokenStringOption

WithTokenStringListSeparator sets the ListSeparator parameter for a TokenStringOptions pointer. ListSeparator defines if the value of the header is a list or not. The value will be split (up to 20 slices) by the ListSeparator. Default disabled: ""

func WithTokenStringPostExtractionFn

func WithTokenStringPostExtractionFn(opt func(string) (string, error)) TokenStringOption

WithTokenStringPostExtractionFn sets the PostExtractionFn parameter for a TokenStringOptions pointer. PostExtractionFn will be run if not nil after a token has been successfully extracted. Default: nil

func WithTokenStringTokenPrefix

func WithTokenStringTokenPrefix(opt string) TokenStringOption

WithTokenStringTokenPrefix sets the TokenPrefix parameter for a TokenStringOptions pointer. TokenPrefix defines the prefix that should be trimmed from the header value to extract the token. Default: "Bearer "

type TokenStringOptions

type TokenStringOptions struct {
	HeaderName       string
	TokenPrefix      string
	ListSeparator    string
	PostExtractionFn func(string) (string, error)
}

TokenStringOptions handles the settings for how to extract the token from a request.

func NewTokenString

func NewTokenString(setters ...TokenStringOption) *TokenStringOptions

NewTokenString takes TokenStringOption setters and returns a TokenStringOptions pointer. Mainly used by the internal functions and most likely not needed by any external application using this library.