# x-amazon-apigateway-authorizer 객체
API Gateway에서 메서드 호출의 권한 부여를 위해 적용할 Lambda 권한 부여자, Amazon Cognito 사용자 풀 또는 JWT 권한 부여자를 정의합니다. 이 확장은 [OpenAPI 2](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md#security-definitions-object)의 보안 정의와 [OpenAPI 3](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.1.md#security-scheme-object)의 보안 스키마에 적용됩니다.
| 속성 이름 | 유형 | 설명 |
| --- | --- | --- |
| type | string | 권한 부여자의 유형입니다. 필수 속성입니다.
REST API의 경우 호출자 자격 증명이 권한 부여 토큰에 내장된 권한 부여자에 대해 `token`을(를) 지정합니다. 호출자 자격 증명이 요청 파라미터에 포함된 권한 부여자의 경우 `request`를 지정합니다. Amazon Cognito 사용자 풀을 사용하여 API에 대한 액세스를 제어하는 권한 부여자의 경우 `cognito_user_pools`를 지정합니다.
HTTP API에 대해 호출자 자격 증명이 요청 파라미터에 포함된 Lambda 권한 부여자의 경우 `request`를 지정합니다. JWT 권한 부여자에 대해 `jwt`를 지정합니다. |
| authorizerUri | string | 권한 부여자 Lambda 함수의 URI(Uniform Resource Identifier)입니다. 구문은 다음과 같습니다."arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:{{account-id}}:function:{{auth_function_name}}/invocations" |
| authorizerCredentials | string | IAM 실행 역할의 ARN 형식으로 된, 권한 부여자를 호출하는 데 필요한 자격 증명입니다. 예: "arn:aws:iam::{{account-id}}:{{IAM\_role}}". |
| authorizerPayloadFormatVersion | string | HTTP API의 경우, API Gateway에서 Lambda 권한 부여자로 전송하는 데이터의 형식과 API Gateway에서 Lambda의 응답을 해석하는 방법을 지정합니다. 자세한 내용은 [페이로드 형식 버전](http-api-lambda-authorizer.md#http-api-lambda-authorizer.payload-format) 단원을 참조하세요. |
| enableSimpleResponses | Boolean | HTTP API에 대해 `request` 권한 부여자가 부울 값을 반환할지 아니면 IAM 정책을 반환할지 여부를 지정합니다. `authorizerPayloadFormatVersion`이 `2.0`인 권한 부여자의 경우에만 지원됩니다. 이 속성을 사용하면 Lambda 권한 부여자 함수가 부울 값을 반환합니다. 자세한 내용은 [형식 2.0에 대한 Lambda 함수 응답](http-api-lambda-authorizer.md#http-api-lambda-authorizer.v2) 단원을 참조하세요. |
| identitySource | string | ID 소스로서 요청 파라미터의 매핑 표현식에 대한 쉼표로 구분된 목록입니다. `request` 및 `jwt` 유형의 권한 부여자에만 적용됩니다. |
| jwtConfiguration | Object | JWT 권한 부여자의 발급자 및 대상 그룹을 지정합니다. 자세히 알아보려면 API Gateway 버전 2 API 참조의 [JWTConfiguration](https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-authorizers-authorizerid.html#apis-apiid-authorizers-authorizerid-model-jwtconfiguration)을 참조하세요. HTTP API에서만 지원됩니다. |
| identityValidationExpression | string | 수신되는 자격 증명으로서의 토큰을 확인하는 표현식입니다. 예: "^x-[a-z]\+". REST API용 `TOKEN` 권한 부여자에서만 지원됩니다. |
| authorizerResultTtlInSeconds | string | 권한 부여자 결과가 캐싱되는 시간(초)입니다. |
| providerARNs | string의 어레이 | `COGNITO_USER_POOLS`에 대한 Amazon Cognito 사용자 풀의 목록입니다. |
## REST API에 대한 x-amazon-apigateway-authorizer 예제
다음 OpenAPI 보안 정의 예제에서는 `test-authorizer`라는 "토큰" 유형의 Lambda 권한 부여자를 지정합니다.
```
"securityDefinitions" : {
"test-authorizer" : {
"type" : "apiKey", // Required and the value must be "apiKey" for an API Gateway API.
"name" : "Authorization", // The name of the header containing the authorization token.
"in" : "header", // Required and the value must be "header" for an API Gateway API.
"x-amazon-apigateway-authtype" : "custom", // Specifies the authorization mechanism for the client.
"x-amazon-apigateway-authorizer" : { // An API Gateway Lambda authorizer definition
"type" : "token", // Required property and the value must "token"
"authorizerUri" : "arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:{{account-id}}:function:{{function-name}}/invocations",
"authorizerCredentials" : "arn:aws:iam::{{account-id}}:role",
"identityValidationExpression" : "^x-[a-z]+",
"authorizerResultTtlInSeconds" : 60
}
}
}
```
다음 OpenAPI 작업 객체 코드 조각은 위에 나온 Lambda 권한 부여자를 사용하도록 `GET /http`를 설정합니다.
```
"/http" : {
"get" : {
"responses" : { },
"security" : [ {
"test-authorizer" : [ ]
} ],
"x-amazon-apigateway-integration" : {
"type" : "http",
"responses" : {
"default" : {
"statusCode" : "200"
}
},
"httpMethod" : "GET",
"uri" : "http://api.example.com"
}
}
}
```
다음 OpenAPI 보안 정의 예제에서는 단일 헤더 파라미터(`auth`)를 자격 증명 원본으로 사용하여 "요청" 유형의 Lambda 권한 부여자를 지정합니다. `securityDefinitions`의 이름은 `request_authorizer_single_header`입니다.
```
"securityDefinitions": {
"request_authorizer_single_header" : {
"type" : "apiKey",
"name" : "auth", // The name of a single header or query parameter as the identity source.
"in" : "header", // The location of the single identity source request parameter. The valid value is "header" or "query"
"x-amazon-apigateway-authtype" : "custom",
"x-amazon-apigateway-authorizer" : {
"type" : "request",
"identitySource" : "method.request.header.auth", // Request parameter mapping expression of the identity source. In this example, it is the 'auth' header.
"authorizerCredentials" : "arn:aws:iam::123456789012:role/AWSepIntegTest-CS-LambdaRole",
"authorizerUri" : "arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:123456789012:function:APIGateway-Request-Authorizer:vtwo/invocations",
"authorizerResultTtlInSeconds" : 300
}
}
}
```
다음 OpenAPI 보안 정의 예제에서는 자격 증명 원본으로 헤더(`HeaderAuth1`) 및 쿼리 문자열 파라미터 `QueryString1`을 사용하여 "요청" 유형이 Lambda 권한 부여자를 지정합니다.
```
"securityDefinitions": {
"request_authorizer_header_query" : {
"type" : "apiKey",
"name" : "Unused", // Must be "Unused" for multiple identity sources or non header or query type of request parameters.
"in" : "header", // Must be "header" for multiple identity sources or non header or query type of request parameters.
"x-amazon-apigateway-authtype" : "custom",
"x-amazon-apigateway-authorizer" : {
"type" : "request",
"identitySource" : "method.request.header.HeaderAuth1, method.request.querystring.QueryString1", // Request parameter mapping expressions of the identity sources.
"authorizerCredentials" : "arn:aws:iam::123456789012:role/AWSepIntegTest-CS-LambdaRole",
"authorizerUri" : "arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:123456789012:function:APIGateway-Request-Authorizer:vtwo/invocations",
"authorizerResultTtlInSeconds" : 300
}
}
}
```
다음 OpenAPI 보안 정의 예제에서는 단일 단계 변수(`stage`)를 자격 증명 원본으로 사용하여 "요청 " 유형의 API Gateway Lambda 권한 부여자를 지정합니다.
```
"securityDefinitions": {
"request_authorizer_single_stagevar" : {
"type" : "apiKey",
"name" : "Unused", // Must be "Unused", for multiple identity sources or non header or query type of request parameters.
"in" : "header", // Must be "header", for multiple identity sources or non header or query type of request parameters.
"x-amazon-apigateway-authtype" : "custom",
"x-amazon-apigateway-authorizer" : {
"type" : "request",
"identitySource" : "stageVariables.stage", // Request parameter mapping expression of the identity source. In this example, it is the stage variable.
"authorizerCredentials" : "arn:aws:iam::123456789012:role/AWSepIntegTest-CS-LambdaRole",
"authorizerUri" : "arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:123456789012:function:APIGateway-Request-Authorizer:vtwo/invocations",
"authorizerResultTtlInSeconds" : 300
}
}
}
```
다음 OpenAPI 보안 정의 예제에서는 Amazon Cognito 사용자 풀을 권한 부여자로 지정합니다.
```
"securityDefinitions": {
"cognito-pool": {
"type": "apiKey",
"name": "Authorization",
"in": "header",
"x-amazon-apigateway-authtype": "cognito_user_pools",
"x-amazon-apigateway-authorizer": {
"type": "cognito_user_pools",
"providerARNs": [
"arn:aws:cognito-idp:us-east-1:123456789012:userpool/us-east-1_ABC123"
]
}
}
```
다음 OpenAPI 작업 객체 코드 조각에서는 사용자 지정 범위 없이 이전 Amazon Cognito 사용자 풀을 권한 부여자로 사용하도록 `GET /http`를 설정합니다.
```
"/http" : {
"get" : {
"responses" : { },
"security" : [ {
"cognito-pool" : [ ]
} ],
"x-amazon-apigateway-integration" : {
"type" : "http",
"responses" : {
"default" : {
"statusCode" : "200"
}
},
"httpMethod" : "GET",
"uri" : "http://api.example.com"
}
}
}
```
## HTTP API에 대한 x-amazon-apigateway-authorizer 예제
다음 OpenAPI 3.0 예제에서는 `Authorization` 헤더를 자격 증명 소스로 사용하여 Amazon Cognito를 자격 증명 공급자로 사용하는 HTTP API에 대한 JWT 권한 부여자를 생성합니다.
```
"securitySchemes": {
"jwt-authorizer-oauth": {
"type": "oauth2",
"x-amazon-apigateway-authorizer": {
"type": "jwt",
"jwtConfiguration": {
"issuer": "https://cognito-idp.region.amazonaws.com/userPoolId",
"audience": [
"audience1",
"audience2"
]
},
"identitySource": "$request.header.Authorization"
}
}
}
```
다음 OpenAPI 3.0 예제에서는 이전 예제와 동일한 JWT 권한 부여자를 생성합니다. 하지만 이 예제에서는 OpenAPI `openIdConnectUrl` 속성을 사용하여 발행자를 자동으로 검색합니다. `openIdConnectUrl`는 완전한 형태여야 합니다.
```
"securitySchemes": {
"jwt-authorizer-autofind": {
"type": "openIdConnect",
"openIdConnectUrl": "https://cognito-idp.region.amazonaws.com/userPoolId/.well-known/openid-configuration",
"x-amazon-apigateway-authorizer": {
"type": "jwt",
"jwtConfiguration": {
"audience": [
"audience1",
"audience2"
]
},
"identitySource": "$request.header.Authorization"
}
}
}
```
다음은 HTTP API에 대한 Lambda 권한 부여자를 생성하는 예제입니다. 이 예제 권한 부여자는 `Authorization` 헤더를 자격 증명 원본으로 사용합니다. 권한 부여자는 `2.0` 페이로드 포맷 버전을 사용하고 `enableSimpleResponses`가 `true`로 설정되어 있기 때문에 부울 값을 반환합니다.
```
"securitySchemes" : {
"lambda-authorizer" : {
"type" : "apiKey",
"name" : "Authorization",
"in" : "header",
"x-amazon-apigateway-authorizer" : {
"type" : "request",
"identitySource" : "$request.header.Authorization",
"authorizerUri" : "arn:aws:apigateway:{{us-west-2}}:lambda:path/2015-03-31/functions/arn:aws:lambda:us-west-2:123456789012:function:{{function-name}}/invocations",
"authorizerPayloadFormatVersion" : "2.0",
"authorizerResultTtlInSeconds" : 300,
"enableSimpleResponses" : true
}
}
}
```