oauth2

Documentation

Overview

Package oauth2 provides a fully customizable OAuth 2.0 authorization service http.handler.

This package currently supports the implicit flow only. Other flows will be supported in the future. See RFC6749 for more details.

To use oauth2, create a handler and run an HTTP server:

package main

import (
	"log"
	"net/http"
	"net/url"

	"github.com/amsterdam/authz/oauth2"
)

func main() {
	bindAddress := ":8080"
	baseAddress, _ := url.Parse("http://localhost:8080/")
	handler, _ := oauth2.Handler(baseAddress)
	log.Fatal(http.ListenAndServe(bindAddress, handler))
}

This service creates JSON Web Token (JWS) access tokens signed using the HS256 (HMAC / SHA256) algorithm. To use these tokens in what RFC6749 calls resource servers you should distribute a shared secret, and verify the token's signature.

When you serve the authorization service bare, as in the above example, it won't be very useful:

$ go build
$ ./test
2017/09/26 16:05:59 WARN: accesstoken config missing, using random secret.
2017/09/26 16:05:59 WARN: Using in-memory state storage
2017/09/26 16:05:59 WARN: using empty scope set
2017/09/26 16:05:59 WARN: using empty client map
2017/09/26 16:05:59 WARN: no IdP registered

A minimally useful service provides implementations of:

* oauth2.ClientMap: a registry of clients that are known by the service; * oauth2.IdP: an identity provider, so users can authenticate; * oauth2.Authz: the scopes supported by the service;

... and configuration for the accesstokens: the shared secret, the token lifetime and the token issuer identifier.

If you run the service on more than a single node you may also want to use external state storage such as Redis. To do so, implement the oauth2.StateKeeper interface.

Index

• func Handler(baseURL string, jwks string, options ...Option) (http.Handler, error)
• type Authz
• type Client
• type ClientMap
• type IDP
• type Option
  • func AccessTokenIssuer(issuer string) Option
  • func AccessTokenLifetime(lifetime int64) Option
  • func AuthzProvider(p Authz) Option
  • func Clients(m ClientMap) Option
  • func IDProvider(i IDP) Option
  • func JWKID(kid string) Option
  • func StateStorage(engine StateKeeper, lifetime time.Duration) Option
  • func TraceHeader(headerName string) Option
• type ScopeSet
• type StateKeeper
• type User

Functions

func Handler

func Handler(baseURL string, jwks string, options ...Option) (http.Handler, error)

Handler returns an http.Handler that handles OAuth 2.0 requests.

Types

type Authz

type Authz interface {
	ScopeSet
	// ScopeSetFor() returns the given user's authorized scopeset.
	ScopeSetFor(u *User) (ScopeSet, error)
}

Authz contains an authorization provider's scopes and can map a user on scopes.

type Client

type Client struct {
	// Client identifier
	ID string
	// list of registered redirects
	Redirects []string
	// client secret
	Secret string
	// Allowed grants (implicit, authz code, client credentials)
	GrantType string
}

Client contains all data needed for OAuth 2.0 clients.

type ClientMap

type ClientMap interface {
	// Returns the client for this identifier or an error
	Get(id string) (*Client, error)
}

ClientMap defines OAuth 2.0 clients.

type IDP

type IDP interface {
	// ID returns the IDP's identifier
	ID() string
	// AuthnRedirect is responsible for generating a URL that we can redirect
	// the user to for authentication.
	AuthnRedirect(authzRef string) (*url.URL, error)
	// AuthnCallback receives the IDP's callback request. It returns the
	// authzRef as given to the corresponding call to AuthnRedirect, and the
	// logged-in User or nil if authentication failed.
	AuthnCallback(r *http.Request) (string, *User, error)
}

IDP defines an identity provider.

type Option

type Option func(*handler) error

Option is a handler setting that can be passed to Handler().

func AccessTokenIssuer

func AccessTokenIssuer(issuer string) Option

AccessTokenIssuer is an option that sets the iss property in access tokens.

func AccessTokenLifetime

func AccessTokenLifetime(lifetime int64) Option

AccessTokenLifetime is an option that sets the lifetime of access tokens.

func AuthzProvider

func AuthzProvider(p Authz) Option

AuthzProvider is an option that sets the given authorization provider for the handler instance.

func Clients

func Clients(m ClientMap) Option

Clients is an option that sets the given client mapping for the handler instance.

func IDProvider

func IDProvider(i IDP) Option

IDProvider is an option that adds the given IdP to this handler. If the IDP was already registered it will be silently overwritten.

func JWKID

func JWKID(kid string) Option

JWKID is an option that sets the key id of the JSON Web Key to use for access tokens.

func StateStorage

func StateStorage(engine StateKeeper, lifetime time.Duration) Option

StateStorage is an option that sets the transient storage for the handler instance.

func TraceHeader

func TraceHeader(headerName string) Option

TraceHeader is an option that sets the name of the header that contains a request identifier. If present, logs will contain a field reqID.

type ScopeSet

type ScopeSet interface {
	// ValidScope() returns true if scope is a subset of this scopeset.
	ValidScope(scope ...string) bool
}

ScopeSet defines a set of scopes.

type StateKeeper

type StateKeeper interface {
	Persist(key string, data string, lifetime time.Duration) error
	Restore(key string) (string, error)
}

StateKeeper defines a storage engine used to store transient state data throughout the handler.

type User

type User struct {
	// UID is the user identifier.
	UID string
	// Data may be used
	Data interface{}
}

User holds user data returned from the IDP. We require a UUID because we encode it in our access token.