auth

Documentation

Overview

Package auth implements an authentication manager that provides OAuth2 compatible authentication.

Index

• Constants
• func Callback(scope string) fire.Callback
• func DefaultGrantStrategy(req *GrantRequest) (bool, []string)
• func TokenMigrator(remove bool) func(http.Handler) http.Handler
• type AccessToken
  • func (t *AccessToken) DescribeToken() (string, string, string)
  • func (t *AccessToken) GetTokenData() *TokenData
  • func (t *AccessToken) SetTokenData(data *TokenData)
• type Application
  • func (a *Application) DescribeClient() string
  • func (a *Application) ValidRedirectURI(uri string) bool
  • func (a *Application) ValidSecret(secret string) bool
• type Client
• type GrantRequest
• type GrantStrategy
• type Manager
  • func New(store *fire.Store, policy *Policy) *Manager
  • func (m *Manager) Authorizer(scope string) func(http.Handler) http.Handler
  • func (m *Manager) Endpoint(prefix string) http.Handler
• type Policy
  • func DefaultPolicy(secret string) *Policy
  • func (p *Policy) NewKeyAndSignature() (string, string, error)
• type RefreshToken
  • func (t *RefreshToken) DescribeToken() (string, string, string)
  • func (t *RefreshToken) GetTokenData() *TokenData
  • func (t *RefreshToken) SetTokenData(data *TokenData)
• type ResourceOwner
• type Token
• type TokenData
• type User
  • func (u *User) DescribeResourceOwner() string
  • 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.

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 scopes to be granted.

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

func DefaultGrantStrategy

func DefaultGrantStrategy(req *GrantRequest) (bool, []string)

DefaultGrantStrategy grants the complete 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 {
	fire.Base       `json:"-" bson:",inline" fire:"access-tokens:access_tokens"`
	Signature       string         `json:"signature" valid:"required"`
	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() (string, string, string)

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 {
	fire.Base   `json:"-" bson:",inline" fire:"applications"`
	Name        string `json:"name" valid:"required"`
	Key         string `json:"key" valid:"required"`
	SecretHash  []byte `json:"-" valid:"required"`
	Scope       string `json:"scope" 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() string

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 Client

type Client interface {
	fire.Model

	// DescribeClient should return the clients identifier field.
	DescribeClient() string

	// 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 hashed secret.
	ValidSecret(string) bool
}

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

type GrantRequest

type GrantRequest struct {
	// The scope that has been requested.
	Scope []string

	// The client that made the access request.
	Client Client

	// The resource owner that gave his consent.
	ResourceOwner ResourceOwner
}

A GrantRequest is used in conjunction with the GrantStrategy.

type GrantStrategy

type GrantStrategy func(req *GrantRequest) (bool, []string)

The GrantStrategy is invoked by the manager with the grant type, the requested scope, the client and the resource owner before issuing an access token. The callback should return the scopes that should be granted.

Note: The Owner is not set for a client credentials grant.

type Manager

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

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

func New

func New(store *fire.Store, policy *Policy) *Manager

New constructs a new Manager from a store and policy.

func (*Manager) Authorizer

func (m *Manager) Authorizer(scope string) 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 scopes to be granted.

func (*Manager) Endpoint

func (m *Manager) Endpoint(prefix string) http.Handler

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

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 used models and strategies.
	AccessToken   Token
	RefreshToken  Token
	Client        Client
	ResourceOwner ResourceOwner
	GrantStrategy GrantStrategy

	// 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) NewKeyAndSignature

func (p *Policy) NewKeyAndSignature() (string, string, error)

NewKeyAndSignature returns a new key with a matching signature that can be used to issue custom access tokens.

type RefreshToken

type RefreshToken struct {
	fire.Base       `json:"-" bson:",inline" fire:"refresh-tokens:refresh_tokens"`
	Signature       string         `json:"signature" valid:"required"`
	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() (string, string, string)

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 {
	fire.Model

	// DescribeResourceOwner should return the resource owners identifier field.
	DescribeResourceOwner() string

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

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

type Token

type Token interface {
	fire.Model

	// DescribeToken should return the tokens identifier, client id and expires at field.
	DescribeToken() (string, string, string)

	// 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 TokenData

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

TokenData is used to carry token related information.

type User

type User struct {
	fire.Base    `json:"-" bson:",inline" fire:"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() string

DescribeResourceOwner implements the ResourceOwner interface.

func (*User) ValidPassword

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

ValidPassword implements the ResourceOwner interface.