JWT

The JWT plugin lets you verify requests containing HS256 or RS256 signed JSON Web Tokens, as specified in RFC 7519.

When you enable this plugin, it grants JWT credentials (public and secret keys) to each of your Consumers, which must be used to sign their JWTs. You can then pass a token through any of the following:

• A query string parameter
• A cookie
• HTTP request headers

Kong Gateway will either proxy the request to your upstream services if the token’s signature is verified, or discard the request if not. Kong Gateway can also perform verifications on some of the registered claims of RFC 7519 (exp and nbf). If Kong Gateway finds multiple tokens that differ - even if they are valid - the request will be rejected to prevent JWT smuggling.

To use the plugin, you need to do the following:

1. Create a Consumer and associate one or more JWT credentials (holding the public and private keys used to verify the token) to it. The Consumer represents a developer using the final upstream service.

2. Create a JWT credential for the Consumer, either with the /consumers/{consumer}/jwt endpoint or by specifying jwt_secrets: for the Consumer in a declarative config file.

   Note for decK and Kong Ingress Controller users: The declarative configuration used in decK and the Kong Ingress Controller imposes some additional validation requirements that differ from the requirements listed above. Because they cannot rely on defaults and do not implement their own algorithm-specific requirements, all fields other than rsa_public_key fields are required.
   
   You should always fill out key, algorithm, and secret. If you use any RS, ES, or PS algorithm, use a dummy value for secret. In Kong Gateway 3.6 or earlier, you use the RS256 or ES256 algorithm instead.

3. Sign your JWT following RFC 7519 standards.
4. Enable the JWT plugin.
5. The JWT can now be included in a request to Kong Gateway. Kong Gateway only proxies requests that include a valid signature, provided they don’t include an invalid verified claim (optionally configured with config.claims_to_verify).

For an end-to-end tutorial on this, see Authenticate Consumers with JWT.

If you want to use RS256 or ES256 to verify your JWTs, then when creating a JWT credential, select RS256 or ES256 as the algorithm, and explicitly upload the public key in the rsa_public_key field (including for ES256 signed tokens). For example, rsa_public_key=@/path/to/public_key.pem.

When creating the signature, make sure that the header is:

{
    "typ": "JWT",
    "alg": "RS256"
}

Secondly, the claims must contain the secret’s key field (this isn’t your private key used to generate the token, but just an identifier for this credential) in the configured claim (from config.key_claim_name). That claim is iss (issuer field) by default. Set its value to our previously created credential’s key. The claims may contain other values. The claim is searched in both the JWT payload and header, in that order.

{
    "iss": "a36c3049b36249a3c9f8891cb127243c"
}

Then, create the signature using your private keys. Using the JWT debugger at jwt.io, set the right header (RS256), the claims (iss, etc.), and the associated public key. Then, append the resulting value in the Authorization header, for example:

curl http://localhost:8000/{routePath} \
  -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiIxM2Q1ODE0NTcyZTc0YTIyYjFhOWEwMDJmMmQxN2MzNyJ9.uNPTnDZXVShFYUSiii78Q-IAfhnc2ExjarZr_WVhGrHHBLweOBJxGJlAKZQEKE4rVd7D6hCtWSkvAAOu7BU34OnlxtQqB8ArGX58xhpIqHtFUkj882JQ9QD6_v2S2Ad-EmEx5402ge71VWEJ0-jyH2WvfxZ_pD90n5AG5rAbYNAIlm2Ew78q4w4GVSivpletUhcv31-U3GROsa7dl8rYMqx6gyo9oIIDcGoMh3bu8su5kQc5SQBFp1CcA5H8sHGfYs-Et5rCU2A6yKbyXtpHrd1Y9oMrZpEfQdgpLae0AfWRf6JutA9SPhst9-5rn4o3cdUmto_TBGqHsFmVyob8VQ'

When a client has been authenticated, the plugin appends some headers to the request before proxying it to the upstream service, so that you can identify the Consumer in your code:

• X-Consumer-ID: The ID of the Consumer in Kong Gateway.
• X-Consumer-Custom-ID: The custom_id of the Consumer (if set).
• X-Consumer-Username: The username of the Consumer (if set).
• X-Credential-Identifier: The identifier of the credential (only if the Consumer is not the anonymous Consumer).
• X-Anonymous-Consumer: Is set to true if authentication fails, and the anonymous Consumer is set instead.

You can use this information on your side to implement additional logic. You can use the X-Consumer-ID value to query the Admin API and retrieve more information about the Consumer.