jwt

README

JWT Middleware for Go-Json-Rest

This is a middleware for Go-Json-Rest.

It uses jwt-go to provide a jwt authentication middleware. It provides additional handler functions to provide the login api that will generate the token and an additional refresh handler that can be used to refresh tokens.

An example can be found in the Go-Json-Rest Examples repo.

Documentation

Overview

Package jwt provides Json-Web-Token authentication for the go-json-rest framework

Index

• type JWTMiddleware
  • func (mw *JWTMiddleware) ClaimsHandler(writer rest.ResponseWriter, request *rest.Request)
  • func (mw *JWTMiddleware) LoginHandler(writer rest.ResponseWriter, request *rest.Request)
  • func (mw *JWTMiddleware) LogoutHandler(writer rest.ResponseWriter, request *rest.Request)
  • func (mw *JWTMiddleware) MiddlewareFunc(handler rest.HandlerFunc) rest.HandlerFunc
  • func (mw *JWTMiddleware) RefreshHandler(writer rest.ResponseWriter, request *rest.Request)
• type RestClaims
  • func ExtractClaims(request *rest.Request) *RestClaims
  • func (rc RestClaims) Valid() error

Types

type JWTMiddleware

type JWTMiddleware struct {
	// Realm name to display to the user. Required.
	Realm string

	// CookieName used for Set-Cookie (optional, default "jwt")
	CookieName string

	// CookieDomain used for Set-Cookie (optional)
	// If omitted/empty, this attribute defaults to the host of the current document URL, not including subdomains.
	CookieDomain string

	// CookieSecure used for Set-Cookie
	// Indicates that the cookie is sent to the server only when a request is made with the https: scheme (except on localhost), and therefore, is more resistant to man-in-the-middle attacks.
	CookieSecure bool

	// CookiePath used for Set-Cookie (optional, default "/")
	// Indicates the path that must exist in the requested URL for the browser to send the Cookie header.
	CookiePath string

	// signing algorithm - possible values are HS256, HS384, HS512
	// Optional, default is HS256.
	SigningAlgorithm string

	// Secret key used for signing. Required.
	Key []byte

	// Duration that a jwt token is valid. Optional, defaults to one hour.
	Timeout time.Duration

	// This field allows clients to refresh their token until MaxRefresh has passed.
	// Note that clients can refresh their token in the last moment of MaxRefresh.
	// This means that the maximum validity timespan for a token is MaxRefresh + Timeout.
	// Optional, defaults to 0 meaning not refreshable.
	MaxRefresh time.Duration

	// Callback function that should perform the authentication of the user based on userId and
	// password. Returns the Subject to set in claims on success and must return true on success, false on failure. Required.
	Authenticator func(ctx context.Context, userId string, password string) (string, bool)

	// Callback function that should perform the authorization of the authenticated user. Called
	// only after an authentication success. Must return true on success, false on failure.
	// Optional, default to success.
	Authorizator func(ctx context.Context, userId string, request *rest.Request) bool

	// Callback function that will be called during login.
	// Using this function it is possible to add additional payload data to the webtoken.
	// The data is then made available during requests via request.Env["JWT_PAYLOAD"].
	// Note that the payload is not encrypted.
	// The attributes mentioned on jwt.io can't be used as keys for the map.
	// Optional, by default no additional data will be set.
	PayloadFunc func(ctx context.Context, userId string) map[string]interface{}

	// IncludeTokenInResponse determines if the JWT are added to the JSON response (it is always set as a cookie)
	// Best practice for web apps are to keep this false and use httpOnly cookies and let the browser send the JWT cookie as applicable.
	IncludeTokenInResponse bool

	// Debug adds a bit of debug when the middleware rejects request with unauthorized
	// Only use while developing as it leaks details that can potentially be abused by an attacker
	Debug bool
}

JWTMiddleware provides a Json-Web-Token authentication implementation. On failure, a 401 HTTP response is returned. On success, the wrapped middleware is called, and the userId is made available as request.Env["REMOTE_USER"].(string). Users can get a token by posting a json request to LoginHandler. The token then needs to be passed in the Authentication header. Example: Authorization:Bearer XXX_TOKEN_XXX

func (*JWTMiddleware) ClaimsHandler

func (mw *JWTMiddleware) ClaimsHandler(writer rest.ResponseWriter, request *rest.Request)

ClaimsHandler can be used by clients to get their claims based on their token

func (*JWTMiddleware) LoginHandler

func (mw *JWTMiddleware) LoginHandler(writer rest.ResponseWriter, request *rest.Request)

LoginHandler can be used by clients to get a jwt token. Payload needs to be json in the form of {"username": "USERNAME", "password": "PASSWORD"}. Reply will be of the form {"token": "TOKEN"}.

func (*JWTMiddleware) LogoutHandler

func (mw *JWTMiddleware) LogoutHandler(writer rest.ResponseWriter, request *rest.Request)

LogoutHandler can be used by clients to logout It will simply unset the cookie with the JWT.

func (*JWTMiddleware) MiddlewareFunc

func (mw *JWTMiddleware) MiddlewareFunc(handler rest.HandlerFunc) rest.HandlerFunc

MiddlewareFunc makes JWTMiddleware implement the Middleware interface.

func (*JWTMiddleware) RefreshHandler

func (mw *JWTMiddleware) RefreshHandler(writer rest.ResponseWriter, request *rest.Request)

RefreshHandler can be used to refresh a token. The token still needs to be valid on refresh. Shall be put under an endpoint that is using the JWTMiddleware. Reply will be of the form {"token": "TOKEN"}.

type RestClaims

type RestClaims struct {
	jwt.StandardClaims
	OriginalIssuedAt int64                  `json:"orig_iat,omitempty"`
	RefreshUntil     int64                  `json:"refresh_until,omitempty"`
	Custom           map[string]interface{} `json:"custom,omitempty"`
}

func ExtractClaims

func ExtractClaims(request *rest.Request) *RestClaims

ExtractClaims allows to retrieve the payload

func (RestClaims) Valid

func (rc RestClaims) Valid() error