Amazon API Gateway
개발자 안내서

API Gateway REST API 리소스에 대한 CORS 활성화

CORS(Cross-origin 리소스 공유)는 브라우저에서 실행 중인 스크립트에서 시작되는 cross-origin HTTP 요청을 제한하는 브라우저 보안 기능입니다. REST API의 리소스가 비 단순 cross-origin HTTP 요청을 받을 경우 CORS 지원을 활성화해야 합니다.

CORS 지원 활성화 여부 확인

cross-origin HTTP 요청은 다음에 대해 이루어지는 요청입니다.

  • 다른 도메인(예: example.com에서 amazondomains.com으로)

  • 다른 하위 도메인(예: example.com에서 petstore.example.com으로)

  • 다른 포트(예: example.com에서 example.com:10777으로)

  • 다른 프로토콜(예: https://example.com에서 http://example.com으로)

Cross-origin HTTP 요청은 단순 요청과 비 단순 요청의 두 가지 유형으로 나눌 수 있습니다.

다음과 같은 모든 조건을 충족하는 HTTP 요청은 단순 요청입니다.

  • GET, HEAD, POST 요청만 허용하는 API 리소스에 대해 발행된 요청입니다.

  • POST 메서드 요청인 경우 Origin 헤더를 포함해야 합니다.

  • 요청 페이로드 콘텐츠 유형이 text/plain, multipart/form-data 또는 application/x-www-form-urlencoded입니다.

  • 요청에 사용자 지정 헤더가 없습니다.

  • 단순 요청에 대한 Mozilla CORS 문서에 나열된 추가 요청.

단순 cross-origin POST 메서드 요청의 경우 해당 리소스로부터의 응답에 Access-Control-Allow-Origin 헤더가 포함되어야 합니다. 헤더 키 값은 '*'(임의의 오리진)으로 설정되거나, 해당 리소스에 대한 액세스가 허용되는 오리진으로 설정됩니다.

다른 모든 cross-origin HTTP 요청은 비 단순 요청입니다. API의 리소스에서 비 단순 요청을 받을 경우 CORS 지원을 활성화해야 합니다.

CORS 지원 활성화의 의미

브라우저에서 비 단순 HTTP 요청을 받을 경우 CORS 프로토콜은 브라우저에 preflight 요청을 서버로 보내고, 서버 승인(또는 자격 증명에 대한 요청)을 기다린 후 실제 요청을 보내도록 요구합니다. preflight 요청은 API에 다음과 같은 HTTP 요청으로 나타납니다.

  • Origin 헤더를 포함합니다.

  • OPTIONS 메서드를 사용합니다.

  • 다음 헤더를 포함합니다.

    • Access-Control-Request-Method

    • Access-Control-Request-Headers

CORS를 지원하기 위해 REST API 리소스는 페치 표준에서 요구하는 다음과 같은 응답 헤더를 한 개 이상 포함하는 OPTIONS preflight 요청에 응답할 수 있는 OPTIONS 메서드를 구현해야 합니다.

  • Access-Control-Allow-Methods

  • Access-Control-Allow-Headers

  • Access-Control-Allow-Origin

CORS 지원을 활성화하는 방식은 API의 통합 유형에 따라 다릅니다.

모의 통합을 위해 CORS 지원 활성화

모의 통합의 경우, 필요한 응답 헤더를 메서드 응답 헤더(적절한 정적 값 포함)로 반환하는 OPTIONS 메서드를 생성하여 CORS를 활성화합니다. 또한 실제 CORS 활성화 메서드는 최소 200 응답에 Access-Control-Allow-Origin:'request-originating server addresses' 헤더를 반환해야 합니다. 헤더 키의 값은 '*'(임의의 오리진)으로 설정되거나 리소스에 대한 액세스를 허용하는 오리진으로 설정됩니다

Lambda 또는 HTTP 비 프록시 통합 및 AWS 서비스 통합을 위해 CORS 지원 활성화

Lambda 사용자 지정(비 프록시) 통합, HTTP 사용자 지정(비 프록시) 통합 또는 AWS 서비스 통합의 경우, API Gateway 메서드 응답 및 통합 응답 설정을 사용하여 필요한 헤더를 설정할 수 있습니다. API Gateway는 OPTIONS 메서드를 생성하고, 기존 메서드 통합 응답에 Access-Control-Allow-Origin 헤더를 추가하려고 시도합니다. 항상 이를 수행하는 것은 아니므로 경우에 따라 통합 응답을 수동으로 수정하여 CORS를 활성화해야 합니다. 일반적으로 이 작업은 Access-Control-Allow-Origin 헤더를 반환하기 위해 통합 응답을 수동으로 수정하는 것입니다.

Lambda 또는 HTTP 프록시 통합을 위해 CORS 지원 활성화

Lambda 프록시 통합 또는 HTTP 프록시 통합의 경우에도, 필요한 OPTIONS 응답 헤더를 API Gateway에 설정할 수 있습니다. 하지만 프록시 통합은 통합 응답을 반환하지 않기 때문에 백엔드에서 Access-Control-Allow-OriginAccess-Control-Allow-Headers 헤더를 반환해야 합니다.

다음은 필요한 CORS 헤더를 반환하도록 구성된 Node.js Lambda 함수의 예입니다.

'use strict'; exports.handler = function(event, context) { var responseCode = 200; var response = { statusCode: responseCode, headers: { "x-custom-header" : "my custom header value", "Access-Control-Allow-Origin": "my-origin.com" }, body: JSON.stringify(event) }; context.succeed(response); };

Node.js 예제에 대한 자세한 내용은 https://github.com/awslabs/serverless-application-model/blob/master/examples/2016-10-31/api_swagger_cors/index.js에서 확인할 수 있습니다.

다음은 필요한 CORS 헤더를 반환하는 Python 코드 조각의 예입니다.

response["headers"] = { 'Content-Type': 'application/json', 'Access-Control-Allow-Origin': '*' }

다음은 SAM(Serverless Application Model)을 사용하여 CORS에 필요한 헤더(AllowHeaders 포함)를 반환하는 예제입니다.

Globals: Api: # Allows an application running locally on port 8080 to call this API Cors: AllowMethods: "'OPTIONS,POST,GET'" AllowHeaders: "'Content-Type'" AllowOrigin: "'http://localhost:8080'"

다음은 SAM 예제와 동일한 헤더를 반환하는 Lambda 프록시 예제입니다.

return { 'statusCode': 200, 'headers': { "Access-Control-Allow-Origin": "http://localhost:8080", "Access-Control-Allow-Headers": "Content-Type", "Access-Control-Allow-Methods": "OPTIONS,POST,GET" }, 'body': json.dumps(response) }

CORS 테스트

사용하는 실제 메서드 및 오리지 헤더에 대해 다음 cURL 명령을 사용자 지정하여 CORS를 테스트할 수 있습니다.

curl -v -X OPTIONS -H "Access-Control-Request-Method: POST" -H "Origin: http://example.com" https://{restapi_id}.execute-api.{region}.amazonaws.com/{stage_name}

API Gateway 콘솔을 사용하여 리소스에서 CORS 활성화

생성한 REST API 리소스의 한 메서드 또는 모든 메서드에 대해 API Gateway 콘솔을 사용하여 CORS 지원을 활성화할 수 있습니다.

중요

리소스는 하위 리소스를 포함할 수 있습니다. 리소스와 그 메서드에 대한 CORS 지원 활성화는 하위 리소스와 그 메서드에 대해 재귀적으로 활성화되지 않습니다.

REST API 리소스에 대해 CORS 지원 활성화

  1. https://console.aws.amazon.com/apigateway에서 API Gateway 콘솔에 로그인합니다.

  2. API 목록에서 API를 선택합니다.

  3. 리소스에서 리소스를 선택합니다. 그렇게 하면 리소스 상의 모든 메서드에 대해 CORS가 활성화됩니다.

    아니면 리소스에서 메서드를 선택하여 해당 메서드에 대해서만 CORS를 활성화할 수도 있습니다.

  4. 작업 드롭다운 메뉴에서 CORS 활성화(Enable CORS)를 선택합니다.

    
                        CORS 활성화 선택
  5. CORS 활성화(Enable CORS) 양식에서 다음을 수행합니다.

    1. Access-Control-Allow-Headers 입력 필드에 클라이언트가 실제 리소스 요청 시에 제출해야 할 쉼표로 분리된 헤더 목록의 정적 문자열을 입력합니다. 콘솔에서 제공하는 'Content-Type,X-Amz-Date,Authorization,X-Api-Key,X-Amz-Security-Token'의 헤더 목록을 사용하거나 자체 헤더를 사용합니다.

    2. 콘솔에서 제공하는 '*' 값을 Access-Control-Allow-Origin 헤더 값으로 사용하여 모든 오리진으로부터 수신되는 액세스 요청을 허용하거나 리소스에 대한 액세스를 허용할 오리진을 지정합니다.

    3. CORS 활성화 및 기존의 CORS 헤더 대체(Enable CORS and replace existing CORS headers)를 선택합니다.

    
                        허용할 헤더 선택

    중요

    상기 지침을 프록시 통합에서 ANY 메서드에 적용할 때 어떤 적용 가능한 CORS도 설정하지 않습니다. 대신 백엔드에서 해당 CORS 헤더를 반환해야 합니다(예: Access-Control-Allow-Origin).

  6. 메서드 변경 사항 확인(Confirm method changes)에서 예, 기존 값 덮어쓰기(Yes, overwrite existing values)를 선택하여 새 CORS 설정을 확인합니다.

    
                        기존 값 덮어쓰기 확인

GET 메서드에 대해 CORS가 활성화되면 OPTIONS 메서드가 리소스에 추가됩니다(아직 없는 경우). OPTIONS 메서드의 200 응답은 preflight 핸드셰이크를 수행하기 위해 Access-Control-Allow-* 헤더 세 개를 반환하도록 자동으로 구성됩니다. 또한 실제 (GET) 메서드는 기본적으로 200 응답에 Access-Control-Allow-Origin 헤더를 반환하도록 구성됩니다. 다른 응답 유형의 경우, Cross-origin access 오류를 반환하지 않으려면 '*' 또는 특정 오리진을 포함하는 Access-Control-Allow-Origin' 헤더를 반환하도록 수동으로 구성해야 합니다.

리소스에 대해 CORS 지원을 활성화한 후 API를 배포하거나 다시 배포해야 새로운 설정이 적용됩니다. 자세한 내용은 API Gateway 콘솔에서 REST API 배포 단원을 참조하십시오.