https://github.com/masonm/wiremock-jwt-extension
WireMock extension for matching requests with JSON Web Tokens (JWT)
https://github.com/masonm/wiremock-jwt-extension
jwt wiremock
Last synced: about 1 year ago
JSON representation
WireMock extension for matching requests with JSON Web Tokens (JWT)
- Host: GitHub
- URL: https://github.com/masonm/wiremock-jwt-extension
- Owner: MasonM
- License: other
- Created: 2017-08-05T07:42:56.000Z (almost 9 years ago)
- Default Branch: master
- Last Pushed: 2023-09-16T19:11:48.000Z (over 2 years ago)
- Last Synced: 2025-04-12T23:37:28.361Z (about 1 year ago)
- Topics: jwt, wiremock
- Language: Java
- Homepage:
- Size: 247 KB
- Stars: 15
- Watchers: 2
- Forks: 13
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Overview
[](https://github.com/MasonM/wiremock-jwt-extension/actions/workflows/gradle.yml?query=branch%3Amaster)
[](https://maven-badges.herokuapp.com/maven-central/com.github.masonm/wiremock-jwt-extension)
wiremock-jwt-extension consists of two extensions for [WireMock](http://wiremock.org): a [request matcher extension](http://wiremock.org/docs/extending-wiremock/#custom-request-matchers) and a [stub mapping transformer extension](http://wiremock.org/docs/record-playback/#transforming-generated-stubs).
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:
```xml
com.github.masonm
wiremock-jwt-extension
1.0.0
```
Gradle:
```groovy
implementation 'com.github.masonm:wiremock-jwt-extension:1.0.0'
```
# Running
There are three ways of running the extension:
1. Standalone, e.g.
```sh
java -jar build/libs/wiremock-jwt-extension-1.0.0-standalone.jar
```
2. As an extension of the WireMock standalone JAR, e.g.
```sh
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.
```java
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:
```sh
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:
```sh
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`:
```json
{
"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/`.