x-yc-apigateway-authorizer:function extension
The x-yc-apigateway-authorizer:function
extension is used within the securityScheme
To authorize an HTTP request, API Gateway invokes the function specified in the extension. You can find out the details about the request and response structures below.
Supported parameters
The table below lists the parameters specific to API Gateway API gateways. You can find the description of other parameters in the OpenAPI 3.0 specification
Parameter | Type | Description |
---|---|---|
function_id |
string |
Function ID. |
tag |
string |
This is an optional parameter. It specifies the tag of the function version. The default value is $latest .tag is used for parameter substitution. |
service_account_id |
string |
Service account ID. It is used for authorization when invoking a function. If it is not specified, its value is taken from the parent service_account_id . If the parent parameter is also missing, the function is invoked without authorization. |
authorizer_result_ttl_in_seconds |
int |
This is an optional parameter. It sets a time limit on keeping the function response stored in the local API Gateway cache. If the parameter is not specified, the response is not cached. |
authorizer_result_caching_mode |
string |
This is an optional parameter. It defines the authorization result caching mode. To use it, make sure to specify the authorizer_result_ttl_in_seconds parameter. The possible values are path and 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 matching 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
Here is 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 API Gateway local cache if the extension specifies the authorizer_result_ttl_in_seconds
parameter.
The contents of a caching key depend on the authorization type and the authorizer_result_caching_mode
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 sending a /user/123
request, a caching key will be generated from /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 provided in the request using the requestContext.authorizer
field. The authorization context may contain data identifying the user that sent the HTTP request.
Possible errors
401 Unauthorized
: Client failed to send the authorization data defined by the schema in the HTTP request (e.g., theAuthorization
header for a schema with the HTTP Basic type).403 Forbidden
: API Gateway failed to invoke a function ("isAuthorized": false
).500 Internal Server Error
: API Gateway could not invoke the function or received a function response with an incorrect structure.