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 the openIdConnectUrl parameter, which is standard for the OpenAPI 3.0 specification, if the jwksUri parameter is specified.

The IdentitySource object may contain the following parameters:

Supported signature algorithmsSupported signature algorithms

API call authorization algorithmAPI call authorization algorithm

Request authorization with a JWT is based on 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 electronic signature of the JWS 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 greater than the current UTC time.
   • nbf: Must be smaller than the current UTC time.
   • iat: Must be smaller than the current UTC time.
   • iss: Must take one of the values specified in the issuers specification parameter.
   • aud: Must take 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

Sample extension specification:

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 is 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 equal https://example.com or https://example2.com.
• The aud field value must equal 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 local API Gateway cache if the extension has the authorizer_result_ttl_in_seconds parameter specified. If, during the time specified in the authorizer_result_ttl_in_seconds parameter, another HTTP request with similar caching key components is received again, 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 the authorizer_result_caching_mode parameter value equals path, /user/{id} will be used to generate a caching key; if it equals uri, /user/123 will be used.

Caching public keysCaching public keys

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

When generating the cache key, the public key ID (kid field value from the JWT header) and the address the public key was received at 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 response stored in the cache 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 inside 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., invalid signature, empty required fields, token lifetime expired, etc.
• 403 Forbidden: The token has no permissions (scope field) required to access the requested resource.
• 500 Internal Server Error: API Gateway failed to retrieve the OpenID Connect configuration or incorrect public key structure/returned value.