REST API와 Amazon Cognito 사용자 풀 통합 - Amazon API Gateway

기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.

REST API와 Amazon Cognito 사용자 풀 통합

API Gateway에서 Amazon Cognito 사용자 풀을 생성한 다음 이 사용자 풀을 사용하는 COGNITO_USER_POOLS 권한 부여자를 생성해야 합니다. 다음 절차에서는 API Gateway 콘솔에서 이 작업을 수행하는 방법을 보여줍니다.

참고

CreateAuthorizer 작업을 통해 여러 사용자 풀을 사용하는 COGNITO_USER_POOLS 권한 부여자를 생성할 수 있습니다. COGNITO_USER_POOLS 권한 부여자 한 명에 최대 1,000개의 사용자 풀을 사용할 수 있습니다. 이 한도는 늘릴 수 없습니다.

중요

아래 절차를 수행한 후 변경 사항을 전파하기 위해 API를 배포 또는 재배포할 필요가 있습니다. API 배포에 대한 자세한 내용은 Amazon API Gateway에서 REST API 배포 단원을 참조하세요.

API Gateway 콘솔을 사용하여 COGNITO_USER_POOLS 권한 부여자를 생성하려면

  1. API Gateway에서 새 API를 생성하거나 기존 API를 선택합니다.

  2. 기본 탐색 창에서 권한 부여자를 선택합니다.

  3. 권한 부여자 생성을 선택합니다.

  4. 사용자 풀을 사용하도록 새 권한 부여자를 구성하려면 다음을 수행합니다.

    1. 권한 부여자 이름에 이름을 입력합니다.

    2. 권한 부여자 유형으로 Cognito를 선택합니다.

    3. Cognito 사용자 풀의 경우 Amazon Cognito를 생성한 AWS 리전을 선택하고 사용 가능한 사용자 풀을 선택합니다.

    4. 토큰 소스에 헤더 이름으로 Authorization을 입력하여 사용자가 성공적으로 로그인할 때 Amazon Cognito에서 반환하는 자격 증명 또는 액세스 토큰을 전달합니다.

    5. (선택 사항) 토큰 검증 필드에 정규식을 입력하여 Amazon Cognito를 통해 요청에 대한 권한이 부여되기 전에 자격 증명 토큰의 aud(대상) 필드를 검증합니다. 액세스 토큰을 사용할 경우, 액세스 토큰에 aud 필드가 포함되지 않으므로 이 유효성 검사는 요청을 거부합니다.

    6. 권한 부여자 생성을 선택합니다.

  5. COGNITO_USER_POOLS 권한 부여자를 생성한 후 필요할 경우, 사용자 풀에서 프로비저닝한 자격 증명 토큰을 제공하여 호출을 테스트할 수 있습니다. Amazon Cognito 자격 증명 SDK를 호출하여 사용자 로그인을 수행함으로써 이 자격 증명 토큰을 얻을 수 있습니다. InitiateAuth 작업을 사용해도 됩니다. 권한 부여 범위를 구성하지 않으면 API Gateway는 제공된 토큰을 자격 증명 토큰으로 취급합니다.

이전 절차에서는 새로 생성된 Amazon Cognito 사용자 풀을 사용하는 COGNITO_USER_POOLS 권한 부여자를 생성합니다. API 메서드에서 권한 부여자를 활성화하는 방법에 따라 통합된 사용자 풀에서 프로비저닝되는 자격 증명 토큰 또는 액세스 토큰을 사용할 수 있습니다.

메서드에서 COGNITO_USER_POOLS 권한 부여자를 구성하려면

  1. 리소스를 선택합니다. 새 메서드를 선택하거나 기존 메서드를 선택합니다. 필요하다면 리소스를 생성합니다.

  2. 메서드 요청 탭의 메서드 요청 설정에서 편집을 선택합니다.

  3. 권한 부여자의 경우 드롭다운 메뉴에서 방금 생성한 Amazon Cognito 사용자 풀 권한 부여자를 선택합니다.

  4. 자격 증명 토큰을 사용하려면 다음 작업을 수행하세요.

    1. 권한 부여 범위를 비워둡니다.

    2. 필요에 따라 통합 요청에서 본문 매핑 템플릿에 $context.authorizer.claims['property-name'] 또는 $context.authorizer.claims.property-name 표현식을 추가하여, 사용자 풀에서 백엔드로 지정된 자격 증명 클레임 속성을 전달합니다. sub 또는 custom-sub처럼 단순한 속성 이름의 경우, 두 표기법이 동일합니다. custom:role처럼 복잡한 속성 이름의 경우, 점 표기법을 사용할 수 없습니다. 예를 들어 다음 매핑 표현식은 클레임의 표준 필드인 sub 및 email를 백엔드로 전달합니다.

      {
	"context" : {
		"sub" : "$context.authorizer.claims.sub",
		"email" : "$context.authorizer.claims.email"
	}
}

      사용자 풀을 구성할 때 사용자 지정 클레임 필드를 선언했다면 동일한 패턴에 따라 사용자 지정 필드에 액세스할 수 있습니다. 다음 예에서는 클레임의 사용자 지정 role 필드를 가져옵니다.

      {
	"context" : {
		"role" : "$context.authorizer.claims.role"
    }
}

      사용자 지정 클레임 필드가 custom:role로 선언되면 다음 예를 사용하여 클레임의 속성을 가져옵니다.

      {
	"context" : {
		"role" : "$context.authorizer.claims['custom:role']"
    }
}

  5. 액세스 토큰을 사용하려면 다음 작업을 수행하세요.

    1. 권한 부여 범위에 Amazon Cognito 사용자 풀이 생성되었을 때 구성된 범위의 전체 이름을 하나 이상 입력합니다. 예를 들어 REST API에 대한 Amazon Cognito 사용자 풀 생성에서 제시된 예를 따르면, 스코프 중 하나는 https://my-petstore-api.example.com/cats.read입니다.

      런타임 시 이 단계의 메서드에서 지정되는 범위가 수신되는 토큰에서 클레임되는 범위와 일치하면 메서드 호출이 성공합니다. 그렇지 않으면 호출은 401 Unauthorized 응답과 함께 실패합니다.

    2. 저장을 선택합니다.

  6. 선택한 다른 메서드에 대해 이러한 단계를 반복합니다.

COGNITO_USER_POOLS 권한 부여자의 경우, OAuth Scopes 옵션이 지정되지 않으면 API Gateway는 제공된 토큰을 자격 증명 토큰으로 취급하고 클레임된 자격 증명을 사용자 풀의 자격 증명과 대조하여 확인합니다. 그렇지 않으면 API Gateway는 제공된 토큰을 액세스 토큰으로 취급하고 토큰에서 클레임된 액세스 범위를 메서드에서 선언된 권한 부여 범위와 대조하여 확인합니다.

API Gateway 콘솔을 사용하는 대신 OpenAPI 정의 파일을 지정하고 API 정의를 API Gateway로 가져와 메서드에서 Amazon Cognito 사용자 풀을 활성화할 수도 있습니다.

OpenAPI 정의 파일을 사용하여 COGNITO_USER_POOLS 권한 부여자를 가져오려면

  1. API에 OpenAPI 정의 파일을 생성(또는 내보내기)합니다.

  2. COGNITO_USER_POOLS 권한 부여자(MyUserPool) JSON 정의를 다음과 같이 OpenAPI 3.0의 securitySchemes 섹션 또는 Open API 2.0의 securityDefinitions 섹션의 일부로 지정합니다.

    OpenAPI 3.0
      "securitySchemes": {
    "MyUserPool": {
      "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:{region}:{account_id}:userpool/{user_pool_id}"
        ]
      }
    }
    OpenAPI 2.0
      "securityDefinitions": {
    "MyUserPool": {
      "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:{region}:{account_id}:userpool/{user_pool_id}"
        ]
      }
    }

  3. 메서드 권한 부여에 자격 증명 토큰을 사용하려면 루트 리소스에서 다음 GET 메서드에 나온 것처럼 { "MyUserPool": [] }을 메서드의 security 정의에 추가합니다.

      "paths": {
    "/": {
      "get": {
        "consumes": [
          "application/json"
        ],
        "produces": [
          "text/html"
        ],
        "responses": {
          "200": {
            "description": "200 response",
            "headers": {
              "Content-Type": {
                "type": "string"
              }
            }
          }
        },
        "security": [
          {
            "MyUserPool": []
          }
        ],        
        "x-amazon-apigateway-integration": {
          "type": "mock",
          "responses": {
            "default": {
              "statusCode": "200",
              "responseParameters": {
                "method.response.header.Content-Type": "'text/html'"
              },
            }
          },
          "requestTemplates": {
            "application/json": "{\"statusCode\": 200}"
          },
          "passthroughBehavior": "when_no_match"
        }
      },
      ...
   }

  4. 메서드 권한 부여에 액세스 토큰을 사용하려면 위의 보안 정의를 { "MyUserPool": [resource-server/scope, ...] }로 변경합니다.

      "paths": {
    "/": {
      "get": {
        "consumes": [
          "application/json"
        ],
        "produces": [
          "text/html"
        ],
        "responses": {
          "200": {
            "description": "200 response",
            "headers": {
              "Content-Type": {
                "type": "string"
              }
            }
          }
        },
        "security": [
          {
            "MyUserPool": ["https://my-petstore-api.example.com/cats.read", "http://my.resource.com/file.read"]
          }
        ],        
        "x-amazon-apigateway-integration": {
          "type": "mock",
          "responses": {
            "default": {
              "statusCode": "200",
              "responseParameters": {
                "method.response.header.Content-Type": "'text/html'"
              },
            }
          },
          "requestTemplates": {
            "application/json": "{\"statusCode\": 200}"
          },
          "passthroughBehavior": "when_no_match"
        }
      },
      ...
   }

  5. 필요에 따라 적절한 OpenAPI 정의 또는 확장자를 사용해 다른 API 구성을 설정할 수 있습니다. 자세한 내용은 OpenAPI에 대한 API Gateway 확장 작업 단원을 참조하세요.