JWT Authentication

Notes and Constraints

• An API can be bound to only one JWT authentication policy for a given environment, but each JWT authentication policy can be bound to multiple APIs.
• You can create a maximum of five JWT authentication policies for an APIG gateway. To adjust the quota, submit a service ticket.
• You need to generate a public-private key pair using a tool or platform, configure the public key in the JWT authentication policy, and use the private key to generate a token. Keep the private key secure.
• The token carried in the request must comply with RFC 7519. The public key configured in the JWT authentication policy must be a JSON string that complies with RFC 7517.
• JWT does not encrypt data. Do not set sensitive data in tokens. To prevent token leakage, you are advised not to use JWT authentication for APIs whose request protocol is HTTP.
• Token verification supports the following encryption algorithms: RS256, RS384, RS512, ES256, ES384, and ES512. When the RSA algorithm is used, it is recommended that the key length be greater than or equal to 3,072 bits.
• The maximum size of the public key returned by JWKS_URI and the fixed public key is 50 KB.
• APIG verifies the nbf (time when the token takes effect) and exp (token expiration time) fields in the token. If the verification fails, the request is rejected.
• If the public key is set to be periodically pulled, ensure that JWKS_URI and the APIG gateway can communicate with each other. The scheduled task in APIG requests JWKS_URI every 5 minutes. The returned response body is used as the public key, and the result of the current request overwrites the result of the previous request. If you want to rotate the public and private keys, you are advised to reserve a grace period each time when the keys are rotated. In this way, JWKS_URI returns the new public key and the old public key that is replaced during the rotation, so that the tokens issued by the new and old private keys are valid in this period.
• The gateway matches and verifies the signature based on the kid in the token and the JWKS public key. If the JWKS contains only one JWK, the kid can be empty. Otherwise, the kid cannot be empty. The kid of any two JWKs in the JWKS must be different. If kid is not set, the token issued before the public and private keys are replaced cannot be verified.
• Policies are independent of APIs. A policy takes effect for an API only after they are bound to each other. When binding a policy to an API, you must specify an environment where the API has been published. The policy takes effect for the API only in the specified environment.
• After you bind a policy to an API, unbind the policy from the API, or update the policy, you do not need to publish the API again.
• Taking an API offline does not affect the policies bound to it. The policies are still bound to the API if the API is published again.
• Policies that have been bound to APIs cannot be deleted.

Creating a JWT Authentication Policy

1. Go to the APIG console.
2. Select a dedicated gateway at the top of the navigation pane.
3. In the navigation pane, choose API Management > API Policies.
4. On the Policies tab, click Create Policy.
5. In the Select Policy Type box, select JWT Authentication in the Plug-ins area.
6. Set the policy information based on the following table.

   Table 1 JWT authentication parameters

   Parameter	Description
   Name	Enter a policy name. Using naming rules facilitates future search.
   Type	The value is fixed as JWT Authentication.
   Description	Enter the description of the policy. Enter 1 to 255 characters.
   Policy Content	Content of the plug-in, which can be configured in a form or using a script.
   Retrieval Mode	Mode of obtaining the public key. Scheduled: The gateway requests JWKS_URI every 5 minutes to obtain a public key. Fixed: The gateway uses the entered JWKS value as the public key.
   JWKS_URI	This parameter is mandatory only when Scheduled is selected for Retrieval Mode. URI of the JWKS public key returned in the response. The public key must be a JSON string that complies with the RFC 7517 specification. Ensure that the JWKS_URI and APIG gateway can communicate with each other. The scheduled task in the gateway requests JWKS_URI every 5 minutes, uses the returned response body as the public key, and overwrites the previous request result with the current request result. Gateway request URI method is GET. If no request protocol is specified, HTTPS is used. The returned JWKS size supports a maximum of 50 KB.
   JWKS	This parameter is mandatory only when Fixed is selected for Retrieval Mode. JWKS public key for verifying the token. The value must be a JSON character string that complies with the RFC 7517 specifications. The maximum size is 50 KB.
   Timeout	This parameter is mandatory only when Scheduled is selected for Retrieval Mode. The max. duration for the gateway to request the JWKS service (1–60,000 ms), in milliseconds.
   Cache Duration	This parameter is mandatory only when Scheduled is selected for Retrieval Mode. It indicates how long the gateway will cache the returned JWKS (600–86,400 seconds).
   Host Header	This parameter is mandatory only when Scheduled is selected for Retrieval Mode. The host and port number of the server to which a request is sent. By default, the original Host header of a request is used.
   Location	Location of the token parameter. The options are header, query, and cookie.
   Name	Token parameter name. When the location is header, the default value is Authorization. The value is case-insensitive. When the location is query, the default value is access_token. This parameter is mandatory when the location is cookie. The value is case-insensitive.
   Prefix	This parameter is mandatory only when the location is header. The prefix will be removed before the token is used for authentication. The default value is Bearer.
   Clock Skew for Token Expiration	If the expiration time (exp) is set for the token in the payload, you can customize the clock skew (0-86,400 seconds) for verifying whether the token expires.
   Forward Token to Backend	Whether the original token can be transparently transmitted to the backend. The default value is false.
   Skip Authentication If Token Absent	Whether to allow direct access to the backend without JWT authentication when the request does not contain a token.
   Ignore Expiration Validity Check	Whether the gateway can ignore the exp field value of the token. The default value is false.
   Forward Payload to Backend	Whether the gateway can forward the payload parsed from the token to the backend. The default value is false.
   Payload Request Header	This parameter is mandatory only if Forward Payload to Backend is enabled. Request header name to which the payload parsed from the token will be written. This parameter is case-insensitive.
   Fields to Forward to Backend	The gateway sets the value of the specified field (claim) in the payload to the request header and sends the request header to the backend. You can set is_override to determine whether to rewrite the request header with the same name. If is_override is set to true, the value of the request header with the same name will be overwritten. If is_override is set to false, the request header with the same name will be appended. is_override is set to true by default. A maximum of 16 field values can be transferred to the backend.
   Blacklist	The gateway performs verification on the value of a specified field in payload based on the blacklist. If the key-value pair corresponding to claim in payload matches any rule in the blacklist configuration, that is, the value of claim is the same as the field value entered in a rule, the request is rejected.

Example Script

{
    "jwks_service": {
        "uri": "https://example.com",
        "timeout": 5000,
        "ttl": 7200,
        "custom_host": "xxx.xxx"
    },
    "jwks": "{\"keys\":[{\"kty\": \"EC\",\"crv\": \"P-256\",\"x\": \"MKBCTNIcKUSDii11ySs3526iDZ8AiTo7Tu6KPAqv7D4\",\"y\": \"4Etl6SRW2YiLUrN5vfvVHuhp7x8PxltmWWlbbM4IFyM\",\"use\": \"enc\",\"kid\": \"1\"}] }",
    "token_location": "header",
    "token_name": "Authorization",
    "token_prefix": "Bearer",
    "token_expiration_tolerance": 0,
    "token_pass_through_enabled": true,
    "missing_token_skip_auth_enabled": false,
    "ignore_expiration_validation_enabled": false,
    "claims_to_headers": [
        {
            "claim": "iat",
            "header": "iat_value",
            "is_override": true
        },
        {
            "claim": "sub",
            "header": "sub_value",
            "is_override": false
        }
    ],
    "blacklist": [
        {
            "claim": "iat",
            "value": ""
        },
        {
            "claim": "sub",
            "value": "test"
        }
    ]
}