x-yc-apigateway-authorizer:function extension
The x-yc-apigateway-authorizer:function
extension is used inside the securityScheme
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 |
This is an optional parameter. Tag of the function version. Default value: $latest .Parameters are substituted in tag . |
service_account_id |
string |
Service account ID. Used for authorization when invoking a function. If not specified, it defaults to the top-level service_account_id parameter. If there is no top-level parameter, the function is invoked without authorization. |
authorizer_result_ttl_in_seconds |
int |
This is an 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. |
authorizer_result_caching_mode |
string |
This is an optional parameter. Authorization result caching mode. To use it, make sure to specify the authorizer_result_ttl_in_seconds parameter. Possible values: path or URI . |
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: b095c95icnvb********
tag: "$latest"
service_account_id: ajehfe84hhl********
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.
The contents of a caching key depend on the authorization type and authorizer_result_caching_mode
parameter value.
Authorization type | Path caching mode |
URI caching mode |
No caching mode specified |
---|---|---|---|
HTTP Basic |
Path , operation (HTTP method) , and Authorization header |
URI , operation (HTTP method), and Authorization header |
Path , operation (HTTP method) , and Authorization header |
HTTP Bearer |
Path , operation (HTTP method) , and Authorization header |
URI , operation (HTTP method), and Authorization header |
Path , operation (HTTP method) , and Authorization header |
API Key |
Path , operation (HTTP method) , and API key |
URI , operation (HTTP method), and API key |
Path , operation (HTTP method) , and API key |
For instance, for the following specification, when making a /user/123
request, a caching key will be generated from the /user/{id}
, GET
, and Authorization
header. 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 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
: Client failed to send the authorization data defined by the scheme in the HTTP request (e.g., theAuthorization
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.