RFC 7519-compliant JSON Web Token (JWT) is a simple method used by API Gateway to authenticate requests. API Gateway hosts the public JSON Web Keys (JWKs) of users and uses these JWKs to sign and authenticate JWTs in requests. Then, API Gateway forwards claims to backend services as backend parameters. This simplifies the development of backend applications.

You can use the JWT authentication plug-in to implement the original OpenID Connect feature configured on APIs. We recommend that you use the JWT authentication plug-in, which has the following advantages over the OpenID Connect feature:

  • You do not need to configure an additional authorization API. JWTs can be generated and distributed in multiple ways. API Gateway is only responsible for JWT authentication by using public JWKs.
  • JWKs without kid specified are supported.
  • Multiple JWKs can be configured.
  • You can read token information from the header of a request or a query parameter.
  • If you want to transmit a JWT in an Authorization header, such as Authorization bearer {token}, you can set parameter to Authorization and parameterLocation to header, so the token information is correctly read.
  • The jti claim-based anti-replay check is supported if you set preventJtiReplay to true.
  • Requests that do not include tokens can be forwarded to backend services without verification if you set bypassEmptyToken to true.
  • The verification on the exp setting for tokens can be skipped if you set ignoreExpirationCheck to true.

If you configure a JWT authentication plug-in and bind it to an API for which the OpenID Connect feature is configured, the JWT authentication plug-in takes effect in place of the OpenID Connect feature.

1. Obtain a JWK

RFC 7517-compliant JWK is used to sign and authenticate JWTs. If you want to configure a JWT authentication plug-in, you need to generate an available JWK manually or by using an available online JWK generator such asmkjwk.org.The following example shows an available JWK. In the JWK example, the private key is used to sign the token, and the public key is configured in the JWT authentication plug-in to authenticate the signature.

{
  "kty": "RSA",
  "e": "AQAB",
  "kid": "O9fpdhrViq2zaaaBEWZITz",
  "use": "sig",
  "alg": "RS256",
  "n": "qSVxcknOm0uCq5vGsOmaorPDzHUubBmZZ4UXj-9do7w9X1uKFXAnqfto4TepSNuYU2bA_-tzSLAGBsR-BqvT6w9SjxakeiyQpVmexxnDw5WZwpWenUAcYrfSPEoNU-0hAQwFYgqZwJQMN8ptxkd0170PFauwACOx4Hfr-9FPGy8NCoIO4MfLXzJ3mJ7xqgIZp3NIOGXz-GIAbCf13ii7kSStpYqN3L_zzpvXUAos1FJ9IPXRV84tIZpFVh2lmRh0h8ImK-vI42dwlD_hOIzayL1Xno2R0T-d5AwTSdnep7g-Fwu8-sj4cCRWq3bd61Zs2QOJ8iustH0vSRMYdP5oYQ"
}	

The preceding JWK is in JSON format. If you want to configure a JWT authentication plug-in in YAML format, you must use a JWK in YAML format.*

  • For a JWT authentication plug-in, you only need to configure a public key. Keep your private key safe. The following table lists the signature algorithms supported by the JWT authentication plug-in.
Signature algorithm Supported alg setting
RSASSA-PKCS1-V1_5 with SHA-2 RS256, RS384, RS512
Elliptic Curve (ECDSA) with SHA-2 ES256, ES384, ES512
HMAC using SHA-2 HS256, HS384, HS512

When you configure a key of the HS256, HS384, or HS512 type, the key value is base64url encoded. If the signature is invalid, check whether your key is in the same format as the key used to generate the token.

2. Plug-in configurations

You can configure a JWT authentication plug-in in JSON or YAML format because these two formats use the same schema. You can use the yaml to json tool to convert the plug-in configuration format. The following example describes a plug-in configuration template in YAML format:

---
parameter: X-Token           # The parameter from which the JWT is read. It corresponds to an API parameter. 
parameterLocation: header    # The location from which the JWT is read. Valid values: query and header. This parameter is optional if Request Mode for the bound API is set to Request Parameter Mapping. It is required if Request Mode for the bound API is set to Request Parameter Passthrough.
preventJtiReplay: false      # Controls whether to enable the anti-replay check for jti. Default value: false.
bypassEmptyToken: false      # Controls whether to forward requests that do not include tokens to backend services without verification.
ignoreExpirationCheck: false # Controls whether to ignore the verification of the exp setting.
claimParameters:             # The conversion of claims to parameters. API Gateway maps JWT claims to backend parameters.
- claimName: aud             # The name of the JWT claim, which can be public or private.
  parameterName: X-Aud       # The name of the backend parameter, to which the JWT claim is mapped.
  location: header           # The location of the backend parameter, to which the JWT claim is mapped. Valid values: query, header, path, and formData.
- claimName: userId          # The name of the JWT claim, which can be public or private.
  parameterName: userId      # The name of the backend parameter, to which the JWT claim is mapped.
  location: query            # The location of the backend parameter, to which the JWT claim is mapped. Valid values: query, header, path, and formData.
#
# Public key in the JWK
jwk:
  kty: RSA
  e: AQAB
  use: sig
  alg: RS256
  n: qSVxcknOm0uCq5vGsOmaorPDzHUubBmZZ4UXj-9do7w9X1uKFXAnqfto4TepSNuYU2bA_-tzSLAGBsR-BqvT6w9SjxakeiyQpVmexxnDw5WZwpWenUAcYrfSPEoNU-0hAQwFYgqZwJQMN8ptxkd0170PFauwACOx4Hfr-9FPGy8NCoIO4MfLXzJ3mJ7xqgIZp3NIOGXz-GIAbCf13ii7kSStpYqN3L_zzpvXUAos1FJ9IPXRV84tIZpFVh2lmRh0h8ImK-vI42dwlD_hOIzayL1Xno2R0T-d5AwTSdnep7g-Fwu8-sj4cCRWq3bd61Zs2QOJ8iustH0vSRMYdP5oYQ
#
# You can configure multiple JWKs and use them together with the jwk field.
# If multiple JWKs are configured, kid is required. If the JWT does not include kid, the consistency check on kid fails.
jwks:
- kid: O9fpdhrViq2zaaaBEWZITz 	# If only one JWK is configured, kid is optional. If the JWT includes kid, API Gateway checks the consistency of kid.
  kty: RSA
  e: AQAB
  use: sig
  alg: RS256
  n: qSVxcknOm0uCq5v....
- kid: 10fpdhrViq2zaaaBEWZITz 	# If only one JWK is configured, kid is optional. If the JWT includes kid, API Gateway checks the consistency of kid.
  kty: RSA
  e: AQAB
  use: sig
  alg: RS256
  n: qSVxcknOm0uCq5v...		
  • JWT authentication plug-ins retrieve JWTs based on the parameter and parameterLocation settings. For example, if parameter is set to X-Token and parameterLocation is set to header, the JWT is read from the X-Token header.
  • If the parameter configured in an API has the same name as the parameter specified by parameter, do not specify parameterLocation. Otherwise, an error is reported when the API is called.
  • If you want to transmit a token in an Authorization header, such as Authorization bearer {token}, you can set parameter to Authorization and parameterLocation to header, so the token information is correctly read.
  • If preventJtiReplay is set to true, the JWT authentication plug-in uses jti in claims to perform an anti-replay check.
  • If bypassEmptyToken is set to true and a token is not included in a request, API Gateway skips the check and directly forwards the request to a backend service.
  • If ignoreExpirationCheck is set to true, API Gateway skips the verification of the exp setting. Otherwise, API Gateway checks whether a token expires.
  • If API Gateway is required to forward claims in tokens to backend services, you can set tokenParameters to configure the following parameters to be forwarded:
    • claimName: the name of the claim in a token, which can be kid.
    • parameterName: the name of the parameter forwarded to a backend service.
    • location: the location of the parameter forwarded to a backend service. Valid values: header, query, path, and formData.
      • If this parameter is set to path, the backend path must contain a parameter with the same name, such as /path/{userId}.
      • If this parameter is set to formData, the body of a received request in a backend service must be of the Form type.
  • You can configure a single key in the jwk field. You can also configure multiple keys in the jwks field.
    • You can configure only one key with kid not specified.
    • You can configure multiple keys with kid specified. kid must be unique.

3. Verification rules

  • A JWT authentication plug-in obtains tokens based on parameter and parameterToken settings. If API Gateway is required to forward requests to backend services even when tokens are not included in the requests, set bypassEmptyToken to true.
  • If you want to configure multiple keys, abide by the following principles:
    • Preferentially select a key whose ID is the same as the value of kid in a token for signature and authentication.
    • You can configure only one key with kid not specified. If there is no key whose ID is the same as the value of kid in a token, use the key with kid not specified for signature and authentication.
    • If all the configured keys have specified kid settings, and the token in a request does not contain kid or no keys match kid, an A403JK error is reported.
  • If a token contains iat, nbf, and exp, the JWT authentication plug-in verifies the validity of the time format.
  • By default, API Gateway verifies the exp setting. If you want to skip the verification, set ignoreExpirationCheck to true.
  • tokenParameters is configured to extract the required parameters from the claims of a token. These parameters are forwarded to backend services.

4. Configuration examples

4.1 Configure a single JWK

---
parameter: X-Token         # The parameter from which the JWT is read. It corresponds to an API parameter.
parameterLocation: header  # The location from which the JWT is read. Valid values: query and header. This parameter is optional if Request Mode for the bound API is set to Request Parameter Mapping. It is required if Request Mode for the bound API is set to Request Parameter Passthrough.
claimParameters:           # The conversion of claims to parameters. API Gateway maps JWT claims to backend parameters.
- claimName: aud           # The name of the JWT claim, which can be public or private.
  parameterName: X-Aud     # The name of the backend parameter, to which the JWT claim is mapped.
  location: header         # The location of the backend parameter, to which the JWT claim is mapped. Valid values: query, header, path, and formData.
- claimName: userId        # The name of the JWT claim, which can be public or private.
  parameterName: userId    # The name of the backend parameter, to which the JWT claim is mapped.
  location: query          # The location of the backend parameter, to which the JWT claim is mapped. Valid values: query, header, path, and formData.
preventJtiReplay: false    # Controls whether to enable the anti-replay check for jti. Default value: false.
#
# Public key in the JWK
jwk:
  kty: RSA
  e: AQAB
  use: sig
  alg: RS256
  n: qSVxcknOm0uCq5vGsOmaorPDzHUubBmZZ4UXj-9do7w9X1uKFXAnqfto4TepSNuYU2bA_-tzSLAGBsR-BqvT6w9SjxakeiyQpVmexxnDw5WZwpWenUAcYrfSPEoNU-0hAQwFYgqZwJQMN8ptxkd0170PFauwACOx4Hfr-9FPGy8NCoIO4MfLXzJ3mJ7xqgIZp3NIOGXz-GIAbCf13ii7kSStpYqN3L_zzpvXUAos1FJ9IPXRV84tIZpFVh2lmRh0h8ImK-vI42dwlD_hOIzayL1Xno2R0T-d5AwTSdnep7g-Fwu8-sj4cCRWq3bd61Zs2QOJ8iustH0vSRMYdP5oYQ
			

4.2 Configure multiple JWKs

---
parameter: Authorization   # The parameter from which the token is obtained. 
parameterLocation: header  # The location from which the token is obtained.
claimParameters:           # The conversion of claims to parameters. API Gateway maps JWT claims to backend parameters.
- claimName: aud           # The name of the JWT claim, which can be public or private.
  parameterName: X-Aud     # The name of the backend parameter, to which the JWT claim is mapped.
  location: header         # The location of the backend parameter, to which the JWT claim is mapped. Valid values: query, header, path, and formData.
- claimName: userId        # The name of the JWT claim, which can be public or private.
  parameterName: userId    # The name of the backend parameter, to which the JWT claim is mapped.
  location: query          # The location of the backend parameter, to which the JWT claim is mapped. Valid values: query, header, path, and formData.
preventJtiReplay: true     # Controls whether to enable the anti-replay check for jti. Default value: false.
jwks:
- kid: O9fpdhrViq2zaaaBEWZITz 	# kid must be set to different values for multiple different JWKs.
  kty: RSA
  e: AQAB
  use: sig
  alg: RS256
  n: qSVxcknOm0uCq5v....
- kid: 10fpdhrViq2zaaaBEWZITz 	# kid must be set to different values for multiple different JWKs.
  kty: RSA
  e: AQAB
  use: sig
  alg: RS256
  n: qSVxcknOm0uCq5v....

5. Error codes

Status Code Message Description
400 I400JR JWT required No JWT-related parameters are found.
403 S403JI Claim jti is required when preventJtiReplay:true If preventJtiReplay is set to true in a JWT authentication plug-in, no valid jti claim is included in the request.
403 S403JU Claim jti in JWT is used If preventJtiReplay is set to true in a JWT authentication plug-in, the jti claim that is included in the request is used.
403 A403JT Invalid JWT: ${Reason} The JWT that is read from the request is invalid.
400 I400JD JWT Deserialize Failed: ${Token} The JWT that is read from the request fails to be parsed.
403 A403JK No matching JWK, kid:${kid} not found There is no JWK that matches kid configured in the JWT included in the request.
403 A403JE JWT is expired at ${Date} The JWT that is read from the request expires.
400 I400JP Invalid JWT plugin config: ${JWT} The JWT authentication plug-in is incorrectly configured.

If an HTTP response message includes an unexpected response code specified by ErrorCode in the X-Ca-Error-Code header, such as A403JT or I400JD, you can visit thejwt.iowebsite to check the token validity and format.

6. Limits

  • The metadata of a JWT authentication plug-in contains a maximum of 16,380 characters.
  • You can configure a maximum of 16 parameters to be forwarded. Both the claimName and parameterName parameters cannot exceed 32 characters in length. Only the following regular expression is supported: [A-Za-z0-9-_].
  • alg can be set to RS256, RS384, RS512, ES256, ES384, ES512, HS256, HS384, or HS512 for JWKs.