Documentation
¶
Overview ¶
Package auth implements an authentication manager that provides OAuth2 compatible authentication.
Index ¶
- Constants
- Variables
- func Callback(scope string) fire.Callback
- func DefaultGrantStrategy(req *GrantRequest) (oauth2.Scope, error)
- func TokenMigrator(remove bool) func(http.Handler) http.Handler
- type AccessToken
- type Application
- type Client
- type ClientDescription
- type GrantRequest
- type GrantStrategy
- type Manager
- type Policy
- type RefreshToken
- type ResourceOwner
- type ResourceOwnerDescription
- type Token
- type TokenData
- type TokenDescription
- type User
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 ¶
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 Manager.
func DefaultGrantStrategy ¶
func DefaultGrantStrategy(req *GrantRequest) (oauth2.Scope, error)
DefaultGrantStrategy grants the requested scope.
func TokenMigrator ¶ added in v0.4.4
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"`
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 ¶ added in v0.3.1
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 {
fire.Base `json:"-" bson:",inline" fire:"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 ¶ added in v0.3.1
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 Client ¶
type Client interface {
fire.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 hashed secret.
ValidSecret(string) bool
}
Client is the interface that must be implemented to provide a custom client.
type ClientDescription ¶ added in v0.5.6
type ClientDescription struct {
IdentifierField string
}
A ClientDescription is returned by a Client model to specify some details about its implementation.
type GrantRequest ¶
type GrantRequest struct {
// The scope that has been requested.
Scope oauth2.Scope
// The client that made the access request.
Client Client
// The resource owner that gave his consent.
//
// Note: ResourceOwner is not set for a client credentials grant.
ResourceOwner ResourceOwner
}
A GrantRequest is used in conjunction with the GrantStrategy.
type GrantStrategy ¶
type GrantStrategy func(req *GrantRequest) (oauth2.Scope, error)
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 no error and the scope that should be granted. It can return ErrGrantRejected or ErrInvalidScope to cancel the grant request.
type Manager ¶ added in v0.5.1
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 (*Manager) Authorizer ¶ added in v0.5.1
Authorizer returns a middleware that can be used to authorize a request by requiring an access token with the provided scope to be granted.
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
Clients []Client
ResourceOwners []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 ¶
DefaultPolicy returns a simple policy that uses all built-in models and strategies.
func (*Policy) NewAccessToken ¶ added in v0.7.0
func (p *Policy) NewAccessToken(id bson.ObjectId, issuedAt, expiresAt time.Time, ro ResourceOwner) (string, error)
NewAccessToken returns a new access token for the provided information.
type RefreshToken ¶
type RefreshToken struct {
fire.Base `json:"-" bson:",inline" fire:"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 ¶ added in v0.3.1
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 {
fire.Model
// DescribeResourceOwner should return a ResourceOwnerDescription.
DescribeResourceOwner() ResourceOwnerDescription
// ValidSecret should determine whether the specified plain text password
// matches the hashed password.
ValidPassword(string) bool
// DataForAccessToken should return a map of data that should be included
// in the JWT token under the "dat" field.
DataForAccessToken() map[string]interface{}
}
ResourceOwner is the interface that must be implemented to provide a custom resource owner.
type ResourceOwnerDescription ¶ added in v0.5.6
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 {
fire.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 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 ¶ added in v0.5.6
A TokenDescription is returned by a Token model to specify some details about its implementation.
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) DataForAccessToken ¶ added in v0.7.0
DataForAccessToken implements the ResourceOwner interface.
func (*User) DescribeResourceOwner ¶ added in v0.3.2
func (u *User) DescribeResourceOwner() ResourceOwnerDescription
DescribeResourceOwner implements the ResourceOwner interface.
func (*User) ValidPassword ¶
ValidPassword implements the ResourceOwner interface.