Yandex Cloud
  • Services
  • Solutions
  • Why Yandex Cloud
  • Blog
  • Pricing
  • Documentation
  • Contact us
Get started
Language / Region
Yandex project
© 2023 Yandex.Cloud LLC
Yandex API Gateway
  • Getting started
  • Step-by-step instructions
    • All instructions
    • Creating API gateways
    • Updating API gateways and their specifications
    • Connecting a domain
    • Deleting API gateways
    • Monitoring
    • Viewing the execution log
  • Tutorials
    • All practical guidelines
    • Deploying a web application using the Java Servlet API
    • Developing a skill for Alice and a website with authorization
    • Developing a Slack bot
    • Developing a Telegram bot
    • Developing user integration
    • Developing CRUD APIs for movie services
    • Communicating with an API gateway using the WebSocket protocol
  • Concepts
    • Relationships between service resources
    • Specification extensions
      • Overview
      • Static response
      • Invoking a function
      • Integration with Serverless Containers
      • Access via HTTP
      • Integration with Object Storage
      • Integration with DataSphere
      • Integration with Data Streams
      • Integration with Message Queue
      • Integration with YDB
      • Greedy parameters
      • Generalized HTTP method
      • Authorization using a function
      • WebSocket protocol support
    • Quotas and limits
  • Access management
  • Pricing policy
  • API reference
    • Authentication in the API
    • gRPC
      • Overview
      • ApiGatewayService
      • OperationService
    • REST
      • Overview
      • ApiGateway
        • Overview
        • addDomain
        • create
        • delete
        • get
        • getOpenapiSpec
        • list
        • listAccessBindings
        • listOperations
        • removeDomain
        • setAccessBindings
        • update
        • updateAccessBindings
  • Websocket API reference
    • Authentication in the API
    • gRPC
      • Overview
      • ConnectionService
    • REST
      • Overview
      • Connection
        • Overview
        • disconnect
        • get
        • send
  • Questions and answers
  1. Concepts
  2. Specification extensions
  3. Authorization using a function

x-yc-apigateway-authorizer:function extension

Written by
Yandex Cloud
  • 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:

  • 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.

Parameter Type Description
function_id string ID of the function.
tag string Optional. Tag of the function version. 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 the parameter is omitted, the value of the service_account_id top-level parameter is used. If there is no top-level parameter, the function is invoked without authorization
authorizer_result_ttl_in_seconds int Optional. 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: 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:

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

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.

Was the article helpful?

Language / Region
Yandex project
© 2023 Yandex.Cloud LLC
In this article:
  • Supported parameters
  • Extension specification
  • Request structure
  • Response structure
  • Function example
  • Caching
  • Authorization context
  • Possible errors