JWT (JSON Web Token) is a commonly used authentication and authorization method in modern Web services. Kong can verify requests with JWT signed using HS256 or RS256. You can configure JWT credentials (public and private keys) for consumers and sign their JWT with these credentials. Kong supports passing JWT tokens via Query, Cookie, or Header. If the JWT signature is verified, Kong proxies the request to the upstream service; otherwise, it discards the request.
The three common JWT signature algorithms are HS256, RS256, and ES256. They differ in the keys required for message signing and signature verification.
HS256 uses the same secret_key for signature and verification. It is suitable for centralized authentication scenarios where both signature and verification should be performed by a credible party.
RS256 uses an RSA private key for signature and an RSA public key for verification. Therefore, verification can be delegated to other applications.
ES256 uses a private key for signature and a public key for verification and has a shorter signature than RS256.
This document describes how to implement the following common JWT authentication and authorization scenarios on a Kong cloud-native gateway using the JWT plugin:
Authenticating and authorizing requests with the HS256 signature
Authenticating and authorizing requests with the RS256 signature
Prerequisites
The gateway instance has been purchased. For details, see Create Gateway.
The service (Service) and route (Route) have been configured.
Plugin Configurations
Field Name
Field Description
uri param names
List of Query parameters used to obtain the JWT token. This field is configured when the JWT token is configured in the URI.
cookies names
A list of Cookie parameters for obtaining the JWT Token. Set this property when the JWT Token is configured in a Cookie.
key claim name
Key value of the credential, corresponding to the JWT Claim content, which is set to iss by default.
secret is base64
Whether the secret of the credential is base64-encoded.
claims to verify
Claims verified by Cloud Native API Gateway, which can be exp or nbf.
anonymous
Determines whether to treat the request as an anonymous Consumer upon authentication failure. The default value is empty, indicating that a 4xx response is returned when the request fails.
run on preflight
Whether the plugin should run its logic on OPTIONS preflight requests (and attempt to authenticate the identity). If it is set to false, OPTIONS requests are always allowed.
maximum expiration
JWT token expiration time, ranging from 0 to 31536000 (365 days). When this field is specified, you need to specify exp in claims to verify. The default value is 0, indicating indefinite. When the token expires, the request is denied with HTTP 403. Note that potential clock drift should be considered when this field is configured.
header names
List of header parameters used to obtain the JWT token. This field is configured when the JWT token is configured in the URI.
Operation Steps
Scenario 1: Authenticating and Authorizing Requests with the HS256 Signature
2. Select Cloud Native Gateway in the left sidebar and click the target instance to go to the instance details.
3. On the Basic Information page, click the Konga console Tag to view the management console login method.
4. Log in to the Konga console, go to the Consumer details page, and select the user (such as clare) for whom access control needs to be configured. Click the Credentials Tab, select JWT, and click Create JWT to create a JWT Token as the access credential for the user.
5. Configure JWT-related parameters.
Configuration Item
Description
key
Corresponding to the issuer of JWT Claims. If it is not specified, a key is generated automatically.
algorithm
Encryption algorithm used for the JWT token signature, which can be HS256 or RS256. In this scenario, it is set to HS256.
secret
Secret set for signature verification when the signature algorithm is HS256. If it is not specified, a secret is generated automatically.
6. View the generated user credentials.
7. Generate the corresponding JWT Token using a program.
Step 2: Binding the JWT Plugin
1. Go to the Service that requires authentication, click ADD PLUGIN, select the JWT plugin from the Authentication group in the plugin marketplace, and click Add Plugin.
2. Fill in the JWT Token verification information and click ADD PLUGIN.
Step 3: Testing Requests
1. Send a request without a JWT token to the service. The request is denied, and 401 is returned.
curl-i xxxxxxx/test
HTTP/1.1 401 Unauthorized
Connection: keep-alive
Content-Length: 26
Content-Type: application/json;charset=utf-8
Date: Tue, 29 Nov 202212:55:33 GMT
Server: kong/2.5.1
X-Kong-Response-Latency: 23
{"message":"Unauthorized"}
2. Send a request with a JWT token to the service. The request is successful.
2. Select Cloud Native Gateway in the left sidebar and click the target instance to go to the instance details.
3. On the Basic Information page, click the Konga console Tag to view the management console login method.
4. Log in to the Konga console, go to the Consumer details page, and select the user (such as clare) for whom access control needs to be configured. Click the Credentials Tab, select JWT, and click Create JWT to create a JWT Token as the access credential for the user.
5. Configure JWT-related parameters.
Configuration Item
Description
key
Corresponding to the issuer of JWT Claims. If it is not specified, a key is generated automatically.
algorithm
Encryption algorithm used for JWT token signature, which can be HS256 or RS256. In this scenario, it is set to RS256.
rsa_public_key
Public key (PEM format) set for signature verification when the signature algorithm is RS256.
secret
Private key (PEM format) set for signature verification when the signature algorithm is RS256.
6. View the generated user credentials.
7. Generate the corresponding JWT Token.
Step 2: Binding the JWT Plugin
1. Go to the Service that requires authentication, click ADD PLUGIN, select the JWT plugin from the Authentication group in the plugin marketplace, and click Add Plugin.
2. Fill in the JWT Token verification information and click ADD PLUGIN.
Step 3: Testing Requests
1. Send a request without a JWT token to the service. The request is denied, and 401 is returned.
curl-i xxxxxxx/testrsa
HTTP/1.1 401 Unauthorized
Connection: keep-alive
Content-Length: 26
Content-Type: application/json;charset=utf-8
Date: Tue, 29 Nov 202212:55:33 GMT
Server: kong/2.5.1
X-Kong-Response-Latency: 23
{"message":"Unauthorized"}
2. Send a request with a JWT token to the service. The request is successful.
