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
- type Application
- type Authenticator
- type Client
- type ClientDescription
- type Policy
- type RefreshToken
- type ResourceOwner
- type ResourceOwnerDescription
- type Token
- type TokenClaims
- 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 Authenticator.
func DefaultGrantStrategy ¶
DefaultGrantStrategy grants the requested scope.
func TokenMigrator ¶
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 ¶
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 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 ¶
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 ¶
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 ¶
ValidPassword implements the ResourceOwner interface.