bearer

Documentation

Overview

Package bearer provides middleware and utilities for authenticating API operation calls with a Bearer Token.

Index

• func AddAuthenticationMiddleware(s *middleware.Stack, signer Signer, tokenProvider TokenProvider) error
• type AuthenticationMiddleware
  • func NewAuthenticationMiddleware(signer Signer, tokenProvider TokenProvider) *AuthenticationMiddleware
  • func (m *AuthenticationMiddleware) HandleFinalize(ctx context.Context, in middleware.FinalizeInput, ...) (out middleware.FinalizeOutput, metadata middleware.Metadata, err error)
  • func (m *AuthenticationMiddleware) ID() string
• type Message
• type SignHTTPSMessage
  • func NewSignHTTPSMessage() *SignHTTPSMessage
  • func (SignHTTPSMessage) SignWithBearerToken(ctx context.Context, token Token, message Message) (Message, error)
• type Signer
• type StaticTokenProvider
  • func (s StaticTokenProvider) RetrieveBearerToken(context.Context) (Token, error)
• type Token
  • func (t Token) Expired(now time.Time) bool
• type TokenCache
  • func NewTokenCache(provider TokenProvider, optFns ...func(*TokenCacheOptions)) *TokenCache
  • func (p *TokenCache) RetrieveBearerToken(ctx context.Context) (Token, error)
• type TokenCacheOptions
• type TokenProvider
• type TokenProviderFunc
  • func (fn TokenProviderFunc) RetrieveBearerToken(ctx context.Context) (Token, error)

Functions

func AddAuthenticationMiddleware

func AddAuthenticationMiddleware(s *middleware.Stack, signer Signer, tokenProvider TokenProvider) error

AddAuthenticationMiddleware helper adds the AuthenticationMiddleware to the middleware Stack in the Finalize step with the options provided.

Types

type AuthenticationMiddleware

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

AuthenticationMiddleware provides the Finalize middleware step for signing an request message with a bearer token.

func NewAuthenticationMiddleware

func NewAuthenticationMiddleware(signer Signer, tokenProvider TokenProvider) *AuthenticationMiddleware

NewAuthenticationMiddleware returns an initialized AuthenticationMiddleware.

func (*AuthenticationMiddleware) HandleFinalize

func (m *AuthenticationMiddleware) HandleFinalize(
	ctx context.Context, in middleware.FinalizeInput, next middleware.FinalizeHandler,
) (
	out middleware.FinalizeOutput, metadata middleware.Metadata, err error,
)

HandleFinalize implements the FinalizeMiddleware interface in order to update the request with bearer token authentication.

func (*AuthenticationMiddleware) ID

func (m *AuthenticationMiddleware) ID() string

ID returns the resolver identifier

type Message

type Message interface{}

Message is the middleware stack's request transport message value.

type SignHTTPSMessage

type SignHTTPSMessage struct{}

SignHTTPSMessage provides a bearer token authentication implementation that will sign the message with the provided bearer token.

Will fail if the message is not a smithy-go HTTP request or the request is not HTTPS.

func NewSignHTTPSMessage

func NewSignHTTPSMessage() *SignHTTPSMessage

NewSignHTTPSMessage returns an initialized signer for HTTP messages.

func (SignHTTPSMessage) SignWithBearerToken

func (SignHTTPSMessage) SignWithBearerToken(ctx context.Context, token Token, message Message) (Message, error)

SignWithBearerToken returns a copy of the HTTP request with the bearer token added via the "Authorization" header, per RFC 6750, https://datatracker.ietf.org/doc/html/rfc6750.

Returns an error if the request's URL scheme is not HTTPS, or the request message is not an smithy-go HTTP Request pointer type.

type Signer

type Signer interface {
	SignWithBearerToken(context.Context, Token, Message) (Message, error)
}

Signer provides an interface for implementations to decorate a request message with a bearer token. The signer is responsible for validating the message type is compatible with the signer.

type StaticTokenProvider

type StaticTokenProvider struct {
	Token Token
}

StaticTokenProvider provides a utility for wrapping a static bearer token value within an implementation of a token provider.

func (StaticTokenProvider) RetrieveBearerToken

func (s StaticTokenProvider) RetrieveBearerToken(context.Context) (Token, error)

RetrieveBearerToken returns the static token specified.

type Token

type Token struct {
	Value string

	CanExpire bool
	Expires   time.Time
}

Token provides a type wrapping a bearer token and expiration metadata.

func (Token) Expired

func (t Token) Expired(now time.Time) bool

Expired returns if the token's Expires time is before or equal to the time provided. If CanExpires is false, Expired will always return false.

type TokenCache

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

TokenCache provides an utility to cache Bearer Authentication tokens from a wrapped TokenProvider. The TokenCache can be has options to configure the cache's early and asynchronous refresh of the token.

func NewTokenCache

func NewTokenCache(provider TokenProvider, optFns ...func(*TokenCacheOptions)) *TokenCache

NewTokenCache returns a initialized TokenCache that implements the TokenProvider interface. Wrapping the provider passed in. Also taking a set of optional functional option parameters to configure the token cache.

func (*TokenCache) RetrieveBearerToken

func (p *TokenCache) RetrieveBearerToken(ctx context.Context) (Token, error)

RetrieveBearerToken returns the token if it could be obtained, or error if a valid token could not be retrieved.

The passed in Context's cancel/deadline/timeout will impacting only this individual retrieve call and not any other already queued up calls. This means underlying provider's RetrieveBearerToken calls could block for ever, and not be canceled with the Context. Set RetrieveBearerTokenTimeout to provide a timeout, preventing the underlying TokenProvider blocking forever.

By default, if the passed in Context is canceled, all of its values will be considered expired. The wrapped TokenProvider will not be able to lookup the values from the Context once it is expired. This is done to protect against expired values no longer being valid. To disable this behavior, use smithy-go's context.WithPreserveExpiredValues to add a value to the Context before calling RetrieveBearerToken to enable support for expired values.

Without RetrieveBearerTokenTimeout there is the potential for a underlying Provider's RetrieveBearerToken call to sit forever. Blocking in subsequent attempts at refreshing the token.

type TokenCacheOptions

type TokenCacheOptions struct {
	// The duration before the token will expire when the credentials will be
	// refreshed. If DisableAsyncRefresh is true, the RetrieveBearerToken calls
	// will be blocking.
	//
	// Asynchronous refreshes are deduplicated, and only one will be in-flight
	// at a time. If the token expires while an asynchronous refresh is in
	// flight, the next call to RetrieveBearerToken will block on that refresh
	// to return.
	RefreshBeforeExpires time.Duration

	// The timeout the underlying TokenProvider's RetrieveBearerToken call must
	// return within, or will be canceled. Defaults to 0, no timeout.
	//
	// If 0 timeout, its possible for the underlying tokenProvider's
	// RetrieveBearerToken call to block forever. Preventing subsequent
	// TokenCache attempts to refresh the token.
	//
	// If this timeout is reached all pending deduplicated calls to
	// TokenCache RetrieveBearerToken will fail with an error.
	RetrieveBearerTokenTimeout time.Duration

	// The minimum duration between asynchronous refresh attempts. If the next
	// asynchronous recent refresh attempt was within the minimum delay
	// duration, the call to retrieve will return the current cached token, if
	// not expired.
	//
	// The asynchronous retrieve is deduplicated across multiple calls when
	// RetrieveBearerToken is called. The asynchronous retrieve is not a
	// periodic task. It is only performed when the token has not yet expired,
	// and the current item is within the RefreshBeforeExpires window, and the
	// TokenCache's RetrieveBearerToken method is called.
	//
	// If 0, (default) there will be no minimum delay between asynchronous
	// refresh attempts.
	//
	// If DisableAsyncRefresh is true, this option is ignored.
	AsyncRefreshMinimumDelay time.Duration

	// Sets if the TokenCache will attempt to refresh the token in the
	// background asynchronously instead of blocking for credentials to be
	// refreshed. If disabled token refresh will be blocking.
	//
	// The first call to RetrieveBearerToken will always be blocking, because
	// there is no cached token.
	DisableAsyncRefresh bool
}

TokenCacheOptions provides a set of optional configuration options for the TokenCache TokenProvider.

type TokenProvider

type TokenProvider interface {
	RetrieveBearerToken(context.Context) (Token, error)
}

TokenProvider provides interface for retrieving bearer tokens.

type TokenProviderFunc

type TokenProviderFunc func(context.Context) (Token, error)

TokenProviderFunc provides a helper utility to wrap a function as a type that implements the TokenProvider interface.

func (TokenProviderFunc) RetrieveBearerToken

func (fn TokenProviderFunc) RetrieveBearerToken(ctx context.Context) (Token, error)

RetrieveBearerToken calls the wrapped function, returning the Token or error.