Skip to content

Overview#

Build Status Maven Central

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/.