ring-jwt

Ring middleware for parsing, decoding and verifying a JWS-signed JWT token from the incoming request.

Built on top of the excellent auth0 JWT library.

Once wired into to your ring server, the middleware will:

• Search for a JWT token on each incoming request (see below for information on where it looks).
• Will add the claims it finds in the token as a clojure map against the :claims key on the incoming request.
• Add an empty :claims map to the request if no token is found.
• Respond with a 401 if the JWS signature in the token cannot be verified.
• Respond with a 401 if the token has expired (i.e. the exp claim indicates a time in the past)
• Respond with a 401 if the token will only be active in the future (i.e. the nbf claim indicates a time in the future)

Note that there is the option to specify a leeway for the exp/nbf checks - see usage below.

Installation

[ovotech/ring-jwt "0.1.0"]

Usage

(require '[ring.middleware.jwt :refer [wrap-jwt]])

(defn handler [request]
  (response {:foo "bar"}))

(jwt/wrap-jwt handler {:alg        :HS256
                       :public-key "yoursecret"})

Depending upon the cryptographic algorithm that is selected for the middleware, a different map of options will be required. Note that, at the point your ring middleware is wired up, ring-jwt will throw an error if it detects that the given options are invalid.

Currently the following JWA algorithms are supported for the purposes of JWS:

Algorithm	Options
RSASSA-PKCS-v1_5 using SHA-256	{:alg :RS256 :public-key public-key} [1]
	{:alg :RS256 :jwk-endpoint "https://your/jwk/endpoint"}
HMAC using SHA-256	{:alg :HS256 :public-key "your-secret"}

[1] public-key is of type java.security.PublicKey.

Additionally, the following optional options are supported:

• leeway-seconds: The number of seconds leeway to give when verifying the expiry/active from claims of the token (i.e. the exp and nbf claims).
• issuer: The issuer of the token, if this does not match the issuer on a token a 401 will be returned.

Finding the token on the request

Currently the library looks in order from the following locations:

1. Authorization header bearer token (i.e. an Authorization HTTP header of the form "Bearer TOKEN")

Useful links

• JSON Web Tokens - JWT Specification
• JSON Web Signatures - JWS Specification
• JSON Web Algorithms - JWA Specification
• JSON Web Keys - JWK Specification
• jwt.io

License

Copyright © 2018 Ovo Energy Ltd.

Distributed under the Eclipse Public License, the same as Clojure.