auth

README

Auth

The core/auth package provides functions for services to issue and sign api consumer tokens.

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.

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 NewMockIssuerWithTime(now func() time.Time) (*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
  • func (e TokenExpiredError) Error() string
• type TokenInvalidError
  • func (e TokenInvalidError) Error() string
• type TokenMalformedError
  • func (e TokenMalformedError) Error() string
• type TokenSignatureError
  • func (e TokenSignatureError) Error() string
• type UnexpectedSigningMethodError
  • func (e UnexpectedSigningMethodError) Error() string

Examples

• ConsumerFromContext
• ContextWithConsumer
• Issuer.Issue

Constants

const (
	// DefaultValidPeriod is the default amount of minutes a token is valid
	DefaultValidPeriod = time.Duration(60 * time.Minute)
)

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 issuer with a random key pair.

func NewMockIssuerWithTime

func NewMockIssuerWithTime(now func() time.Time) (*Issuer, error)

NewMockIssuerWithTime creates a new issuer 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
	ValidPeriod time.Duration
	TimeFunc    func() time.Time
}

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{ Err error }

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

func (TokenExpiredError) Error

func (e TokenExpiredError) Error() string

type TokenInvalidError

type TokenInvalidError struct{ Err error }

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

func (TokenInvalidError) Error

func (e TokenInvalidError) Error() string

type TokenMalformedError

type TokenMalformedError struct{ Err error }

TokenMalformedError happens when the token is not the correct format

func (TokenMalformedError) Error

func (e TokenMalformedError) Error() string

type TokenSignatureError

type TokenSignatureError struct{ Err error }

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

func (TokenSignatureError) Error

func (e TokenSignatureError) Error() string

type UnexpectedSigningMethodError

type UnexpectedSigningMethodError struct {
	Algorithm interface{}
}

UnexpectedSigningMethodError when JWT parsing encounters an unexpected signature method

func (UnexpectedSigningMethodError) Error

func (e UnexpectedSigningMethodError) Error() string