다음을 통해 공유


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를 포함합니다. * 값은 모든 메서드를 나타냅니다. 아니요 이 섹션이 없으면 GETPOST가 지원됩니다.
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 실행 전을 트리거하지는 않습니다. GETHEAD 메서드와 제한된 요청 헤더 집합을 사용하는 요청만 허용됩니다.

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 헤더가 있을 때 예상됩니다.

예시

이 예에서는 GETPOST 이외의 사용자 지정 헤더 또는 메서드가 있는 요청과 같은 실행 전 요청을 지원하는 방법을 보여 줍니다. 사용자 지정 헤더 및 기타 HTTP 동사를 지원하려면 다음 예와 같이 allowed-methodsallowed-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>

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