x-yc-apigateway-authorizer:jwt extension

The x-yc-apigateway-authorizer:jwt extension is used within the securityScheme component schemas of the OpenId Connect type. For HTTP request authorization, API Gateway validates a token and verifies its signature using public keys the extension refers to. You can learn more about the JWT standard here.

Supported parametersSupported parameters

The table below lists the parameters specific to API Gateway API gateways. You can find the description of other parameters in the OpenAPI 3.0 specification.

You do not need to to specify openIdConnectUrl, which is standard for the OpenAPI 3.0 specification, if jwksUri is specified.

The IdentitySource object may contain the following parameters:

Supported signature algorithmsSupported signature algorithms

API call authorization algorithmAPI call authorization algorithm

JWT request authorization uses the following algorithm:

1. API Gateway checks whether there is a token in identitySource and removes its prefix if it is provided in the specification.

2. If the specification allows caching the authorization result and a cached record is still valid, API Gateway returns the cached authorization result. Otherwise, it decodes the token header and body.

3. API Gateway specifies the receiving address of the public key required to validate the JWS electronic signature of the token. It does this using the jwksUri parameter value. If the jwksUri parameter is not provided in the specification, API Gateway uses the openIdConnectUrl parameter, which is standard for OpenAPI, to send a request to the address specified in the parameter and retrieves the public key address from the jwks_uri field located in the body of the response.

4. If the specification allows caching public keys and the cached record is still valid, API Gateway uses the receiving address of the public keys and the public key ID (kid field of the JWT header) to try and retrieve the public key from the local cache. Otherwise, it queries the public key at its address. The public key whose ID matches the kid field value in the JWT header is selected from the response body. The retrieved public key is cached if the specification allows this.

5. API Gateway checks whether the token signature algorithms and the public key match.

6. API Gateway verifies the token signature.

7. API Gateway checks the token body fields:

   • exp: Must be after the current time in UTC.
   • nbf: Must be before the current time in UTC.
   • iat: Must be before the current time in UTC.
   • iss: Must match one of the values specified in the issuers specification parameter.
   • aud: Must match one of the values specified in the audiences specification parameter.

   For more information about the fields, see the JWT standard.

8. API Gateway checks that the token body contains the fields set in the requiredClaims specification parameter.

9. API Gateway checks that the token owner (token's scope field value) has all permissions required to get the requested resource.

If any check fails, API Gateway denies access to the requested resource and returns the 403 status code.

Extension specificationExtension specification

Extension specification example:

paths:
  /jwt/header/authorize:
    get:
      summary: Authorized operation with OpenId Connect security scheme and JWT in header
      operationId: httpOpenIdAuthorizeWithJwtInHeader
      security:
        - jwtHeaderAuthorizer:
          - profile:read
          - profile:write
      x-yc-apigateway-integration:
        type: dummy
        content:
          '*': "Authorized!"
        http_code: 200
        http_headers:
          'Content-Type': "text/plain"
components:
  securitySchemes:
    jwtHeaderAuthorizer:
      type: openIdConnect
      openIdConnectUrl: https://example.com/.well-known/openid-configuration
      x-yc-apigateway-authorizer:
        type: jwt
        authorizer_result_ttl_in_seconds: 3000
        jwkTtlInSeconds: 5000
        jwksUri: https://example.com/.well-known/jwks.json
        issuers:
          - https://example.com
          - https://example2.com
        audiences:
          - audience-1
          - audience-2
        identitySource:
          in: header
          name: Authorization
          prefix: "Bearer "
        requiredClaims:
          - role
          - email

In the above example, API Gateway validates the token in the Authorization header when accessing the /jwt/query/authorize resource. To get the token, remove the Bearer prefix from the target header value.

For successful authorization:

• The token signature and all common fields must be correct.
• The token must contain the role and email fields.
• The iss field value must be https://example.com or https://example2.com.
• The aud field value must be audience-1 or audience-2.
• The token must have the profile:read and profile:write permissions specified.

Caching authorization resultsCaching authorization results

The authorization result is stored in the API Gateway local cache if the extension has the authorizer_result_ttl_in_seconds parameter specified. If, during the time specified in authorizer_result_ttl_in_seconds, another HTTP request with similar caching key components is received, API Gateway will use the cached response without validating the token signature.

The caching key contents depend on the authorizer_result_caching_mode value.

For example, for the resource ID in the /user/{id} specification and in the /user/1234 request, if authorizer_result_caching_mode is path, /user/{id} will be used to generate a caching key; if it is uri, /user/123 will be used.

Caching public keysCaching public keys

A public key you get at the address specified in the jwksUri parameter or the configuration file's jwks_uri field, is stored in the API Gateway local cache if the extension has the jwkTtlInSeconds parameter specified.

When generating the caching key, the public key ID (the kid field value from the JWT header) and the public key address are used.

If an HTTP request requiring a public key with the same address and the kid key ID is received again within the time specified in jwkTtlInSeconds, API Gateway will use the cached response and will not request the public key again.

Authorization contextAuthorization context

If the authorization is successful, the JWT authorization context will be provided in the request in the requestContext.authorizer.jwt field when invoking a user-defined integration function. The JWT authorization context contains the following parameters:

Possible errorsPossible errors

• 401 Unauthorized: The client did not provide authorization data in the HTTP request or the provided token is incorrect, e.g., it has an invalid signature, required fields are missing, token lifetime is expired, etc.
• 403 Forbidden: The token has no permissions (the scope field) to access the requested resource.
• 500 Internal Server Error: Either API Gateway failed to retrieve the OpenID Connect configuration, or the public key or returned value structure is invalid.

Use casesUse cases

• Deploying a web app with JWT authorization in Yandex API Gateway and authentication in Firebase