x-yc-apigateway-authorizer:function extension
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 |
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:
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 theAuthorization
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, 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.