JWT authentication

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 as mkjwk.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.

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

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 the jwt.io website 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.