auth

Documentation

Overview

Package auth contains http middleware implementations handling the HTTP authorization. All middlewares only parse the provided authorization credentials and update the request's Context. See RFC 7235 for details on HTTP based authorization. (https://datatracker.ietf.org/doc/html/rfc7235)

Example

package main

import (
	"net/http"

	"github.com/halimath/httputils"
	"github.com/halimath/httputils/auth"
)

func main() {
	// h is a http.Handler, that actually handles the request.
	h := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		w.Header().Set("Content-Type", "text/plain")

		// We can assume here that auth is always set. See below
		a := auth.GetAuthorization(r.Context())

		switch a.(type) {
		case *auth.UsernamePassword:
			// Use username/password to authorize the usert
		case *auth.BearerToken:
			// Decode token and authorizes
		}
	})

	authMW := httputils.Compose(
		auth.Authorized(
			auth.AuthenticationChallenge{
				Scheme: auth.AuthorizationSchemeBasic,
				Realm:  "test",
			},
			auth.AuthenticationChallenge{
				Scheme: auth.AuthorizationSchemeBearer,
				Realm:  "test",
			},
		),
		auth.Bearer(),
		auth.Basic(),
	)

	http.ListenAndServe(":1234", authMW(h))
}

Example (Custom)

package main

import (
	"encoding/base64"
	"net/http"
	"strings"

	"github.com/halimath/httputils"
	"github.com/halimath/httputils/auth"
)

func main() {
	type HMAC struct {
		Username string
		MAC      []byte
	}

	h := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		// ...
	})

	authMW := httputils.Compose(
		auth.AuthHandler(
			"Hmac",
			func(credentials string) auth.Authorization {
				parts := strings.Split(credentials, ":")
				if len(parts) != 2 {
					return nil
				}

				mac, err := base64.StdEncoding.DecodeString(parts[1])
				if err != nil {
					return nil
				}

				return &HMAC{
					Username: parts[0],
					MAC:      mac,
				}
			},
		),
		auth.Authorized(
			auth.AuthenticationChallenge{
				Scheme: auth.AuthorizationSchemeBasic,
				Realm:  "test",
			},
			auth.AuthenticationChallenge{
				Scheme: auth.AuthorizationSchemeBearer,
				Realm:  "test",
			},
		),
	)

	http.ListenAndServe(":1234", authMW(h))
}

Index

• Constants
• func AuthHandler(scheme string, ab AuthorizationBuilder) httputils.Middleware
• func Authorized(challenge AuthenticationChallenge, moreChallenges ...AuthenticationChallenge) httputils.Middleware
• func Basic() httputils.Middleware
• func Bearer() httputils.Middleware
• func WithAuthorization(ctx context.Context, auth Authorization) context.Context
• type AuthenticationChallenge
• type Authorization
  • func GetAuthorization(ctx context.Context) Authorization
• type AuthorizationBuilder
• type BearerToken
• type UsernamePassword

Examples

• Package
• Package (Custom)

Constants

const (
	// HeaderAuthorization contains the name of the HTTP Authorization header as specified in RFC 7235, section 4.2
	// (https://datatracker.ietf.org/doc/html/rfc7235#section-4.2)
	HeaderAuthorization = "Authorization"

	// AuthorizationSchemeBasic contains the authorization scheme used with basic authentication as specified in
	// RFC 7617, section 2
	// (https://datatracker.ietf.org/doc/html/rfc7617#section-2)
	AuthorizationSchemeBasic = "Basic"

	// AuthorizationSchemeBearer contains the authorization scheme used with token bearer authorization as specified
	// in RFC 6750, section 2.1
	// (https://datatracker.ietf.org/doc/html/rfc6750#section-2.1)
	AuthorizationSchemeBearer = "Bearer"

	// HeaderWWWAuthenticate contains the name of the WWW-Authenticate response header as specified in RFC 7235, section 4.1
	// (https://datatracker.ietf.org/doc/html/rfc7235#section-4.1)
	HeaderWWWAuthenticate = "WWW-Authenticate"
)

Functions

func AuthHandler

func AuthHandler(scheme string, ab AuthorizationBuilder) httputils.Middleware

AuthHandler creates a http middleware that accepts Authoriation request headers using the authorization scheme. It forwards the credentials given after scheme to ab in order to build an Authorization object.

func Authorized

func Authorized(challenge AuthenticationChallenge, moreChallenges ...AuthenticationChallenge) httputils.Middleware

Authorized creates a http middleware that checks if the request carries an Authorization (using GetAuthorization). If no authorization is found, the request is rejected with a HTTP status 401 (Unauthorized). The response contains a WWW-Authenticate header with the given challenges.

func Basic

func Basic() httputils.Middleware

Basic creates a http middleware which extracts basic autorization credentials as specified in RFC 7617 and stores them in the request's context. Use GetAuthorization to extract the authorization. (https://datatracker.ietf.org/doc/html/rfc7617)

func Bearer

func Bearer() httputils.Middleware

Bearer creates a http middleware wrapping h that performs token bearer authorization as specified in RFC 6750, section 2.1. Note that only header based authorization is implemented. (https://datatracker.ietf.org/doc/html/rfc6750#section-2.1)

func WithAuthorization

func WithAuthorization(ctx context.Context, auth Authorization) context.Context

WithAuthorization extends ctx with auth stored under a private key.

Types

type AuthenticationChallenge

type AuthenticationChallenge struct {
	Scheme    string
	Realm     string
	UserProps map[string]string
}

AuthenticationChallenge implements a single authentication challenge returned with a HTTP status 401.

type Authorization

type Authorization interface{}

Authorization is a tagging interface implemented by all types of authentication Authorization.

func GetAuthorization

func GetAuthorization(ctx context.Context) Authorization

GetAuthorization returns the Authorization stored in ctx or nil if no authorization are stored in ctx.

type AuthorizationBuilder

type AuthorizationBuilder func(credentials string) Authorization

AuthorizationBuilder builds an Authorization value from the given credentials string.

type BearerToken

type BearerToken struct {
	Token string
}

BearerToken implements Authorization capturing a bearer token as specified in RFC 6750. (https://datatracker.ietf.org/doc/html/rfc6750)

type UsernamePassword

type UsernamePassword struct {
	Username string
	Password string
}

UsernamePassword implements an Authorization capturing Authorization provided via HTTP BasicAuth Auth. See RFC 7617. (https://datatracker.ietf.org/doc/html/rfc7617)