README
¶
JWT Middleware
This package provides a goa middleware that checks requests for valid JWT keys. If a key is found, it is made available in goa's context for use in the controllers.
It also includes a Token Manager which can be used to create JWT tokens that are valid for use with the middleware. TokenManager also implements the TokenGen interfaces of github.com/RangelReale/osin so that it can be used to generate tokens for your custom osin-based Oauth2 implementation.
Middleware Usage
Middleware can be applied at the application or service level in goa. To use a middleware,
create an instance of it first, then apply it using the Use function of your application or service:
spec := &jwt.Specification{
AllowParam: false,
AuthOptions: false,
TTLMinutes: 60,
Issuer: "api.me.com",
KeySigningMethod: jwt.RSA256,
SigningKeyFunc: privateKey,
ValidationFunc: pubKey,
}
tm := jwt.NewTokenManager(spec)
// Generate a test token
claims := make(map[string]interface{})
claims["custom"] = "hotrod"
t, err := tm.Create(claims)
fmt.Println(t)
fmt.Println(err)
// Mount "application" controller
c := NewApplicationController(service)
// Require a valid JWT Token for any routes
// on this controller
c.Use(jwt.Middleware(spec))
TokenManager Usage
TokenManager uses the same specification as the JWT Middleware. Instantiate it
with the NewTokenManager function:
spec := &jwt.Specification{
AllowParam: false,
AuthOptions: false,
TTLMinutes: 60,
Issuer: "api.me.com",
KeySigningMethod: jwt.RSA256,
SigningKeyFunc: privateKey,
ValidationFunc: pubKey,
}
tm := jwt.NewTokenManager(spec)
// Generate a test token
claims := make(map[string]interface{})
claims["custom"] = "hotrod"
t, err := tm.Create(claims)
fmt.Println(t)
fmt.Println(err)
Generally you will want to create a custom response type to carry your token:
type LoginResponse struct {
Token string
...
}
token, err := tm.Create(...)
resp:= &LoginResponse{
Token = token
}
Documentation
¶
Overview ¶
Package jwt makes it possible to authorize API requests using JSON Web Tokens, see https://jwt.io/introduction/
Middleware ¶
The package provides a middleware that can be mounted on controllers that require authentication. The JWT middleware is instantiated using the package Middleware function. This function accepts a specification that describes the various properties used by the JWT signature and validation algorithms.
spec := &jwt.Specification{
AllowParam: false, // Pass tokens in headers only
AuthOptions: false, // Do not authorize OPTIONS requests
TTLMinutes: 1440, // Tokens are valid for 24 hours
Issuer: "me.com", // me.com issued the token
KeySigningMethod: jwt.RSA256, // Use the RSA256 hashing algorithm to sign tokens
SigningKeyFunc: privateKey, // privateKey returns the key used to sign tokens
ValidationFunc: pubKey, // pubKey returns the key used to validate tokens
}
authorizedController.Use(jwt.Middleware(spec))
Token Manager ¶
The package also exposes a token manager that creates the JWT tokens. The manager is instantiated using the same specification used to create the middleware:
var tm *jwt.TokenManager = jwt.NewTokenManager(spec)
func Login(ctx *goa.Context) error {
// ...
// Authorize request using ctx, initialize tenant id if necessary etc.
// ...
claims := map[string]interface{}{
"accountID": accountID,
}
token, err := tm.Create(claims)
if err != nil {
return err
}
return ctx.Respond(200, token) // You'll probably need something different here
}
Index ¶
Constants ¶
const JWTHeader = "Authorization"
JWTHeader is the name of the header used to transmit the JWT token.
const JWTKey middlewareKey = 0
JWTKey is the JWT middleware key used to store the token in the context.
const TokenManagerKey middlewareKey = 1
TokenManagerKey is the JWT middleware key used to store the token manager in the context.
Variables ¶
This section is empty.
Functions ¶
func Middleware ¶
func Middleware(spec *Specification) goa.Middleware
Middleware is a middleware that retrieves a JWT token from the request if present and injects it into the context. It checks for the token in the HTTP Headers first, then the querystring if the specification "AllowParam" is true. Retrieve it using ctx.Value(JWTKey).
Types ¶
type KeyFunc ¶
type KeyFunc func() (interface{}, error)
KeyFunc is a function that returns the key to sign a token. It should return a []byte (for all) or a *rsa.PrivateKey or *ecdsa.PrivateKey
type SigningMethod ¶
type SigningMethod int
SigningMethod is the enum that lists the supported token signature hashing algorithms.
const ( // RSA256 signing algorithm RSA256 SigningMethod = iota + 1 // RSA384 signing algorithm RSA384 // RSA512 signing algorithm RSA512 // HMAC256 signing algorithm HMAC256 // HMAC384 signing algorithm HMAC384 // HMAC512 signing algorithm HMAC512 // ECDSA256 signing algorithm ECDSA256 // ECDSA384 signing algorithm ECDSA384 // ECDSA512 signing algorithm ECDSA512 )
type Specification ¶
type Specification struct {
// TokenHeader is the HTTP header to search for the JWT Token
// Defaults to "Authorization"
TokenHeader string
// TokenParam is the request parameter to parse for the JWT Token
// Defaults to "token"
TokenParam string
// AllowParam is a flag that determines whether it is allowable
// to parse tokens from the querystring
// Defaults to false
AllowParam bool
// ValidationFunc is a function that returns the key to validate the JWT
// Required, no default
ValidationFunc ValidationKeyfunc
// AuthOptions is a flag that determines whether a token is required on OPTIONS
// requests
AuthOptions bool
// TTLMinutes is the TTL for tokens that are generated
TTLMinutes int
// RefreshTTLMinutes is the TTL for refresh tokens that are generated
// and should generally be much longer than TTLMinutes
RefreshTTLMinutes int
// Issuer is the name of the issuer that will be inserted into the
// generated token's claims
Issuer string
// KeySigningMethod determines the type of key that will be used to sign
// Tokens.
KeySigningMethod SigningMethod
// SigningKeyFunc is a function that returns the key used to sign the token
SigningKeyFunc KeyFunc
// CommonClaims is a list of claims added to all tokens issued
CommonClaims map[string]interface{}
}
Specification describes the JWT authorization properties. It is used to both instantiate a middleware and a token manager. The middleware uses the specification properties to authorize the incoming request while the token manager uses it to create authorization tokens.
type TokenManager ¶
type TokenManager struct {
// contains filtered or unexported fields
}
TokenManager provides for the creation of access and refresh JWT Tokens
func NewTokenManager ¶
func NewTokenManager(spec *Specification) *TokenManager
NewTokenManager returns a TokenManager. If TTLMinutes isn't specified it will default to 5 minutes. Use the same Specification as you use for Middleware() to ensure your tokens are compatible.
type ValidationKeyfunc ¶
ValidationKeyfunc is a function that takes a token and returns the key to validate that token, which allows it to use inforamtion from the key itself to choose the key to return.
Source Files