kryshakm/jwt repository overview

⁠Description

A simple web application to create and verify JSON Web Tokens (JWT). Support is currently limited to JSON Web Signature (JWS) and not JSON Web Encryption (JWE).

⁠Usage

All JWTs that are created will contain at least the following claims:

• aud, exp, iat, and iss

Although these claims are all optional as defined by RFC 5741⁠, all JWTs inspected by the application for verification must contain these claims.

⁠Creating a JWT

To create a JWT without any client specific information, simply create a POST request to the /create endpoint.

⁠Example:

[user@host]# curl -s http://localhost/create -X POST | jq
{
  "code": 201,
  "token": "eyJhbGciOiJIUzI1NiIsImtpZCI6IjAwMSIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJleGFtcGxlLmNvbSIsImlhdCI6MTYxMDQwMjQxNywiZXhwIjoxNjEwNDA2MDE3LCJhdWQiOiJleGFtcGxlLmNvbSJ9.g2gwfU3AkDhSSinwwpaiTQeMaGzEBAwTtS-0ylCJ7Fg"
}

To create a JWT with specific client information to be encoded as a claim, create a POST request to the /create endpoint with the Content-Type header set to application/json and a JSON encoded request body. The JSON key/value pairs will be encoded as claims.

⁠Example:

[user@host]# curl -s http://localhost/create -X POST -H "Content-Type: application/json" -d '{"email":"[email protected]","name":"user"}' | jq
{
  "code": 201,
  "token": "eyJ0eXAiOiJKV1QiLCJraWQiOiIwMDEiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJleGFtcGxlLmNvbSIsImV4cCI6MTYxMDQwNjA4NywiZW1haWwiOiJ1c2VyQGV4YW1wbGUuY29tIiwibmFtZSI6InVzZXIiLCJpYXQiOjE2MTA0MDI0ODcsImF1ZCI6ImV4YW1wbGUuY29tIn0.aB8sMfR0idbTutV6KJVpiRX-KbqteSSoakF0cZsDIDQ"
}

⁠Verifying a JWT

In order to verify an existing JWT, the client must send the token as part of a specific request header or JSON encoded requst body. The order of operation in which tokens are located in the request is as follows:

1. Authorization header using the format Authorization: Bearer <jwt>
   • Custom header(s) specified in the JWT_TOKEN environment variable
2. Cookie header with the name auth_token
   • Custom cookie(s) specified in the JWT_TOKEN environment variable
3. JSON encoded request body with key token
   • Custom JSON key(s) specified in the JWT_TOKEN environment variable

Once a JWT is located in the request, searching ceases immediately and the token is processed for verification.

To verify a JWT using the Authorization header, send a GET request to the /verify endpoint using the format Authorization: Bearer <jwt>.

⁠Example:

[user@host]# curl -s http://localhost/verify -H "Authorization: Bearer eyJraWQiOiIwMDEiLCJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE2MTA0MDI0MTEsImlzcyI6ImV4YW1wbGUuY29tIiwiYXVkIjoiZXhhbXBsZS5jb20iLCJleHAiOjE2MTA0MDYwMTF9.bkG47ODMf9X77GcRZAIXf2E-fzPWI-C4N04lkaJxayI" | jq
{
  "claims": {
    "iat": 1610402411,
    "iss": "example.com",
    "aud": "example.com",
    "exp": 1610406011
  },
  "code": 200
}

To verify a JWT using the Cookie header, send a GET request to the /verify endpoint using the format Cookie: auth_token=<jwt>.

⁠Example:

[user@host]# curl -s http://localhost/verify -H "Cookie: auth_token=eyJraWQiOiIwMDEiLCJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE2MTA0MDI0MTEsImlzcyI6ImV4YW1wbGUuY29tIiwiYXVkIjoiZXhhbXBsZS5jb20iLCJleHAiOjE2MTA0MDYwMTF9.bkG47ODMf9X77GcRZAIXf2E-fzPWI-C4N04lkaJxayI" | jq
{
  "claims": {
    "iat": 1610402411,
    "iss": "example.com",
    "aud": "example.com",
    "exp": 1610406011
  },
  "code": 200
}

To verify a JWT using a JSON encoded request body, send a POST request to the /verify endpoint with the Content-Type header set to application/json and a JSON key token set to the token value.

⁠Example:

[user@host]# curl -s http://localhost/verify -X POST -H "Content-Type: application/json" -d '{"token":"eyJraWQiOiIwMDEiLCJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE2MTA0MDI0MTEsImlzcyI6ImV4YW1wbGUuY29tIiwiYXVkIjoiZXhhbXBsZS5jb20iLCJleHAiOjE2MTA0MDYwMTF9.bkG47ODMf9X77GcRZAIXf2E-fzPWI-C4N04lkaJxayI"}' | jq
{
  "claims": {
    "iat": 1610402411,
    "iss": "example.com",
    "aud": "example.com",
    "exp": 1610406011
  },
  "code": 200
}

⁠Configuration

The application can be configured by passing environment variables to the container.

⁠BASE_PATH

• Value: uri path
• Type: string
• Default: /
• Example: BASE_PATH=/api/jwt/
• Usage:

⁠JWT_ALG

• Value:
  • HS256, HS384, HS512
  • RS256, RS384, RS512
  • PS256, PS384, PS512
  • ES256, ES256K, ES384, ES512
  • EdDSA
• Type: string
• Default: HS256
• Example: JWT_ALG=RS256
• Usage:

⁠JWT_AUD

• Value: aud claim
• Type: string
• Default: example.com
• Example: JWT_AUD=my.example.com
• Usage:

⁠JWT_CLAIMS

• Value: claims
• Type: json string
• Default: null
• Example: JWT_CLAIMS='{"groups":["admin","everyone"]}'

⁠JWT_EXP

• Value: exp claim
• Type: int
• Default: 3600
• Example: JWT_EXP=7200
• Usage:

⁠JWT_ISS

• Value: iss claim
• Type: string
• Default: example.com
• Example: JWT_AUD=my.example.com
• Usage:

⁠JWT_JWK

• Value: jwks file
• Type: string
• Default: null
• Example: JWT_JWK=./keys/jwks/keys.jwks
• Usage:

⁠JWT_KEY

• Value:
  • hmac jwk file, hmac secret
  • rsa jwk file, rsa key file
  • ec jwk file, ec key file
  • ed jwk file, ed key file
• Type: string
• Default: example123
• Example: JWT_KEY=hmac_secret or JWT_KEY=./keys/rsa/rs256/rsa.key
• Usage:

⁠JWT_KID

• Value: key id
• Type: string
• Default: 001
• Example: JWT_KID=002
• Usage:

⁠JWT_MUTE_CLAIMS

• Value: claims
• Type: json string
• Default: null
• Example: JWT_MUTE_CLAIMS='["email","username"]'
• Usage

⁠JWT_SUB

• Value: claim name
• Type: string
• Default: null
• Example: JWT_SUB=email
• Usage

⁠JWT_TOKEN

• Value: json object
• Type: string
• Default: null
• Example: JWT_TOKEN='{"header":["x-jwt"],"cookie":["jwt"],"body":["jwt"]}';
• Usage

⁠Signing Keys

The follownig sample signing keys are included in the /var/www/keys (or relative path ./keys) directory.

A matching JWKS file is located at /var/www/keys/jwks/keys.jwks (or relative path ./keys/jwks/keys.jwks).

⁠Notes

There are two versions of this container image to allow for execution in unprivileged environments.