MasonM/wiremock-jwt-extension

WireMock extension for matching requests with JSON Web Tokens (JWT)

Overview

wiremock-jwt-extension consists of two extensions for WireMock: a request matcher extension and a stub mapping transformer extension.

The request matcher extracts JWT tokens from incoming requests and matches against the "payload" and/or "header" portions. The stub mapping transformer can transform recorded stub mappings to use the request matcher if there exists a JWT token in the "Authorization" header.

JWE (JSON Web Encryption) and signature verification are not currently supported. Patches welcome!

Installation

Maven:

<dependency>
    <groupId>com.github.masonm</groupId>
    <artifactId>wiremock-jwt-extension</artifactId>
    <version>1.0.0</version>
</dependency>

Gradle:

implementation 'com.github.masonm:wiremock-jwt-extension:1.0.0'

Running

There are three ways of running the extension:

1. Standalone, e.g.

   java -jar build/libs/wiremock-jwt-extension-1.0.0-standalone.jar

2. As an extension of the WireMock standalone JAR, e.g.

   wget -nc https://repo1.maven.org/maven2/org/wiremock/wiremock-standalone/3.0.4/wiremock-standalone-3.0.4.jar
   java \
           -cp wiremock-standalone-3.0.4.jar:build/libs/wiremock-jwt-extension-1.0.0.jar \
           wiremock.Run \
           --extensions="com.github.masonm.JwtMatcherExtension,com.github.masonm.JwtStubMappingTransformer"

3. Programmatically in Java, e.g.

   new WireMockServer(wireMockConfig()
       .extensions("com.github.masonm.JwtMatcherExtension", "com.github.masonm.JwtStubMappingTransformer"))

Request matcher usage

The extension accepts the following parameters:

• header: Key-value map of header fields to match, e.g. { "alg": "HS256" }
• payload: Key-value map of payload fields to match, e.g. { "admin": true }. If the value is an array (e.g. { "aud": ["aud1", "aud2"] }, it will be matched exactly.
• request: (legacy) Any additional request matchers. Only for Wiremock versions before 2.20 that lacked support for composing standard and custom matchers.

When using the API, make sure to set the "name" field of the customMatcher to "jwt-matcher". Here's an example cURL command that creates a stub mapping with the request matcher:

curl -d@- http://localhost:8080/__admin/mappings <<-EOD
{
    "request" : {
        "url" : "/some_url",
        "method" : "GET",
        "customMatcher" : {
            "name" : "jwt-matcher",
            "parameters" : {
                "header" : {
                    "alg" : "HS256",
                    "typ": "JWT"
                },
                "payload": {
                    "name" : "John Doe",
                    "aud": ["aud1", "aud2"]
                }
            }
        }
    },
    "response" : {
        "status" : 200,
        "body": "success"
    }
}
EOD

Example request that matches the above stub mapping:

curl -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyLCJhdWQiOlsiYXVkMSIsImF1ZDIiXX0.h49E7AnYrJpttdEoi4GmoZUCtg6GBSHTSjUcDGnbjRI' http://localhost:8080/some_url

Stub mapping transformer usage

The transformer has the name "jwt-stub-mapping-transformer" and accepts a list of payload fields to match against via the parameter "payloadFields". Example request to POST /__admin/recordings/snapshot:

{
    "transformers" : [ "jwt-stub-mapping-transformer" ],
    "transformerParameters" : {
        "payloadFields" : [ "name", "admin" ]
    }
}

Building

Run gradle jar to build the JAR without WireMock or gradle standaloneJar to build a standalone JAR. These will be placed in build/libs/.