flame

Documentation

Overview

Package flame implements an authentication manager that provides OAuth2 compatible authentication with JWT tokens.

Index

• Constants
• Variables
• func Callback(scope string) fire.Callback
• func DefaultGrantStrategy(scope oauth2.Scope, _ Client, _ ResourceOwner) (oauth2.Scope, error)
• func TokenMigrator(remove bool) func(http.Handler) http.Handler
• type AccessToken
  • func (t *AccessToken) DescribeToken() TokenDescription
  • func (t *AccessToken) GetTokenData() *TokenData
  • func (t *AccessToken) SetTokenData(data *TokenData)
• type Application
  • func (a *Application) DescribeClient() ClientDescription
  • func (a *Application) ValidRedirectURI(uri string) bool
  • func (a *Application) ValidSecret(secret string) bool
• type Authenticator
  • func NewAuthenticator(store *coal.Store, policy *Policy) *Authenticator
  • func (a *Authenticator) Authorizer(scope string, force bool) func(http.Handler) http.Handler
  • func (a *Authenticator) Endpoint(prefix string) http.Handler
• type Client
• type ClientDescription
• type Policy
  • func DefaultPolicy(secret string) *Policy
  • func (p *Policy) GenerateToken(id bson.ObjectId, issuedAt, expiresAt time.Time, client Client, ...) (string, error)
  • func (p *Policy) ParseToken(str string) (*TokenClaims, bool, error)
• type RefreshToken
  • func (t *RefreshToken) DescribeToken() TokenDescription
  • func (t *RefreshToken) GetTokenData() *TokenData
  • func (t *RefreshToken) SetTokenData(data *TokenData)
• type ResourceOwner
• type ResourceOwnerDescription
• type Token
• type TokenClaims
• type TokenData
• type TokenDescription
• type User
  • func (u *User) DescribeResourceOwner() ResourceOwnerDescription
  • func (u *User) ValidPassword(password string) bool

Constants

const AccessTokenContextKey ctxKey = iota

AccessTokenContextKey is the key used to save the access token in a context.

Variables

var ErrGrantRejected = errors.New("grant rejected")

ErrGrantRejected should be returned by the GrantStrategy to indicate a rejection of the grant based on the provided conditions.

var ErrInvalidScope = errors.New("invalid scope")

ErrInvalidScope should be returned by the GrantStrategy to indicate that the requested scope exceeds the grantable scope.

Functions

func Callback

func Callback(scope string) fire.Callback

Callback returns a callback that can be used to protect resources by requiring an access token with the provided scope to be granted.

Note: It requires that the request has already been authorized using the Authorizer middleware from a Authenticator.

func DefaultGrantStrategy

func DefaultGrantStrategy(scope oauth2.Scope, _ Client, _ ResourceOwner) (oauth2.Scope, error)

DefaultGrantStrategy grants the requested scope.

func TokenMigrator

func TokenMigrator(remove bool) func(http.Handler) http.Handler

TokenMigrator is a middleware that detects access tokens passed via query parameters and migrates them to a Bearer Token header. Additionally it may remove the migrated query parameter from the request.

Note: The TokenMigrator should be added before any logger in the middleware chain to successfully protect the access_token from being exposed.

Types

type AccessToken

type AccessToken struct {
	coal.Base       `json:"-" bson:",inline" coal:"access-tokens:access_tokens"`
	ExpiresAt       time.Time      `json:"expires-at" valid:"required" bson:"expires_at"`
	Scope           []string       `json:"scope" valid:"required" bson:"scope"`
	ClientID        bson.ObjectId  `json:"client-id" valid:"-" bson:"client_id"`
	ResourceOwnerID *bson.ObjectId `json:"resource-owner-id" valid:"-" bson:"resource_owner_id"`
}

AccessToken is the built-in model used to store access tokens.

func (*AccessToken) DescribeToken

func (t *AccessToken) DescribeToken() TokenDescription

DescribeToken implements the Token interface.

func (*AccessToken) GetTokenData

func (t *AccessToken) GetTokenData() *TokenData

GetTokenData implements the Token interface.

func (*AccessToken) SetTokenData

func (t *AccessToken) SetTokenData(data *TokenData)

SetTokenData implements the Token interface.

type Application

type Application struct {
	coal.Base   `json:"-" bson:",inline" coal:"applications"`
	Name        string `json:"name" valid:"required"`
	Key         string `json:"key" valid:"required"`
	SecretHash  []byte `json:"-" valid:"required"`
	RedirectURI string `json:"redirect_uri" valid:"required"`
}

Application is the built-in model used to store clients.

func (*Application) DescribeClient

func (a *Application) DescribeClient() ClientDescription

DescribeClient implements the Client interface.

func (*Application) ValidRedirectURI

func (a *Application) ValidRedirectURI(uri string) bool

ValidRedirectURI implements the Client interface.

func (*Application) ValidSecret

func (a *Application) ValidSecret(secret string) bool

ValidSecret implements the Client interface.

type Authenticator

type Authenticator struct {
	Reporter func(error)
	// contains filtered or unexported fields
}

An Authenticator provides OAuth2 based authentication. The implementation currently supports the Resource Owner Credentials Grant, Client Credentials Grant and Implicit Grant.

func NewAuthenticator

func NewAuthenticator(store *coal.Store, policy *Policy) *Authenticator

NewAuthenticator constructs a new Authenticator from a store and policy.

func (*Authenticator) Authorizer

func (a *Authenticator) Authorizer(scope string, force bool) func(http.Handler) http.Handler

Authorizer returns a middleware that can be used to authorize a request by requiring an access token with the provided scope to be granted.

func (*Authenticator) Endpoint

func (a *Authenticator) Endpoint(prefix string) http.Handler

Endpoint returns a handler for the common token and authorize endpoint.

type Client

type Client interface {
	coal.Model

	// DescribeClient should return a ClientDescription.
	DescribeClient() ClientDescription

	// ValidRedirectURI should return whether the specified redirect uri can be
	// used by this client.
	//
	// Note: In order to increases security the callback should only allow
	// pre-registered redirect uris.
	ValidRedirectURI(string) bool

	// ValidSecret should determine whether the specified plain text secret
	// matches the stored hashed secret.
	ValidSecret(string) bool
}

Client is the interface that must be implemented to provide a custom client.

type ClientDescription

type ClientDescription struct {
	IdentifierField string
}

A ClientDescription is returned by a Client model to specify some details about its implementation.

type Policy

type Policy struct {
	// The shared secret which should be at least 16 characters.
	Secret []byte

	// The available grants.
	PasswordGrant          bool
	ClientCredentialsGrant bool
	ImplicitGrant          bool

	// The token models.
	AccessToken  Token
	RefreshToken Token

	// The client models.
	Clients []Client

	// ResourceOwners should return a list of resource owner models that are
	// tried in order to resolve grant requests.
	ResourceOwners func(Client) []ResourceOwner

	// GrantStrategy is invoked by the authenticator with the grant type, the
	// requested scope, the client and the resource owner before issuing an
	// access token. The callback should return no error and the scope that
	// should be granted. It can return ErrGrantRejected or ErrInvalidScope to
	// cancel the grant request.
	//
	// Note: ResourceOwner is not set for a client credentials grant.
	GrantStrategy func(oauth2.Scope, Client, ResourceOwner) (oauth2.Scope, error)

	// TokenData should return a map of data that should be included in the JWT
	// tokens under the "dat" field.
	TokenData func(Client, ResourceOwner) map[string]interface{}

	// The token used lifespans.
	AccessTokenLifespan  time.Duration
	RefreshTokenLifespan time.Duration

	// The optional automated cleanup of expires tokens.
	AutomatedCleanup bool
}

A Policy configures the provided authentication schemes.

func DefaultPolicy

func DefaultPolicy(secret string) *Policy

DefaultPolicy returns a simple policy that uses all built-in models and strategies.

func (*Policy) GenerateToken

func (p *Policy) GenerateToken(id bson.ObjectId, issuedAt, expiresAt time.Time, client Client, ro ResourceOwner) (string, error)

GenerateToken returns a new token for the provided information.

func (*Policy) ParseToken

func (p *Policy) ParseToken(str string) (*TokenClaims, bool, error)

ParseToken will parse the presented token and return its claims, if it is expired and eventual errors.

type RefreshToken

type RefreshToken struct {
	coal.Base       `json:"-" bson:",inline" coal:"refresh-tokens:refresh_tokens"`
	ExpiresAt       time.Time      `json:"expires-at" valid:"required" bson:"expires_at"`
	Scope           []string       `json:"scope" valid:"required" bson:"scope"`
	ClientID        bson.ObjectId  `json:"client-id" valid:"-" bson:"client_id"`
	ResourceOwnerID *bson.ObjectId `json:"resource-owner-id" valid:"-" bson:"resource_owner_id"`
}

RefreshToken is the built-in model used to store refresh tokens.

func (*RefreshToken) DescribeToken

func (t *RefreshToken) DescribeToken() TokenDescription

DescribeToken implements the Token interface.

func (*RefreshToken) GetTokenData

func (t *RefreshToken) GetTokenData() *TokenData

GetTokenData implements the Token interface.

func (*RefreshToken) SetTokenData

func (t *RefreshToken) SetTokenData(data *TokenData)

SetTokenData implements the Token interface.

type ResourceOwner

type ResourceOwner interface {
	coal.Model

	// DescribeResourceOwner should return a ResourceOwnerDescription.
	DescribeResourceOwner() ResourceOwnerDescription

	// ValidSecret should determine whether the specified plain text password
	// matches the stored hashed password.
	ValidPassword(string) bool
}

ResourceOwner is the interface that must be implemented to provide a custom resource owner.

type ResourceOwnerDescription

type ResourceOwnerDescription struct {
	IdentifierField string
}

A ResourceOwnerDescription is returned by a ResourceOwner model to specify some details about its implementation.

type Token

type Token interface {
	coal.Model

	// DescribeToken should return a TokenDescription.
	DescribeToken() TokenDescription

	// GetTokenData should collect and return the tokens data.
	GetTokenData() *TokenData

	// SetTokenData should set the specified token data.
	SetTokenData(*TokenData)
}

Token is the interface that must be implemented to provide a custom access token and refresh token.

type TokenClaims

type TokenClaims struct {
	jwt.StandardClaims

	// Data is only set for access tokens.
	Data map[string]interface{} `json:"dat"`
}

TokenClaims represents the data included in an access token and refresh token.

type TokenData

type TokenData struct {
	Scope           []string
	ExpiresAt       time.Time
	ClientID        bson.ObjectId
	ResourceOwnerID *bson.ObjectId
}

TokenData is used to carry token related information.

type TokenDescription

type TokenDescription struct {
	ClientIDField  string
	ExpiresAtField string
}

A TokenDescription is returned by a Token model to specify some details about its implementation.

type User

type User struct {
	coal.Base    `json:"-" bson:",inline" coal:"users"`
	Name         string `json:"name" valid:"required"`
	Email        string `json:"email" valid:"required"`
	PasswordHash []byte `json:"-" valid:"required"`
}

User is the built-in model used to store resource owners.

func (*User) DescribeResourceOwner

func (u *User) DescribeResourceOwner() ResourceOwnerDescription

DescribeResourceOwner implements the ResourceOwner interface.

func (*User) ValidPassword

func (u *User) ValidPassword(password string) bool

ValidPassword implements the ResourceOwner interface.