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 aJWK
manually or by using an onlineJWK generator
. The following example shows a sampleJWK
:
{
"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 apublic key
. Keep yourprivate key
confidential. Only theRSA256
algorithm is currently supported.- If you want to configure multiple
JWKs
, thekid
field is required. If you want to configure only one JWK, thekid
field is optional. - You can configure multiple
JWKs
and usethem
together with thejwk
field. JWT (OpenID Connect) plug-ins
retrieve JWTs based on theparameter
andparameterLocation
settings.- For example, if
parameter
is set to X-Token andparameterLocation
is set to header, the JWT is read from theX-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.
- For example, if
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