x-yc-apigateway-authorizer:function extension

The x-yc-apigateway-authorizer:function extension is used inside the securityScheme component schemes with the following types:

• HTTP Basic.
• HTTP Bearer.
• API Key.

To authorize an HTTP request, API Gateway calls the function specified in the extension. Find out more about the request and the response structures.

Supported parameters

The table below lists the parameters specific to API Gateway API gateways. Read more about other parameters in the OpenAPI Specification 3.0.

Extension 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: b095c95icnvbuf4v755l
        tag: "$latest"
        service_account_id: ajehfe84hhlaq4n59q1
        authorizer_result_ttl_in_seconds: 300

Request structure

Function call JSON structure:

{
    "resource": <resource corresponding to 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 structure

Response JSON structure:

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

Function example

An example 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>.

Caching

A function response is stored in the local cache API Gateway if the extension specifies the authorizer_result_ttl_in_seconds parameter. When generating a caching key for the scheme:

• With the HTTP Basic and the HTTP Bearer types, use path, operation (HTTP method), and the Authorization header.
• With the API Key type, use path, operation (HTTP method) and the API key.

If, during the time specified in authorizer_result_ttl_in_seconds, another HTTP request with similar path, operation, and authorization data is received again, API Gateway will use the cached response without invoking the function.

Authorization context

If the authorization was successful and another user function is invoked, the authorization context will be passed down in the request using the requestContext.authorizer field. An authorization context may contain data identifying the user that is the source of the HTTP request.

Possible errors

• 401 Unauthorized: A client failed to send the authorization data defined by the scheme in the HTTP request (for example, the Authorization header for a scheme with the HTTP Basic type).
• 403 Forbidden: API Gateway did not make a successful function call ("isAuthorized": false).
• 500 Internal Server Error: API Gateway could not invoke the function or received a function response with an incorrect structure.