x-yc-apigateway-authorizer:function extension

Written by

Supported parameters
Extension specification
Request structure
Response structure
Function example
Caching
Authorization context
Possible errors

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

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.

Parameter	Type	Description
`function_id`	`string`	Function ID.
`tag`	`string`	Optional parameter. Version tag. Default value: `$latest`. Parameters are substituted in `tag`.
`service_account_id`	`string`	ID of the service account. Used for authorization when invoking a function. If you omit the parameter, the value used is that of the top-level parameter `service_account_id`. If there is no top-level parameter, the function is invoked without authorization.
`authorizer_result_ttl_in_seconds`	`int`	Optional parameter. A time limit on keeping the function response stored in the local API Gateway cache. If the parameter is omitted, the response is not cached.

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: ajehfe41hhliq4n93q1g
        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:

JavaScript

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;
};

Caching

A function response is stored in the local API Gateway cache 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.