handlers

README

Handlers

This package contains handlers to manage header and cookie values, and identity validation.

Context values middleware

===================

CheckHeader and CheckCookie handlers forward values coming from a request header or a cookie, to a request context.

The mapping is done using enumeration of possible keys, and their mappings to header, context or cookie keys.

Usage

• Read a header from a request and add its value to the underlying request context:

    // Access token
    handler := handlers.CheckHeader(handlers.UserAccess)

    // Locale
    handler := handlers.CheckHeader(handlers.Locale)

    // CollectionID
    handler := handlers.CheckHeader(handlers.CollectionID)

• Read a cookie and add its value to the output request context:

    // Access token
    handler := handlers.CheckCookie(handlers.UserAccess)

    // Locale
    handler := handlers.CheckCookie(handlers.Locale)

    // CollectionID
    handler := handlers.CheckCookie(handlers.CollectionID)

• Access the context value:

    // Access token
    accessToken := ctx.Value(handlers.UserAccess.Context())

    // Locale
    locale := ctx.Value(handlers.Locale.Context())

    // CollectionID
    collectionID := ctx.Value(handlers.CollectionID.Context())

Identity middleware

===================

Middleware component that authenticates requests against zebedee.

The identity and permissions returned from the identity endpoint are added to the request context.

Getting started

Initialise the identity middleware and add it into the HTTP handler chain using alice:

    router := mux.NewRouter()
    alice := alice.New(handlers.Identity(<zebedeeURL>)).Then(router)
    httpServer := server.New(config.BindAddr, alice)

Wrap authenticated endpoints using the handlers.CheckIdentity(handler) function to check that a request identity exists.

    router.Path("/jobs").Methods("POST").HandlerFunc(handlers.CheckIdentity(api.addJob))

Add required headers to outbound requests to other services

    import "github.com/ONSdigital/dp-net/request"

    request.AddServiceTokenHeader(req, api.AuthToken)
    request.AddUserHeader(req, "UserA")

or, put less portably:

    req.Header.Add("Authorization", api.AuthToken)
    req.Header.Add("User-Identity", "UserA")

But most of this should be done by dp-net/http and dp-api-clients-go/....

Testing

If you need to use the middleware component in unit tests you can call the constructor function that allows injection of the HTTP client

import (
    clientsidentity "github.com/ONSdigital/dp-api-clients-go/identity"
    dphttp "github.com/ONSdigital/dp-net/http"
    dphandlers "github.com/ONSdigital/dp-net/handlers"
)

httpClient := &dphttp.ClienterMock{
    DoFunc: func(ctx context.Context, req *http.Request) (*http.Response, error) {
        return &http.Response{
            StatusCode: http.StatusOK,
        }, nil
    },
}
// set last argument to secretKey if you want to support legacy headers
clientsidentity.NewAPIClient(httpClient, zebedeeURL, "")

identityHandler := dphandlers.IdentityWithHTTPClient(doAuth, httpClient)

Documentation

Index

• Variables
• func CheckCookie(key Key) func(http.Handler) http.Handler
• func CheckHeader(key Key) func(http.Handler) http.Handler
• func CheckIdentity(handle func(http.ResponseWriter, *http.Request)) http.HandlerFunc
• func ControllerHandler(controllerHandlerFunc ControllerHandlerFunc) http.HandlerFunc
• func DoCheckCookie(h http.Handler, key Key) http.Handler
• func DoCheckHeader(h http.Handler, key Key) http.Handler
• func GetFlorenceToken(ctx context.Context, req *http.Request) (string, error)
• func Identity(zebedeeURL string) func(http.Handler) http.Handler
• func IdentityWithHTTPClient(cli *clientsidentity.Client) func(http.Handler) http.Handler
• type ControllerHandlerFunc
• type Key
  • func (k Key) Context() request.ContextKey
  • func (k Key) Cookie() string
  • func (k Key) Header() string
• type KeyMap

Variables

var KeyMaps = map[Key]*KeyMap{
	UserAccess: {
		Header:  request.FlorenceHeaderKey,
		Cookie:  request.FlorenceCookieKey,
		Context: request.FlorenceIdentityKey,
	},
	Locale: {
		Header:  request.LocaleHeaderKey,
		Cookie:  request.LocaleCookieKey,
		Context: request.LocaleContextKey,
	},
	CollectionID: {
		Header:  request.CollectionIDHeaderKey,
		Cookie:  request.CollectionIDCookieKey,
		Context: request.CollectionIDContextKey,
	},
}

KeyMaps maps the possible values of Key enumeration to their Header, Cookie and Context correspnding keys

Functions

func CheckCookie

func CheckCookie(key Key) func(http.Handler) http.Handler

CheckCookie is a wrapper which adds a cookie value (if found) to the request context. This function complies with alice middleware Constructor type: func(http.Handler) -> (http.Handler))

func CheckHeader

func CheckHeader(key Key) func(http.Handler) http.Handler

CheckHeader is a wrapper which adds a value from the request header (if found) to the request context. This function complies with alice middleware Constructor type: func(http.Handler) -> (http.Handler)

func CheckIdentity

func CheckIdentity(handle func(http.ResponseWriter, *http.Request)) http.HandlerFunc

CheckIdentity wraps a HTTP handler function. It validates that the request context contains a Caller, snf only calls the provided HTTP handler if the Caller is available, else it returns an error code and drains the http body

func ControllerHandler

func ControllerHandler(controllerHandlerFunc ControllerHandlerFunc) http.HandlerFunc

ControllerHandler is a middleware handler that ensures all required logical arguments are being passed along and then returns a generic http.HandlerFunc

func DoCheckCookie

func DoCheckCookie(h http.Handler, key Key) http.Handler

DoCheckCookie returns a handler that performs the CheckCookie logic

func DoCheckHeader

func DoCheckHeader(h http.Handler, key Key) http.Handler

DoCheckHeader returns a handler that performs the CheckHeader logic

func GetFlorenceToken

func GetFlorenceToken(ctx context.Context, req *http.Request) (string, error)

func Identity

func Identity(zebedeeURL string) func(http.Handler) http.Handler

Identity is a handler that controls the authenticating of a request

func IdentityWithHTTPClient

func IdentityWithHTTPClient(cli *clientsidentity.Client) func(http.Handler) http.Handler

IdentityWithHTTPClient allows a handler to be created that uses the given identity client

Types

type ControllerHandlerFunc

type ControllerHandlerFunc func(w http.ResponseWriter, r *http.Request, lang, collectionID, accessToken string)

ControllerHandlerFunc is a function type that accepts arguments required for logical flow in handlers Implementation of function should set headers as needed

type Key

type Key int

Key - iota enum of possible sets of keys for middleware manipulation

const (
	UserAccess Key = iota
	Locale
	CollectionID
)

Possible values for sets of keys

func (Key) Context

func (k Key) Context() request.ContextKey

Context returns the context key

func (Key) Cookie

func (k Key) Cookie() string

Cookie returns the cookie key

func (Key) Header

func (k Key) Header() string

Header returns the header key

type KeyMap

type KeyMap struct {
	Header  string
	Cookie  string
	Context request.ContextKey
}

KeyMap represents a mapping between header keys, cookie keys and context keys for an equivalent value.