auth

README

Auth

The core/auth package provides functions for services to issue and sign api consumer tokens. It contains several middlewares for HTTP and GRPC to aid streamlining the authentication process.

Examples

Put consumers through context

Setting the consumer in a context.

ctx = auth.ContextWithConsumer(context.Background(), auth.Consumer{
	ID:     999,
	Grants: []string{"foo"},
})

Retreiving a consumer from context.

consumer := auth.ConsumerFromContext(ctx)
consumer.IsUser(999)

Issue new tokens

consumer := &auth.Consumer{
	ID:        999,
	FirstName: "Testy",
	LastName:  "McTest",
	Grants: []string{
		"testing.read",
		"testing.create",
	},
}
raw, err := issuer.Issue(consumer)
if err != nil {
	return
}
fmt.Println(raw)

Documentation

Overview

Package auth provides functions for services to issue and sign api consumer tokens. It contains several middlewares for HTTP and GRPC to aid streamlining the authentication process.

Index

• Constants
• Variables
• func ContextWithConsumer(parent context.Context, consumer Consumer) context.Context
• type Claims
  • func (c *Claims) ExpiresAt() time.Time
  • func (c *Claims) IssuedAt() time.Time
  • func (c *Claims) NotBefore() time.Time
• type Consumer
  • func ConsumerFromContext(ctx context.Context) Consumer
  • func (c *Consumer) HasAnyGrant(grants ...string) bool
  • func (c *Consumer) HasAnyNeed(needs ...string) bool
  • func (c *Consumer) HasAnyRole(roles ...string) bool
  • func (c *Consumer) HasUUID(id string) bool
  • func (c *Consumer) IsUser(userID int64) bool
• type Issuer
  • func NewIssuer(cfg IssuerConfig, privateKey *rsa.PrivateKey) *Issuer
  • func NewIssuerFromPrivateKeyPEM(cfg IssuerConfig, pem []byte) (*Issuer, error)
  • func NewMockIssuer() (*Issuer, error)
  • func (i *Issuer) Issue(consumer *Consumer) (string, error)
  • func (i *Issuer) IssueWithClaims(claims Claims) (string, error)
  • func (i *Issuer) Parser() *Parser
• type IssuerConfig
• type Parser
  • func NewParser(pk *rsa.PublicKey) *Parser
  • func NewParserFromPublicKeyPEM(pkb []byte) (*Parser, error)
  • func (p *Parser) Claims(raw string) (*Claims, error)
  • func (p *Parser) Token(raw string) (*jwt.Token, error)
• type RSAPublicKeyCopierRenewer
• type TokenExpiredError
• type TokenInvalidError
• type TokenMalformedError
• type TokenSignatureError
• type UnexpectedSigningMethodError
  • func (e UnexpectedSigningMethodError) Error() string

Examples

• ConsumerFromContext
• ContextWithConsumer
• Issuer.Issue

Constants

const (
	// DefaultTokenValidPeriod is the default amount of minutes a token is valid
	DefaultTokenValidPeriod = 60
)

Variables

var (
	// ErrTokenInvalid happens when a token could not be validated because of an unknown reason
	ErrTokenInvalid = TokenInvalidError{fmt.Errorf("token invalid")}
)

Functions

func ContextWithConsumer

func ContextWithConsumer(parent context.Context, consumer Consumer) context.Context

ContextWithConsumer takes a context and a service consumer and returns a new context with the consumer embedded.

Example

package main

import (
	"context"

	"github.com/LUSHDigital/core/auth"
)

var ctx context.Context

func main() {
	ctx = auth.ContextWithConsumer(context.Background(), auth.Consumer{
		ID:     999,
		Grants: []string{"foo"},
	})
}

Types

type Claims

type Claims struct {
	Consumer Consumer `json:"consumer"`
	jwt.StandardClaims
}

Claims hold the JWT claims to user for a token

func (*Claims) ExpiresAt

func (c *Claims) ExpiresAt() time.Time

ExpiresAt returns the expiry time for claims

func (*Claims) IssuedAt

func (c *Claims) IssuedAt() time.Time

IssuedAt returns the issued time for claims

func (*Claims) NotBefore

func (c *Claims) NotBefore() time.Time

NotBefore returns the issued time for claims

type Consumer

type Consumer struct {
	ID        int64    `json:"id"`
	UUID      string   `json:"uuid"`
	FirstName string   `json:"first_name"`
	LastName  string   `json:"last_name"`
	Language  string   `json:"language"`
	Grants    []string `json:"grants"`
	Roles     []string `json:"roles"`
	Needs     []string `json:"needs"`
}

Consumer represents an API user

func ConsumerFromContext

func ConsumerFromContext(ctx context.Context) Consumer

ConsumerFromContext extracts the consumer from the supplied context.

Example

package main

import (
	"context"

	"github.com/LUSHDigital/core/auth"
)

var ctx context.Context

func main() {
	consumer := auth.ConsumerFromContext(ctx)
	consumer.IsUser(999)
}

func (*Consumer) HasAnyGrant

func (c *Consumer) HasAnyGrant(grants ...string) bool

HasAnyGrant checks if a consumer possess any of a given set of grants

func (*Consumer) HasAnyNeed

func (c *Consumer) HasAnyNeed(needs ...string) bool

HasAnyNeed checks if a consumer has any of the given needs

func (*Consumer) HasAnyRole

func (c *Consumer) HasAnyRole(roles ...string) bool

HasAnyRole checks if a consumer possess any of a given set of roles

func (*Consumer) HasUUID

func (c *Consumer) HasUUID(id string) bool

HasUUID checks if a consumer has the same uuid as a user

func (*Consumer) IsUser

func (c *Consumer) IsUser(userID int64) bool

IsUser checks if a consumer has the same ID as a user

type Issuer

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

Issuer represents a set of methods for generating a JWT with a private key

func NewIssuer

func NewIssuer(cfg IssuerConfig, privateKey *rsa.PrivateKey) *Issuer

NewIssuer returns a new JWT instance

func NewIssuerFromPrivateKeyPEM

func NewIssuerFromPrivateKeyPEM(cfg IssuerConfig, pem []byte) (*Issuer, error)

NewIssuerFromPrivateKeyPEM will take a private key PEM file and return a token issuer

func NewMockIssuer

func NewMockIssuer() (*Issuer, error)

NewMockIssuer creates a new tokeniser with a random key pair

func (*Issuer) Issue

func (i *Issuer) Issue(consumer *Consumer) (string, error)

Issue generates and returns a JWT authentication token for a private key

Example

consumer := &auth.Consumer{
	ID:        999,
	FirstName: "Testy",
	LastName:  "McTest",
	Grants: []string{
		"testing.read",
		"testing.create",
	},
}
raw, err := issuer.Issue(consumer)
if err != nil {
	return
}
fmt.Println(raw)

func (*Issuer) IssueWithClaims

func (i *Issuer) IssueWithClaims(claims Claims) (string, error)

IssueWithClaims overrides the default claims and issues a JWT token for the a private key

func (*Issuer) Parser

func (i *Issuer) Parser() *Parser

Parser returns a parser based on the issuers private key's public counterpart

type IssuerConfig

type IssuerConfig struct {
	Name             string
	TokenValidPeriod int
}

IssuerConfig is a set of data to configure an issuer

type Parser

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

Parser represents a set of methods for parsing and validating a JWT against a public key

func NewParser

func NewParser(pk *rsa.PublicKey) *Parser

NewParser returns a new parser with a public key.

func NewParserFromPublicKeyPEM

func NewParserFromPublicKeyPEM(pkb []byte) (*Parser, error)

NewParserFromPublicKeyPEM parses a public key to

func (*Parser) Claims

func (p *Parser) Claims(raw string) (*Claims, error)

Claims returns the consumer details for a given auth token.

func (*Parser) Token

func (p *Parser) Token(raw string) (*jwt.Token, error)

Token takes a string and returns a valid jwt token

type RSAPublicKeyCopierRenewer

type RSAPublicKeyCopierRenewer interface {
	Copy() rsa.PublicKey
	Renew()
}

RSAPublicKeyCopierRenewer represents the combination of a Copier and Renewer interface

type TokenExpiredError

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

TokenExpiredError happens when the token has expired or is not yet valid

type TokenInvalidError

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

TokenInvalidError happens when a token could not be validated because of an unknown reason

type TokenMalformedError

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

TokenMalformedError happens when the token is not the correct format

type TokenSignatureError

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

TokenSignatureError happens when the signature could not be verified with the given public key

type UnexpectedSigningMethodError

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

UnexpectedSigningMethodError when JWT parsing encounters an unexpected signature method

func (UnexpectedSigningMethodError) Error

func (e UnexpectedSigningMethodError) Error() string