authentication

Documentation

Index

• func BearerFromContext(ctx context.Context) (result string, err error)
• func ContextWithToken(parent context.Context, token *jwt.Token) context.Context
• func TokenFromContext(ctx context.Context) (result *jwt.Token, err error)
• type Handler
  • func (h *Handler) ServeHTTP(w http.ResponseWriter, r *http.Request)
• type HandlerBuilder
  • func NewHandler() *HandlerBuilder
  • func (b *HandlerBuilder) ACLFile(value string) *HandlerBuilder
  • func (b *HandlerBuilder) Build() (handler *Handler, err error)
  • func (b *HandlerBuilder) Error(value string) *HandlerBuilder
  • func (b *HandlerBuilder) KeysCAs(value *x509.CertPool) *HandlerBuilder
  • func (b *HandlerBuilder) KeysFile(value string) *HandlerBuilder
  • func (b *HandlerBuilder) KeysInsecure(value bool) *HandlerBuilder
  • func (b *HandlerBuilder) KeysURL(value string) *HandlerBuilder
  • func (b *HandlerBuilder) Logger(value logging.Logger) *HandlerBuilder
  • func (b *HandlerBuilder) Next(value http.Handler) *HandlerBuilder
  • func (b *HandlerBuilder) OperationID(value func(r *http.Request) string) *HandlerBuilder
  • func (b *HandlerBuilder) Public(value string) *HandlerBuilder
  • func (b *HandlerBuilder) Service(value string) *HandlerBuilder

Functions

func BearerFromContext

func BearerFromContext(ctx context.Context) (result string, err error)

BearerFromContext extracts the bearer token of the user from the context. If no user is found in the context then the result will be the empty string.

func ContextWithToken

func ContextWithToken(parent context.Context, token *jwt.Token) context.Context

ContextWithToken creates a new context containing the given token.

func TokenFromContext

func TokenFromContext(ctx context.Context) (result *jwt.Token, err error)

TokenFromContext extracts the JSON web token of the user from the context. If no token is found in the context then the result will be nil.

Types

type Handler

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

Handler is an HTTP handler that checks authentication using the JWT tokens from the authorization header.

func (*Handler) ServeHTTP

func (h *Handler) ServeHTTP(w http.ResponseWriter, r *http.Request)

ServeHTTP is the implementation of the HTTP handler interface.

type HandlerBuilder

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

HandlerBuilder contains the data and logic needed to create a new authentication handler. Don't create objects of this type directly, use the NewHandler function instead.

func NewHandler

func NewHandler() *HandlerBuilder

NewHandler creates a builder that can then be configured and used to create authentication handlers.

func (*HandlerBuilder) ACLFile

func (b *HandlerBuilder) ACLFile(value string) *HandlerBuilder

ACLFile sets a file that contains items of the access control list. This should be a YAML file with the following format:

• claim: email pattern: ^.*@redhat\.com$

• claim: sub pattern: ^f:b3f7b485-7184-43c8-8169-37bd6d1fe4aa:myuser$

The claim field is the name of the claim of the JWT token that will be checked. The pattern field is a regular expression. If the claim matches the regular expression then access will be allowed.

If the ACL is empty then access will be allowed to all JWT tokens.

If the ACL has at least one item then access will be allowed only to tokens that match at least one of the items.

func (*HandlerBuilder) Build

func (b *HandlerBuilder) Build() (handler *Handler, err error)

Build uses the data stored in the builder to create a new authentication handler.

func (*HandlerBuilder) Error

func (b *HandlerBuilder) Error(value string) *HandlerBuilder

Error sets the error identifier that will be used to generate JSON error responses. For example, if the value is `123` then the JSON for error responses will be like this:

{
	"kind": "Error",
	"id": "11",
	"href": "/api/clusters_mgmt/v1/errors/11",
	"code": "CLUSTERS-MGMT-11",
	"reason": "Bearer token is expired"
}

When this isn't explicitly provided the value will be `401`. Note that changing this doesn't change the HTTP response status, that will always be 401.

func (*HandlerBuilder) KeysCAs

func (b *HandlerBuilder) KeysCAs(value *x509.CertPool) *HandlerBuilder

KeysCAs sets the certificate authorities that will be trusted when verifying the certificate of the web server where keys are loaded from.

func (*HandlerBuilder) KeysFile

func (b *HandlerBuilder) KeysFile(value string) *HandlerBuilder

KeysFile sets the location of a file containing a JSON web key set that will be used to verify the signatures of the tokens. The keys from this file will be loaded when a token is received containing an unknown key identifier.

At least one keys file or one keys URL is mandatory.

func (*HandlerBuilder) KeysInsecure

func (b *HandlerBuilder) KeysInsecure(value bool) *HandlerBuilder

KeysInsecure sets the flag that indicates that the certificate of the web server where the keys are loaded from should not be checked. The default is false and changing it to true makes the token verification insecure, so refrain from doing that in security sensitive environments.

func (*HandlerBuilder) KeysURL

func (b *HandlerBuilder) KeysURL(value string) *HandlerBuilder

KeysURL sets the URL containing a JSON web key set that will be used to verify the signatures of the tokens. The keys from these URLs will be loaded when a token is received containing an unknown key identifier.

At least one keys file or one keys URL is mandatory.

func (*HandlerBuilder) Logger

func (b *HandlerBuilder) Logger(value logging.Logger) *HandlerBuilder

Logger sets the logger that the middleware will use to send messages to the log. This is mandatory.

func (*HandlerBuilder) Next

func (b *HandlerBuilder) Next(value http.Handler) *HandlerBuilder

Next sets the HTTP handler that will be called when the authentication handler has authenticated correctly the request. This is mandatory.

func (*HandlerBuilder) OperationID

func (b *HandlerBuilder) OperationID(value func(r *http.Request) string) *HandlerBuilder

OperationID sets a function that will be called each time an error is detected, passing the details of the request that caused the error. The value returned by the function will be included in the `operation_id` field of the JSON error response. For example, if the function returns `123` the generated JSON error response will be like this:

{
	"kind": "Error",
	"id": "401",
	"href": "/api/clusters_mgmt/v1/errors/401",
	"code": "CLUSTERS-MGMT-401",
	"reason": "Bearer token is expired".
	"operation_id": "123"
}

For example, if the operation identifier is available in an HTTP header named `X-Operation-ID` then the handler can be configured like this to use it:

handler, err := authentication.NewHandler().
	Logger(logger).
	KeysURL("https://...").
	OperationID(func(r *http.Request) string {
		return r.Header.Get("X-Operation-ID")
	}).
	Next(next).
	Build()
if err != nil {
	...
}

If the function returns an empty string then the `operation_id` field will not be added.

By default there is no function configured for this, so no `operation_id` field will be added.

func (*HandlerBuilder) Public

func (b *HandlerBuilder) Public(value string) *HandlerBuilder

Public sets a regular expression that defines the parts of the URL space that considered public, and therefore require no authentication. This method may be called multiple times and then all the given regular expressions will be used to check what parts of the URL space are public.

func (*HandlerBuilder) Service

func (b *HandlerBuilder) Service(value string) *HandlerBuilder

Service sets the identifier of the service that will be used to generate error codes. For example, if the value is `my_service` then the JSON for error responses will be like this:

{
	"kind": "Error",
	"id": "401",
	"href": "/api/clusters_mgmt/v1/errors/401",
	"code": "MY-SERVICE-401",
	"reason": "Bearer token is expired"
}

When this isn't explicitly provided the value will be extracted from the second segment of the request path. For example, if the request URL is `/api/clusters_mgmt/v1/cluster` the value will be `clusters_mgmt`.