auth

Documentation

Overview

Package auth provides authentication and authorization support.

Index

• Constants
• type Auth
  • func New(algorithm string, lookup PublicKeyLookup, keys Keys) (*Auth, error)
  • func (a *Auth) AddKey(privateKey *rsa.PrivateKey, kid string)
  • func (a *Auth) GenerateToken(kid string, claims Claims) (string, error)
  • func (a *Auth) RemoveKey(kid string)
  • func (a *Auth) ValidateToken(tokenStr string) (Claims, error)
• type Claims
  • func (c Claims) Authorized(roles ...string) bool
• type Keys
• type PublicKeyLookup

Constants

const (
	RoleAdmin = "ADMIN"
	RoleUser  = "USER"
)

These are the expected values for Claims.Roles.

const Key ctxKey = 1

Key is used to store/retrieve a Claims value from a context.Context.

Types

type Auth

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

Auth is used to authenticate clients. It can generate a token for a set of user claims and recreate the claims by parsing the token.

func New

func New(algorithm string, lookup PublicKeyLookup, keys Keys) (*Auth, error)

New creates an *Authenticator for use.

func (*Auth) AddKey

func (a *Auth) AddKey(privateKey *rsa.PrivateKey, kid string)

AddKey adds a private key and combination kid id to our local store.

func (*Auth) GenerateToken

func (a *Auth) GenerateToken(kid string, claims Claims) (string, error)

GenerateToken generates a signed JWT token string representing the user Claims.

func (*Auth) RemoveKey

func (a *Auth) RemoveKey(kid string)

RemoveKey removes a private key and combination kid id to our local store.

func (*Auth) ValidateToken

func (a *Auth) ValidateToken(tokenStr string) (Claims, error)

ValidateToken recreates the Claims that were used to generate a token. It verifies that the token was signed using our key.

type Claims

type Claims struct {
	jwt.StandardClaims
	Roles []string `json:"roles"`
}

Claims represents the authorization claims transmitted via a JWT.

func (Claims) Authorized

func (c Claims) Authorized(roles ...string) bool

Authorized returns true if the claims has at least one of the provided roles.

type Keys

type Keys map[string]*rsa.PrivateKey

Keys represents an in memory store of keys.

type PublicKeyLookup

type PublicKeyLookup func(kid string) (*rsa.PublicKey, error)

PublicKeyLookup defines the signature of a function to lookup public keys.

In a production system, a key id (KID) is used to retrieve the correct public key to parse a JWT for auth and claims. A key lookup function is provided to perform the task of retrieving a KID for a given public key.

A key lookup function is required for creating an Authenticator.

* Private keys should be rotated. During the transition period, tokens signed with the old and new keys can coexist by looking up the correct public key by KID.

* KID to public key resolution is usually accomplished via a public JWKS endpoint. See https://auth0.com/docs/jwks for more details.