The highest tagged major version is
README
¶
jwtauth - JWT authentication middleware for HTTP services
The jwtauth http middleware package provides a simple way to verify a JWT token
from a http request and send the result down the request context (context.Context).
Please note, jwtauth works with any Go http router, but resides under the go-chi group
for maintenance and organization - its only 3rd party dependency is the underlying jwt library
"github.com/lestrrat-go/jwx".
In a complete JWT-authentication flow, you'll first capture the token from a http
request, decode it, verify it and then validate that its correctly signed and hasn't
expired - the jwtauth.Verifier middleware handler takes care of all of that. The
jwtauth.Verifier will set the context values on keys jwtauth.TokenCtxKey and
jwtauth.ErrorCtxKey.
Next, it's up to an authentication handler to respond or continue processing after the
jwtauth.Verifier. The jwtauth.Authenticator middleware responds with a 401 Unauthorized
plain-text payload for all unverified tokens and passes the good ones through. You can
also copy the Authenticator and customize it to handle invalid tokens to better fit
your flow (ie. with a JSON error response body).
By default, the Verifier will search for a JWT token in a http request, in the order:
- 'Authorization: BEARER T' request header
- 'jwt' Cookie value
The first JWT string that is found as an authorization header
or cookie header is then decoded by the lestrrat-go/jwx library and a jwt.Token
object is set on the request context. In the case of a signature decoding error
the Verifier will also set the error on the request context.
The Verifier always calls the next http handler in sequence, which can either
be the generic jwtauth.Authenticator middleware or your own custom handler
which checks the request context jwt token and error to prepare a custom
http response.
Note: jwtauth supports custom verification sequences for finding a token
from a request by using the Verify middleware instantiator directly. The default
Verifier is instantiated by calling Verify(ja, TokenFromHeader, TokenFromCookie).
Usage
See the full example.
package main
import (
"fmt"
"net/http"
"github.com/go-chi/chi"
"github.com/go-chi/jwtauth"
)
var tokenAuth *jwtauth.JWTAuth
func init() {
tokenAuth = jwtauth.New("HS256", []byte("secret"), nil)
// For debugging/example purposes, we generate and print
// a sample jwt token with claims `user_id:123` here:
_, tokenString, _ := tokenAuth.Encode(map[string]interface{}{"user_id": 123})
fmt.Printf("DEBUG: a sample jwt is %s\n\n", tokenString)
}
func main() {
addr := ":3333"
fmt.Printf("Starting server on %v\n", addr)
http.ListenAndServe(addr, router())
}
func router() http.Handler {
r := chi.NewRouter()
// Protected routes
r.Group(func(r chi.Router) {
// Seek, verify and validate JWT tokens
r.Use(jwtauth.Verifier(tokenAuth))
// Handle valid / invalid tokens. In this example, we use
// the provided authenticator middleware, but you can write your
// own very easily, look at the Authenticator method in jwtauth.go
// and tweak it, its not scary.
r.Use(jwtauth.Authenticator)
r.Get("/admin", func(w http.ResponseWriter, r *http.Request) {
_, claims, _ := jwtauth.FromContext(r.Context())
w.Write([]byte(fmt.Sprintf("protected area. hi %v", claims["user_id"])))
})
})
// Public routes
r.Group(func(r chi.Router) {
r.Get("/", func(w http.ResponseWriter, r *http.Request) {
w.Write([]byte("welcome anonymous"))
})
})
return r
}
LICENSE
Documentation
¶
Index ¶
- Variables
- func Authenticator(next http.Handler) http.Handler
- func EpochNow() int64
- func ErrorReason(err error) error
- func ExpireIn(tm time.Duration) int64
- func FromContext(ctx context.Context) (jwt.Token, map[string]interface{}, error)
- func NewContext(ctx context.Context, t jwt.Token, err error) context.Context
- func SetExpiry(claims map[string]interface{}, tm time.Time)
- func SetExpiryIn(claims map[string]interface{}, tm time.Duration)
- func SetIssuedAt(claims map[string]interface{}, tm time.Time)
- func SetIssuedNow(claims map[string]interface{})
- func TokenFromCookie(r *http.Request) string
- func TokenFromHeader(r *http.Request) string
- func TokenFromQuery(r *http.Request) string
- func UnixTime(tm time.Time) int64
- func Verifier(ja *JWTAuth) func(http.Handler) http.Handler
- func Verify(ja *JWTAuth, findTokenFns ...func(r *http.Request) string) func(http.Handler) http.Handler
- func VerifyRequest(ja *JWTAuth, r *http.Request, findTokenFns ...func(r *http.Request) string) (jwt.Token, error)
- func VerifyToken(ja *JWTAuth, tokenString string) (jwt.Token, error)
- type JWTAuth
Constants ¶
This section is empty.
Variables ¶
var ( TokenCtxKey = &contextKey{"Token"} ErrorCtxKey = &contextKey{"Error"} )
Functions ¶
func Authenticator ¶
Authenticator is a default authentication middleware to enforce access from the Verifier middleware request context values. The Authenticator sends a 401 Unauthorized response for any unverified tokens and passes the good ones through. It's just fine until you decide to write something similar and customize your client response.
func EpochNow ¶
func EpochNow() int64
EpochNow is a helper function that returns the NumericDate time value used by the spec
func ErrorReason ¶ added in v1.1.0
ErrorReason will normalize the error message from the underlining jwt library
func ExpireIn ¶
ExpireIn is a helper function to return calculated time in the future for "exp" claim
func SetExpiryIn ¶
Set expiry ("exp") in the claims to some duration from the present time
func SetIssuedAt ¶
Set issued at ("iat") to specified time in the claims
func SetIssuedNow ¶
func SetIssuedNow(claims map[string]interface{})
Set issued at ("iat") to present time in the claims
func TokenFromCookie ¶
TokenFromCookie tries to retreive the token string from a cookie named "jwt".
func TokenFromHeader ¶
TokenFromHeader tries to retreive the token string from the "Authorization" reqeust header: "Authorization: BEARER T".
func TokenFromQuery ¶
TokenFromQuery tries to retreive the token string from the "jwt" URI query parameter.
To use it, build our own middleware handler, such as:
func Verifier(ja *JWTAuth) func(http.Handler) http.Handler {
return func(next http.Handler) http.Handler {
return Verify(ja, TokenFromQuery, TokenFromHeader, TokenFromCookie)(next)
}
}
func Verifier ¶
Verifier http middleware handler will verify a JWT string from a http request.
Verifier will search for a JWT token in a http request, in the order:
- 'jwt' URI query parameter
- 'Authorization: BEARER T' request header
- Cookie 'jwt' value
The first JWT string that is found as a query parameter, authorization header or cookie header is then decoded by the `jwt-go` library and a *jwt.Token object is set on the request context. In the case of a signature decoding error the Verifier will also set the error on the request context.
The Verifier always calls the next http handler in sequence, which can either be the generic `jwtauth.Authenticator` middleware or your own custom handler which checks the request context jwt token and error to prepare a custom http response.
Source Files
Directories