JSON Web Token (JWT) - Plugin| Alibaba Cloud Documentation Center

JSON Web Token (JWT) (RFC7519) is a simple authentication method. API Gateway can host the public JSON Web Keys (JWK) of users and use these JWKs to verify and sign the JWTs in the users’ requests. This makes users’ development work easier.

Now, you can use JWT (OpenID Connect) plug-ins to implement the original OpenID Connect feature. If you configure a JWT (OpenID Connect) plug-in and bind it to an API for which the OpenIdConnect feature has been configured, the JWT (OpenID Connect) plug-in takes effect in place of the originalOpenID Connect feature.

Usage instructions

To configure a JWT (OpenID Connect) plug-in, you need to generate a JWK manually or by using an online JWK generator. The following example shows a sample JWK:

{
  "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 the JSON format. To configure a JWT (OpenID Connect) plug-in in the YAML format, you must use a JWK in the YAML format*

For a JWT (OpenID Connect) plug-in, you only need to configure a public key. Keep your private key confidential. Only the RSA256 algorithm is currently supported.
If you want to configure multiple JWKs, the kid field is required. If you want to configure only one JWK, the kid field is optional.
You can configure multiple JWKs and use them together with the jwk field.
JWT (OpenID Connect) plug-insretrieve 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 corresponding parameter configured in an API has the same name as the parameter configured in parameter, parameterLocation can be ignored to avoid errors when the API is called.

Plug-in configurations

You can configure JWT (OpenID Connect) plug-ins in the JSON or YAML format as these two formats use the same schema. You can use the yaml to json tool to convert the configuration format of a JWT (OpenID Connect) plug-in. The following table describes a plug-in configuration template in the 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 when Request Mode for the bound API is set to Request Parameter Mapping. It is required when 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 a JWT claim, which can be public or private.
  parameterName: X-Aud     # The name of the backend parameter that the JWT claim is mapped to.
  location: header         # The location of the backend parameter that the JWT claim is mapped to. Valid values: query, header, path, and formData.
- claimName: userId        #The name of a JWT claim, which can be public or private. 
  parameterName: userId    # The name of the backend parameter that the JWT claim is mapped to.
  location: query          # The location of the backend parameter that the JWT claim is mapped to. Valid values: query, header, path, and formData.
preventJtiReplay: false    # Controls whether to enable the anti-replay check for jti (JWT ID). Default value: false.
#
# Public key in the JWK
jwk:                    
  kty: RSA
  e: AQAB
  use: sig
  kid: O8fpdhrViq2zaaaBEWZITz   # The kid field is optional when only one JWK is configured. If the JWT contains a kid field, API Gateway checks whether the kid fields are consistent.
  alg: RS256
  n: qSVxcknOm0uCq5vGsOmaorPDzHUubBmZZ4UXj-9do7w9X1uKFXAnqfto4TepSNuYU2bA_-tzSLAGBsR-BqvT6w9SjxakeiyQpVmexxnDw5WZwpWenUAcYrfSPEoNU-0hAQwFYgqZwJQMN8ptxkd0170PFauwACOx4Hfr-9FPGy8NCoIO4MfLXzJ3mJ7xqgIZp3NIOGXz-GIAbCf13ii7kSStpYqN3L_zzpvXUAos1FJ9IPXRV84tIZpFVh2lmRh0h8ImK-vI42dwlD_hOIzayL1Xno2R0T-d5AwTSdnep7g-Fwu8-sj4cCRWq3bd61Zs2QOJ8iustH0vSRMYdP5oYQ
#
# You can configure a maximum of five JWKs and use them together with the jwk field.
# When multiple JWKs are configured, the kid field is required. If the JWT does not contain a kid field, the consistency check on the kid field fails.
jwks:
- jwk:
    kty: RSA
    e: AQAB
    use: sig
    kid: O9fpdhrViq2zaaaBEWZITz   # The kid field is optional when only one JWK is configured. If the JWT contains a kid field, API Gateway checks whether the kid fields are consistent.
    alg: RS256
    n: qSVxcknOm0uCq5vGsOmaorPDzHUubBmZZ4UXj-9do7w9X1uKFXAnqfto4TepSNuYU2bA_-tzSLAGBsR-BqvT6w9SjxakeiyQpVmexxnDw5WZwpWenUAcYrfSPEoNU-0hAQwFYgqZwJQMN8ptxkd0170PFauwACOx4Hfr-9FPGy8NCoIO4MfLXzJ3mJ7xqgIZp3NIOGXz-GIAbCf13ii7kSStpYqN3L_zzpvXUAos1FJ9IPXRV84tIZpFVh2lmRh0h8ImK-vI42dwlD_hOIzayL1Xno2R0T-d5AwTSdnep7g-Fwu8-sj4cCRWq3bd61Zs2QOJ8iustH0vSRMYdP5oYQ
- jwk:
    kty: RSA
    e: AQAB
    use: sig
    kid: 10fpdhrViq2zaaaBEWZITz   # The kid field is optional when only one JWK is configured. If the JWT contains a kid field, API Gateway checks whether the kid fields are consistent.
    alg: RS256
    n: qSVxcknOm0uCq5vGsOmaorPDzHUubBmZZ4UXj-9do7w9X1uKFXAnqfto4TepSNuYU2bA_-tzSLAGBsR-BqvT6w9SjxakeiyQpVmexxnDw5WZwpWenUAcYrfSPEoNU-0hAQwFYgqZwJQMN8ptxkd0170PFauwACOx4Hfr-9FPGy8NCoIO4MfLXzJ3mJ7xqgIZp3NIOGXz-GIAbCf13ii7kSStpYqN3L_zzpvXUAos1FJ9IPXRV84tIZpFVh2lmRh0h8ImK-vI42dwlD_hOIzayL1Xno2R0T-d5AwTSdnep7g-Fwu8-sj4cCRWq3bd61Zs2QOJ8iustH0vSRMYdP5oYQ