x-yc-apigateway-authorizer:function extension

The x-yc-apigateway-authorizer:function extension is used within the securityScheme component schemas of the following types:

• HTTP Basic
• HTTP Bearer
• API Key

To authorize an HTTP request, API Gateway invokes the function specified in the extension. You can find out the details about the request and response structures below.

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.

Extension specificationExtension specification

Example specification for an HTTP Basic scheme:

paths:
  /http/basic/authorize:
    get:
      summary: Authorized operation with http basic security scheme
      operationId: httpBasicAuthorize
      security:
        - httpBasicAuth: [ ]
      x-yc-apigateway-integration:
        type: dummy
        content:
          '*': "Authorized!"
        http_code: 200
        http_headers:
          'Content-Type': "text/plain"
components:
  securitySchemes:
    httpBasicAuth:
      type: http
      scheme: basic
      x-yc-apigateway-authorizer:
        type: function
        function_id: b095c95icnvb********
        tag: "$latest"
        service_account_id: ajehfe84hhl********
        authorizer_result_ttl_in_seconds: 300

Request structureRequest structure

Function call JSON structure:

{
    "resource": <resource matching specification request>,
    "path": <actual request path>,
    "httpMethod": <HTTP method name>,
    "headers": <dictionary with HTTP header string values>,
    "queryStringParameters": <dictionary of queryString parameters>,
    "pathParameters": <dictionary of request path parameter values>,
    "requestContext": <dictionary with request context>,
    "cookies": <dictionary with request cookies>
}

Response structureResponse structure

Response JSON structure:

{
    "isAuthorized": <authorization result, true or false>,
    "context": <dictionary with authorization context>
}

Function exampleFunction example

Here is an example of a function that uses a response structure with an authorization context:

exports.handler = async function (event, context) {
    let response = {
        "isAuthorized": false
    };

    if (event.headers.Authorization === "secretToken") {
        response = {
            "isAuthorized": true,
            "context": {
                "stringKey": "value",
                "numberKey": 1,
                "booleanKey": true,
                "arrayKey": ["value1", "value2"],
                "mapKey": {"value1": "value2"}
            }
        };
    }

    return response;
};

secretToken is the authorization data of the registered user or trusted client, such as Basic <base64(username:password)> or Bearer <JWT_token>.

CachingCaching

A function response is stored in the API Gateway local cache if the extension specifies the authorizer_result_ttl_in_seconds parameter.

The contents of a caching key depend on the authorization type and the authorizer_result_caching_mode value.

For example, for the following specification, when sending a /user/123 request, a caching key will be generated from /user/{id}, GET, and the Authorization header value. If you change the authorizer_result_caching_mode parameter value to uri, a caching key will be generated from /user/123, GET, and the Authorization header value.

paths:
  /user/{id}:
    get:
      summary: Authorized operation with http basic security scheme
      operationId: httpBasicAuthorize
      parameters:
        - in: path
          name: id
          schema:
            type: integer
          required: true
          description: Numeric ID of the user to get
      security:
        - httpBasicAuth: [ ]
      x-yc-apigateway-integration:
        type: dummy
        content:
          '*': "Authorized!"
        http_code: 200
        http_headers:
          'Content-Type': "text/plain"
components:
  securitySchemes:
    httpBasicAuth:
      type: http
      scheme: basic
      x-yc-apigateway-authorizer:
        type: function
        function_id: b095c95icnvb********
        tag: "$latest"
        service_account_id: ajehfe84hhl********
        authorizer_result_ttl_in_seconds: 300
        authorizer_result_caching_mode: path

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 invoking the function.

Authorization contextAuthorization context

If authorization is successful, the authorization context will be provided in the request:

• When calling another custom function: In the requestContext.authorizer field.
• When calling a container or HTTP request: In the X-Yc-Apigateway-Authorization-Context header. Data is encoded in Base64.

The authorization context may contain data identifying the user who sent the HTTP request.

Possible errorsPossible errors

• 401 Unauthorized: Client failed to send the authorization data defined by the schema in the HTTP request (e.g., the Authorization header for a schema of the HTTP Basic type).
• 403 Forbidden: API Gateway failed to invoke the function ("isAuthorized": false).
• 500 Internal Server Error: API Gateway could not invoke the function or received a function response with an incorrect structure.