Documentation
¶
Overview ¶
Package flame implements an authenticator that provides OAuth2 compatible authentication with JWT tokens.
Index ¶
- Constants
- Variables
- func AddApplicationIndexes(i *coal.Indexer)
- func AddTokenIndexes(i *coal.Indexer, autoExpire bool)
- func AddUserIndexes(i *coal.Indexer)
- func Callback(force bool, scope ...string) *fire.Callback
- func DefaultGrantStrategy(scope oauth2.Scope, _ Client, _ ResourceOwner) (oauth2.Scope, error)
- func DefaultTokenData(_ Client, ro ResourceOwner, _ GenericToken) map[string]interface{}
- func EnsureApplication(store *coal.Store, name, key, secret string) (string, error)
- func EnsureFirstUser(store *coal.Store, name, email, password string) error
- func GenerateJWTToken(secret string, claims JWTClaims) (string, error)
- func ParseJWTToken(secret, token string, claims *JWTClaims) (*jwt.Token, error)
- func TokenMigrator(remove bool) func(http.Handler) http.Handler
- type Application
- type AuthInfo
- type Authenticator
- type Client
- type GenericToken
- type JWTClaims
- type Policy
- type ResourceOwner
- type Token
- type TokenType
- type User
Constants ¶
const ( // AccessTokenContextKey is the key used to save the access token in a context. AccessTokenContextKey = ctxKey("access-token") // ClientContextKey is the key used to save the client in a context. ClientContextKey = ctxKey("client") // ResourceOwnerContextKey is the key used to save the resource owner in a context. ResourceOwnerContextKey = ctxKey("resource-owner") )
const AuthInfoDataKey = "flame:auth-info"
AuthInfoDataKey is the key used to store the auth info struct.
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 ErrInvalidFilter = errors.New("invalid filter")
ErrInvalidFilter should be returned by the ResourceOwnerFilter to indicate that the request includes invalid filter parameters.
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 AddApplicationIndexes ¶ added in v0.8.8
AddApplicationIndexes will add application indexes to the specified indexer.
func AddTokenIndexes ¶ added in v0.18.0
AddTokenIndexes will add access token indexes to the specified indexer.
func AddUserIndexes ¶ added in v0.8.8
AddUserIndexes will add user indexes to the specified indexer.
func Callback ¶
Callback returns a callback that can be used in controllers to protect resources by requiring an access token with the provided scope to be granted.
Note: The callback requires that the request has already been authorized using the Authorizer middleware from an Authenticator.
func DefaultGrantStrategy ¶
DefaultGrantStrategy grants only empty scopes.
func DefaultTokenData ¶ added in v0.17.0
func DefaultTokenData(_ Client, ro ResourceOwner, _ GenericToken) map[string]interface{}
DefaultTokenData adds the user's id to the token data claim.
func EnsureApplication ¶ added in v0.8.7
EnsureApplication will ensure that an application with the provided name exists and returns its key.
func EnsureFirstUser ¶ added in v0.8.7
EnsureFirstUser ensures the existence of a first user if no other has been created.
func GenerateJWTToken ¶ added in v0.20.0
GenerateJWTToken will generate a custom JWT token.
func ParseJWTToken ¶ added in v0.20.0
ParseJWTToken will parse a custom JWT token.
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 Application ¶
type Application struct {
coal.Base `json:"-" bson:",inline" coal:"applications"`
Name string `json:"name" bson:"name"`
Key string `json:"key" bson:"key" coal:"flame-client-id"`
Secret string `json:"secret,omitempty" bson:"-"`
SecretHash []byte `json:"-" bson:"secret"`
RedirectURL string `json:"redirect-url" bson:"redirect_url"`
}
Application is the built-in model used to store clients.
func (*Application) HashSecret ¶ added in v0.8.5
func (a *Application) HashSecret() error
HashSecret will hash Secret and set SecretHash.
func (*Application) ValidRedirectURL ¶ added in v0.8.7
func (a *Application) ValidRedirectURL(url string) bool
ValidRedirectURL implements the flame.Client interface.
func (*Application) ValidSecret ¶
func (a *Application) ValidSecret(secret string) bool
ValidSecret implements the flame.Client interface.
func (*Application) Validate ¶ added in v0.8.5
func (a *Application) Validate() error
Validate implements the coal.ValidatableModel interface.
type AuthInfo ¶ added in v0.18.1
type AuthInfo struct {
Client Client
ResourceOwner ResourceOwner
AccessToken GenericToken
}
AuthInfo is the collected authentication info stored in the data map.
type Authenticator ¶
type Authenticator struct {
// The function gets invoked by the authenticator with critical errors.
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, loadClient, loadResourceOwner 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.
type Client ¶
type Client interface {
coal.Model
// ValidRedirectURL should return whether the specified redirect url can be
// used by this client.
//
// Note: In order to increases security the callback should only allow
// pre-registered redirect urls.
ValidRedirectURL(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 by clients. The field used to uniquely identify the client must be flagged with "flame-client-id".
type GenericToken ¶ added in v0.18.0
type GenericToken interface {
coal.Model
// GetTokenData should collect and return the tokens data.
GetTokenData() (typ TokenType, scope []string, expiresAt time.Time, client coal.ID, resourceOwner *coal.ID)
// SetTokenData should set the specified token data.
SetTokenData(typ TokenType, scope []string, expiresAt time.Time, client Client, resourceOwner ResourceOwner)
}
GenericToken is the interface that must be implemented by the tokens.
type JWTClaims ¶ added in v0.20.0
type JWTClaims struct {
jwt.StandardClaims
// Data contains user defined key value pairs.
Data map[string]interface{} `json:"dat,omitempty"`
}
JWTClaims extends the standard JWT claims to include the "dat" attribute.
type Policy ¶
type Policy struct {
// The secret should be at least 16 characters long.
Secret string
// The available grants.
PasswordGrant bool
ClientCredentialsGrant bool
ImplicitGrant bool
// The token model.
Token GenericToken
// The client models.
Clients []Client
// ClientFilter should return a filter that should be applied when looking
// up a client. This callback can be used to select clients based on other
// request parameters. It can return ErrInvalidFilter to cancel the
// authentication request.
ClientFilter func(Client, *http.Request) (bson.M, error)
// ResourceOwners should return a list of resource owner models that are
// tried in order to resolve grant requests.
ResourceOwners func(Client) []ResourceOwner
// ResourceOwnerFilter should return a filter that should be applied when
// looking up a resource owner. This callback can be used to select resource
// owners based on other request parameters. It can return ErrInvalidFilter
// to cancel the authentication request.
ResourceOwnerFilter func(ResourceOwner, *http.Request) (bson.M, error)
// 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, GenericToken) map[string]interface{}
// The token used lifespans.
AccessTokenLifespan time.Duration
RefreshTokenLifespan time.Duration
}
A Policy configures the provided authentication schemes.
func DefaultPolicy ¶
DefaultPolicy returns a simple policy that uses all built-in models and strategies.
Note: The secret should be at least 16 characters long.
func (*Policy) GenerateToken ¶
func (p *Policy) GenerateToken(id coal.ID, issuedAt, expiresAt time.Time, client Client, resourceOwner ResourceOwner, token GenericToken) (string, error)
GenerateToken returns a new token for the provided information.
type ResourceOwner ¶
type ResourceOwner interface {
coal.Model
// 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 resource owners. The field used to uniquely identify the resource owner must be flagged with "flame-resource-owner-id".
type Token ¶
type Token struct {
coal.Base `json:"-" bson:",inline" coal:"tokens:tokens"`
Type TokenType `json:"type"`
ExpiresAt time.Time `json:"expires-at" bson:"expires_at"`
Scope []string `json:"scope" bson:"scope"`
Application coal.ID `json:"-" bson:"application_id" coal:"application:applications"`
User *coal.ID `json:"-" bson:"user_id" coal:"user:users"`
}
Token is the built-in model used to store access and refresh tokens.
func (*Token) GetTokenData ¶
GetTokenData implements the flame.GenericToken interface.
func (*Token) SetTokenData ¶
func (t *Token) SetTokenData(typ TokenType, scope []string, expiresAt time.Time, client Client, resourceOwner ResourceOwner)
SetTokenData implements the flame.GenericToken interface.
type User ¶
type User struct {
coal.Base `json:"-" bson:",inline" coal:"users"`
Name string `json:"name" bson:"name"`
Email string `json:"email" bson:"email" coal:"flame-resource-owner-id"`
Password string `json:"password,omitempty" bson:"-"`
PasswordHash []byte `json:"-" bson:"password"`
}
User is the built-in model used to store resource owners.
func (*User) HashPassword ¶ added in v0.8.5
HashPassword will hash Password and set PasswordHash.
func (*User) ValidPassword ¶
ValidPassword implements the flame.ResourceOwner interface.