CORS

  • 아티클

적용 대상: 모든 API Management 계층

cors 정책은 CORS(Cross-Origin Resource Sharing) 지원을 작업 또는 API에 추가하여 브라우저 기반 클라이언트의 도메인 간 호출을 허용합니다.

참고 항목

정책 문에 제공된 순서대로 정책의 요소 및 자식 요소를 설정합니다. 이 정책을 구성하는 데 도움이 되도록 포털은 양식 기반의 안내형 편집기를 제공합니다. API Management 정책을 설정하거나 편집하는 방법에 대해 자세히 알아봅니다.

정책 문

<cors allow-credentials="false | true" terminate-unmatched-request="true | false">
    <allowed-origins>
        <origin>origin uri</origin>
    </allowed-origins>
    <allowed-methods preflight-result-max-age="number of seconds">
        <method>HTTP verb</method>
    </allowed-methods>
    <allowed-headers>
        <header>header name</header>
    </allowed-headers>
    <expose-headers>
        <header>header name</header>
    </expose-headers>
</cors>

특성

이름 설명 필수 항목 기본값
allow-credentials 사전 응답의 Access-Control-Allow-Credentials 헤더가 이 특성의 값으로 설정되고 도메인 간 요청에서 자격 증명을 제출하는 클라이언트 기능에 영향을 줍니다. 정책 식이 허용됩니다. 아니요 false
terminate-unmatched-request 정책 설정과 일치하지 않는 교차 원본 요청의 처리를 제어합니다. 정책 식이 허용됩니다.

OPTIONS 요청이 실행 전 요청으로 처리되고 Origin 헤더가 정책 설정과 일치하지 않는 경우:
- 특성이 true로 설정된 경우 빈 200 OK 응답으로 요청을 즉시 종료합니다.
- 특성이 false로 설정된 경우 인바운드 요소의 직계 자식 항목인 다른 범위 내 cors 정책이 있는지 인바운드를 확인하고 적용합니다. cors 정책이 없으면 빈 200 OK 응답으로 요청을 종료합니다.

GET 또는 HEAD 요청에 Origin 헤더가 포함되어 있고(따라서 단순 원본 간 요청으로 처리됨) 정책 설정과 일치하지 않는 경우:
- 특성이 true로 설정된 경우 빈 200 OK 응답으로 요청을 즉시 종료합니다.
- 특성이 false로 설정된 경우 요청이 정상적으로 진행되도록 허용하고 응답에 CORS 헤더를 추가하지 마세요.		 아니요 true

Elements

이름 설명 필수 항목 기본값
allowed-origins 도메인 간 요청에 대해 허용되는 원본을 설명하는 origin 요소를 포함합니다. allowed-origins는 모든 원본을 허용하도록 *를 지정하는 단일 origin 요소 또는 URI를 포함하는 하나 이상의 origin 요소를 포함할 수 있습니다. 예 해당 없음
allowed-methods 이 요소는 GET 또는 POST 이외의 메서드가 허용되는 경우 필요합니다. 지원되는 HTTP 동사를 지정하는 method를 포함합니다. * 값은 모든 메서드를 나타냅니다. 아니요 이 섹션이 없으면 GET 및 POST가 지원됩니다.
allowed-headers 이 요소는 요청에 포함할 수 있는 헤더 이름을 지정하는 header 요소를 포함합니다. 예 해당 없음
expose-headers 이 요소는 클라이언트가 액세스할 수 있는 헤더 이름을 지정하는 header 요소를 포함합니다. 아니요 해당 없음

주의

정책 설정에서 * 와일드카드를 주의해서 사용합니다. 이 구성은 지나치게 관대할 수 있으며 API를 특정 API 보안 위협에 더 취약하게 만들 수 있습니다.

allowed-origins 요소

이름 설명 필수 항목 기본값
origin 값은 모든 원본을 허용하는 *이거나 단일 원본을 지정하는 URI일 수 있습니다. URI에는 체계, 호스트 및 포트가 포함되어야 합니다. 인용 부호를 포함하지 마십시오. 예 URI에서 포트를 생략하면 HTTP에 포트 80이 사용되고 HTTPS에 포트 443이 사용됩니다.

allowed-methods특성

이름 설명 필수 항목 기본값
preflight-result-max-age 사전 응답의 Access-Control-Max-Age 헤더가 이 특성 값으로 설정되고 사전 응답을 캐싱하는 사용자 에이전트 기능에 영향을 줍니다. 정책 식이 허용됩니다. 아니요 0

allowed-method 요소

이름 설명 필수 항목 기본값
메서드(method) HTTP 동사를 지정합니다. 정책 식이 허용됩니다. allowed-methods 섹션이 있는 경우 하나 이상의 method 요소가 필요합니다. 해당 없음

allowed-headers 요소

이름 설명 필수 항목 기본값
헤더 헤더 이름을 지정합니다. 해당 섹션이 있는 경우 allowed-headers에 하나 이상의 header 요소가 필요합니다. 해당 없음

expose-headers 요소

이름 설명 필수 항목 기본값
헤더 헤더 이름을 지정합니다. 해당 섹션이 있는 경우 expose-headers에 하나 이상의 header 요소가 필요합니다. 해당 없음

사용

사용법 참고 사항

  • 둘 이상의 범위(예: 제품 범위 및 전역 범위)에서 cors 정책을 구성할 수 있습니다. base 요소가 부모 범위에서 필요한 정책을 상속하도록 작업, API 및 제품 범위에서 구성되었는지 확인합니다.
  • 실행 전 OPTIONS 요청에서는 cors 정책만 평가됩니다. 구성된 나머지 정책은 승인된 요청에 대해 평가됩니다.
  • 이 정책은 정책 섹션에서 한 번만 사용할 수 있습니다.

CORS 소개

CORS는 브라우저와 서버가 상호 작용하고 특정 교차 원본 요청(웹페이지의 JavaScript에서 다른 도메인으로 이루어진 XMLHttpRequest 호출)을 허용할지 여부를 결정할 수 있도록 하는 HTTP 헤더 기반 표준입니다. 따라서 동일 원본의 요청만 허용하는 것보다 유연성이 더 뛰어나며 모든 원본 간 요청을 허용하는 것보다 보안도 더 높아집니다.

CORS는 두 가지 형식의 교차 원본 요청을 지정합니다.

  • 프리플라이트 요청 - 브라우저는 먼저 OPTIONS 메서드를 사용하여 서버에 HTTP 요청을 전송하여 실제 요청을 보낼 수 있는지 확인합니다. 서버 응답에 액세스를 허용하는 Access-Control-Allow-Origin 헤더가 포함된 경우 브라우저는 실제 요청을 따릅니다.

  • 단순 요청 - 이러한 요청에는 하나 이상의 추가 Origin 헤더가 포함되지만 CORS 실행 전을 트리거하지는 않습니다. GET 및 HEAD 메서드와 제한된 요청 헤더 집합을 사용하는 요청만 허용됩니다.

cors 정책 시나리오

다음 시나리오에 대해 API Management에서 cors 정책을 구성합니다.

  • 개발자 포털에서 대화형 테스트 콘솔을 사용하도록 설정합니다. 자세한 내용은 개발자 포털 문서를 참조하세요.

    참고 항목

    대화형 콘솔에 대해 CORS를 사용하도록 설정하면 기본적으로 API Management는 전역 범위에서 cors 정책을 구성합니다.

  • 백 엔드가 자체 CORS 지원을 제공하지 않을 때 실행 전 요청에 응답하거나 간단한 CORS 요청을 통과하도록 API Management를 사용하도록 설정합니다.

    참고 항목

    요청이 API에 정의된 OPTIONS 메서드가 있는 작업과 일치하는 경우 cors 정책과 연결된 실행 전 요청 처리 논리가 실행되지 않습니다. 따라서 이러한 작업은 사용자 지정 실행 전 처리 논리를 구현하는 데 사용할 수 있습니다(예: 특정 조건에서만 cors 정책을 적용).

일반 구성 문제

  • 헤더의 구독 키 - 제품 범위에서 cors 정책을 구성하고 API가 구독 키 인증을 사용하는 경우 구독 키가 헤더에 전달될 때 정책이 작동하지 않습니다. 이 문제를 해결하려면 구독 키를 쿼리 매개 변수로 포함하도록 요청을 수정합니다.
  • 헤더 버전 관리가 포함된 API - API 범위에서 cors 정책을 구성하고 API가 헤더 버전 관리 체계를 사용하는 경우 버전이 헤더로 전달되었기 때문에 정책이 작동하지 않습니다. 경로 또는 쿼리 매개 변수와 같은 대체 버전 관리 방법을 구성해야 할 수도 있습니다.
  • 정책 순서 - cors 정책이 인바운드 섹션의 첫 번째 정책이 아닌 경우 예기치 않은 동작이 발생할 수 있습니다. 정책 편집기에서 실제 정책 계산을 선택하여 각 범위에서 정책 평가 순서를 확인합니다. 일반적으로 첫 번째 cors 정책만 적용됩니다.
  • 빈 200 OK 응답 - 일부 정책 구성에서 특정 교차 원본 요청은 빈 200 OK 응답으로 완료됩니다. 이 응답은 terminate-unmatched-request가 기본값인 true로 설정되고 수신 요청에 cors 정책에 구성된 허용된 원본과 일치하지 않는 Origin 헤더가 있을 때 예상됩니다.

예시

이 예에서는 GET 및 POST 이외의 사용자 지정 헤더 또는 메서드가 있는 요청과 같은 실행 전 요청을 지원하는 방법을 보여 줍니다. 사용자 지정 헤더 및 기타 HTTP 동사를 지원하려면 다음 예와 같이 allowed-methods 및 allowed-headers 섹션을 사용합니다.

<cors allow-credentials="true">
    <allowed-origins>
        <!-- Localhost useful for development -->
        <origin>http://localhost:8080/</origin>
        <origin>http://example.com/</origin>
    </allowed-origins>
    <allowed-methods preflight-result-max-age="300">
        <method>GET</method>
        <method>POST</method>
        <method>PATCH</method>
        <method>DELETE</method>
    </allowed-methods>
    <allowed-headers>
        <!-- Examples below show Azure Mobile Services headers -->
        <header>x-zumo-installation-id</header>
        <header>x-zumo-application</header>
        <header>x-zumo-version</header>
        <header>x-zumo-auth</header>
        <header>content-type</header>
        <header>accept</header>
    </allowed-headers>
    <expose-headers>
        <!-- Examples below show Azure Mobile Services headers -->
        <header>x-zumo-installation-id</header>
        <header>x-zumo-application</header>
    </expose-headers>
</cors>

관련 콘텐츠

정책 작업에 대한 자세한 내용은 다음을 참조하세요.