동일 출처 정책은 서로 다른 출처의 리소스 간 상호작용을 방지하기 위해 클라이언트 측 웹 애플리케이션(웹브라우저 등)에서 적용되는 보안 정책입니다. 이 보안 조치는 악의적인 행동을 방지하는 데는 유용하지만 알려진 출처 간의 적법한 상호작용도 방지합니다. 예를 들어 example.appspot.com에 호스팅된 페이지의 스크립트가 example.storage.googleapis.com에 있는 Cloud Storage 버킷에 저장된 리소스를 사용해야 할 수도 있습니다. 하지만 브라우저 관점에서 이 둘은 출처가 서로 다르기 때문에 브라우저는 example.appspot.com의 스크립트가 example.storage.googleapis.com의 리소스를 가져오는 것을 허용하지 않습니다.
교차 출처 리소스 공유(CORS)는 이 제한을 해결하기 위해 W3C(World Wide Web Consortium)에서 개발한 사양입니다.
Cloud Storage는 버킷이 CORS를 지원하도록 구성하는 것을 허용함으로써 이 사양을 지원합니다. 위 예시에 이어 브라우저에서 example.storage.googleapis.com 버킷의 리소스를 example.appspot.com의 스크립트와 공유할 수 있도록 버킷을 구성할 수 있습니다.
단순 요청과 실행 전 요청이라는 두 가지 유형의 CORS 요청이 있습니다. 단순 요청은 바로 시작할 수 있습니다. 실행 전 요청은 기본 요청을 진행하기 전에 예비 '실행 전' 요청을 서버에 보내 권한을 얻어야 합니다.
다음 상황 중 어느 하나라도 참인 경우 실행 전 요청입니다.
GET, HEAD, POST 외의 메서드를 사용합니다.
POST 메서드를 text/plain, application/x-www-form-urlencoded, multipart/form-data가 아닌 Content-Type과 함께 사용합니다.
커스텀 헤더를 설정합니다. 예를 들면 X-PINGOTHER입니다.
브라우저가 Cloud Storage에 단순 요청을 보낼 때 다음과 같은 프로세스가 이루어집니다.
브라우저가 Origin 헤더를 요청에 추가합니다. Origin 헤더는 Origin:https://www.example.appspot.com과 같이 Cloud Storage 버킷의 리소스를 공유하기 위해 리소스 출처를 포함하고 있습니다.
Cloud Storage가 요청의 HTTP 메서드와 Origin 헤더의 값을 대상 버킷의 CORS 구성에 있는 메서드 및 출처 정보와 비교하여 일치하는 항목이 있는지 확인합니다. 일치하는 항목이 있으면 Cloud Storage가 Access-Control-Allow-Origin 헤더를 응답에 포함합니다. Access-Control-Allow-Origin 헤더는 초기 요청에 있는 Origin 헤더의 값을 포함합니다.
브라우저가 응답을 받고 Access-Control-Allow-Origin 값이 원래 요청에 지정된 도메인과 일치하는지를 확인합니다. 일치하면 요청이 성공합니다. 일치하지 않거나 응답에 Access-Control-Allow-Origin 헤더가 없는 경우에는 요청이 실패합니다.
실행 전 요청은 다음 단계를 먼저 수행합니다. 성공하면 단순 요청과 동일한 프로세스를 따릅니다.
브라우저가 기본 요청의 Requested Method 및 Requested Headers를 포함하는 OPTIONS 요청을 보냅니다.
Cloud Storage가 응답하고 대상 리소스에서 허용하는 HTTP 메서드 및 헤더의 값을 반환합니다. 실행 전 요청에 있는 메서드 또는 헤더 값 중 하나라도 대상 리소스에서 허용하는 메서드 및 헤더 집합에 들어 있지 않으면 요청이 실패하고 기본 요청이 전송되지 않습니다.
위 프로세스는 CORS를 간단하게 설명한 것입니다. 자세한 설명은 가져오기 사양을 읽어보세요.
Cloud Storage CORS 지원
Cloud Storage를 사용하면 버킷 수준에서만 CORS 구성을 설정할 수 있습니다. 다양한 도구를 사용하여 버킷의 CORS 구성을 설정할 수 있습니다. 그러나 다양한 Cloud Storage 엔드포인트는 서로 다른 방식으로 CORS 요청을 처리합니다.
JSON API 엔드포인트는 CORS 요청을 항상 허용하고 버킷에 설정된 구성에 관계없이 CORS 응답 헤더의 기본값을 반환합니다.
XML API 엔드포인트는 버킷 구성에 따라서만 CORS 요청을 허용하고 해당 구성에 대한 응답의 특정 CORS 헤더 값을 반환합니다.
인증된 브라우저 다운로드 엔드포인트 storage.cloud.google.com은 CORS 요청을 허용하지 않습니다. Google Cloud 콘솔은 각 객체의 공개 URL 링크에 이 엔드포인트를 제공합니다.
다음 XML API 요청 URL 중 하나를 사용하여 CORS 헤더를 포함하는 Cloud Storage에서 응답을 받을 수 있습니다.
XML API를 사용할 때 버킷의 CORS 구성에 설정한 값에 따라 Cloud Storage가 HTTP 응답에서 반환하는 CORS 헤더가 결정됩니다.
JSON API를 사용할 때 Cloud Storage는 버킷 구성을 평가하지 않고 대신 기본 헤더 값을 반환합니다.
다음 표에서는 CORS 구성의 필드와 XML 및 JSON API의 응답 동작에 대해 설명합니다. 이러한 필드의 사용 방법은 CORS 구성 예시를 참조하세요.
필드1
설명
XML API 응답 동작
JSON API 응답 동작
origin
이 Cloud Storage 버킷과의 교차 출처 리소스 공유를 허용하려는 출처를 지정합니다.
예를 들면 https://origin1.example.com입니다.
브라우저 요청의 출처가 CORS 구성의 출처와 일치하면 Cloud Storage가 브라우저에 Access-Control-Allow-Origin을 반환합니다. 일치하는 항목이 없으면 Cloud Storage가 응답에 Access-Control-Allow-Origin을 포함하지 않습니다. 모든 출처에 대한 액세스 권한을 부여하는 와일드 카드 값(<Origin>*</Origin>)을 제공할 수 있습니다.
이 Cloud Storage 버킷과의 교차 출처 리소스 공유를 허용하려는 HTTP 메서드를 지정합니다. 성공적인 실행 전 요청에 대한 응답으로 이 값이 Access-Control-Allow-Methods 헤더에 반환됩니다.
OPTIONS는 브라우저에서 실행 전 요청을 시작하는 데 사용하는 표준 메서드이므로 CORS 구성에서 OPTIONS를 지정해서는 안 됩니다.
Cloud Storage는 DELETE, GET, HEAD, POST, PUT 메서드를 지원합니다.
Cloud Storage는 Access-Control-Request-Methods 헤더의 브라우저에서 전송된 메서드를 버킷의 CORS 구성과 대조합니다. 일치하는 항목이 없으면 Cloud Storage는 CORS 응답 헤더가 없는 200 응답 코드를 반환합니다.
Cloud Storage는 DELETE, GET, HEAD, PATCH, POST, PUT 메서드로 설정된 Access-Control-Allow-Methods 헤더를 반환합니다.
responseHeader
이 Cloud Storage 버킷과의 교차 출처 리소스 공유를 허용하려는 헤더를 지정합니다. 성공적인 실행 전 요청에 대한 응답으로 이 값이 Access-Control-Allow-Headers 헤더에 반환됩니다.
실행 전 요청의 경우 Cloud Storage는 Access-Control-Request-Headers 헤더의 브라우저에서 전송된 헤더를 버킷의 CORS 구성과 대조합니다. 일치하는 항목이 없으면 Cloud Storage는 CORS 응답 헤더를 반환하지 않습니다.
Cloud Storage는 Access-Control-Request-Headers 헤더에 지정된 값과 동일한 Access-Control-Allow-Headers 헤더를 반환합니다.
maxAgeSeconds(선택사항)
프리플라이트 요청을 반복하기 전에 브라우저가 요청할 수 있는 시간(초)을 지정합니다. 이를 캐시 만료 시간이라고도 합니다. 실행 전 요청에 대한 응답으로 이 값이 Access-Control-Max-Age 헤더에 반환됩니다. 예를 들어 3600은 캐시 만료 시간을 1시간으로 설정합니다.
Cloud Storage는 지정된 캐시 만료 시간이 있는 Access-Control-Max-Age 헤더를 반환합니다. 이 필드를 생략하면 Cloud Storage가 기본값 3600을 반환합니다.
모든 출처의 요청을 허용하려면 출처를 *로 설정합니다.
예를 들어 JSON API의 "origin": ["*"] 또는 XML API의 <Origin>*</Origin>입니다. 이 출처는 구성을 테스트하는 데 유용하지만 대부분의 경우 리소스가 원치 않게 사용되지 않도록 요청 출처를 제한하는 것이 좋습니다.
추가 고려사항
다음 표에서는 사용자 인증 정보 또는 액세스 제어 헤더를 사용하여 요청할 때의 고려 사항에 대해 설명합니다.
속성 또는 헤더
설명
XML API 응답 동작
JSON API 응답 동작
사용자 인증 정보
쿠키, 승인 헤더, TLS 클라이언트 인증서
Cloud Storage는 Access-Control-Allow-Credentials 헤더를 반환하지 않습니다. CORS 사용자 인증 정보는 XML API에서 지원되지 않습니다.
단순 요청의 경우 CORS 요청이 승인되었으면 Access-Control-Allow-Credentials 헤더가 true로 설정됩니다.
실행 전 요청의 경우 Access-Control-Request-Method가 비어 있으면 Cloud Storage는 Access-Control-Allow-Credentials를 true로 설정하고 404 - Not Found로 요청을 거부합니다.
노출된 헤더
실행 전 요청의 경우 Access-Control-Request-Headers 요청 헤더는 이후 CORS 요청에 포함될 수 있는 헤더를 나타냅니다.
Access-Control-Expose-Headers 응답 헤더는 서버 응답에 포함되며 클라이언트에 노출될 수 있는 헤더를 나타냅니다.
단순 요청의 경우 Access-Control-Expose-Headers는 CORS 구성에 응답 헤더 값을 나열합니다.
단순 요청의 경우 Access-Control-Expose-Headers는 공통 HTTP 헤더 목록에 포함된 경우 Access-Control-Request-Headers에 지정된 값을 반환합니다.
버킷의 외부 리소스 액세스 허용
일부 경우에는 Cloud Storage에 호스팅된 스크립트가 Cloud Storage 외부 웹사이트에 호스팅된 정적 리소스에 액세스하도록 허용해야 할 수 있습니다. 이러한 시나리오에서 해당 웹사이트는 storage.googleapis.com의 콘텐츠에 액세스를 허용할 수 있도록 CORS 헤더를 사용합니다.
이 데이터 액세스를 위해 특정 버킷을 전용으로 지정하는 것이 좋습니다.
이 방식은 사이트에 있는 정적 리소스가 실수로 모든 storage.googleapis.com에 과도하게 노출되는 것을 방지합니다. 예를 들어 mybucket이라는 버킷을 데이터 액세스 전용으로 사용하려면 웹사이트에서 CORS 헤더에 Access-Control-Allow-Origin: https://storage.googleapis.com 대신 Access-Control-Allow-Origin: https://mybucket.storage.googleapis.com를 사용해야 합니다.
클라이언트 측 CORS 지원
대부분의 브라우저는 XMLHttpRequest 객체를 사용하여 교차 도메인 요청을 설정합니다.
XMLHttpRequest는 올바른 헤더를 삽입하고 서버와의 CORS 상호작용을 처리하기 위한 모든 작업을 다룹니다. Cloud Storage 버킷에서 CORS 지원을 활용하기 위해 새로운 코드를 추가할 필요가 없습니다.
[[["이해하기 쉬움","easyToUnderstand","thumb-up"],["문제가 해결됨","solvedMyProblem","thumb-up"],["기타","otherUp","thumb-up"]],[["이해하기 어려움","hardToUnderstand","thumb-down"],["잘못된 정보 또는 샘플 코드","incorrectInformationOrSampleCode","thumb-down"],["필요한 정보/샘플이 없음","missingTheInformationSamplesINeed","thumb-down"],["번역 문제","translationIssue","thumb-down"],["기타","otherDown","thumb-down"]],["최종 업데이트: 2025-09-05(UTC)"],[],[],null,["# Cross-origin resource sharing (CORS)\n\n[Setup](/storage/docs/using-cors)\n[Configuration samples](/storage/docs/cors-configurations)\n\nThe [same-origin policy](https://www.w3.org/Security/wiki/Same_Origin_Policy) is a security policy enforced on\nclient-side web applications (like web browsers) to prevent interactions between\nresources from different origins. While useful for preventing malicious behavior,\nthis security measure also prevents legitimate interactions between known\norigins. For example, a script on a page hosted at\n`example.appspot.com` might need to use resources stored in a\nCloud Storage bucket at `example.storage.googleapis.com`. However, because\nthese are two different origins from the perspective of the browser, the browser\nwon't allow a script from `example.appspot.com` to fetch resources from\n`example.storage.googleapis.com`.\n\nThe [Cross Origin Resource Sharing](https://fetch.spec.whatwg.org/#http-cors-protocol) (CORS) spec was developed by\nthe [World Wide Web Consortium (W3C)](https://www.w3.org/) to get around this limitation.\nCloud Storage supports this specification by allowing you to configure\nyour buckets to support CORS. Continuing the previous example, you can configure\nthe `example.storage.googleapis.com` bucket so that a browser can share its\nresources with scripts from `example.appspot.com`.\n\nFor more information about CORS configuration components, see\n[Set Bucket CORS](/storage/docs/xml-api/put-bucket-metadata#cors-body).\n\nHow CORS works\n--------------\n\nThere are two types of CORS requests: simple and preflighted. A\n[simple request](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS#Simple_requests) can be initiated directly. A\n[preflighted request](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS#Preflighted_requests) must send a preliminary, \"preflight\"\nrequest to the server to get permission before the primary request can proceed.\nA request is preflighted if any of the following circumstances are true:\n\n- It uses methods other than `GET`, `HEAD` or `POST`.\n- It uses the `POST` method with a `Content-Type` other than `text/plain`, `application/x-www-form-urlencoded`, or `multipart/form-data`.\n- It sets custom headers. For example, `X-PINGOTHER`.\n\nThe following process occurs when a browser makes a simple request to\nCloud Storage:\n\n1. The browser adds the `Origin` header to the request. The `Origin` header\n contains the origin of the resource seeking to share the\n Cloud Storage bucket's resources, for example,\n `Origin:https://www.example.appspot.com`.\n\n2. Cloud Storage compares the HTTP method of the request and the value\n of the `Origin` header to the **Methods** and **Origins** information in the\n target bucket's CORS configuration to see if there are matches. If there are,\n Cloud Storage includes the `Access-Control-Allow-Origin` header in\n its response. The `Access-Control-Allow-Origin` header contains the value of\n the `Origin` header from the initial request.\n\n3. The browser receives the response and checks to see if the\n `Access-Control-Allow-Origin` value matches the domain specified in the\n original request. If they do match, the request succeeds. If they don't\n match, or if the `Access-Control-Allow-Origin` header is\n not present in the response, the request fails.\n\nA preflighted request performs the following steps first. If it is successful,\nit then follows the same process as a simple request:\n\n1. The browser sends an `OPTIONS` request containing the `Requested Method` and\n `Requested Headers` of the primary request.\n\n2. Cloud Storage responds back with the values of the HTTP methods and headers\n allowed by the targeted resource. If any of the method or header values in\n the preflight request aren't in the set of methods and headers allowed by\n the targeted resource, the request fails, and the primary request isn't\n sent.\n\nThis is a simplified description of CORS. For a more complete description,\nread the [Fetch](https://fetch.spec.whatwg.org/#http-cors-protocol) spec.\n\nCloud Storage CORS support\n--------------------------\n\nCloud Storage lets you set a CORS configuration at the bucket level\nonly. You can [set up a CORS configuration for a bucket](/storage/docs/using-cors) using a variety of\ntools; however, different Cloud Storage [endpoints](/storage/docs/request-endpoints) deal with CORS\nrequests in different ways:\n\n- JSON API endpoints always allow CORS requests and return default values in the\n CORS response headers, regardless of the configuration set on the bucket.\n\n- XML API endpoints only allow CORS requests based on the configuration on the\n bucket and return specific CORS header values in response to that configuration.\n\n- The authenticated browser download endpoint `storage.cloud.google.com` does\n not allow CORS requests. Note that the Google Cloud console provides this\n endpoint for each object's public URL link.\n\nYou can use either of the following XML API request URLs to obtain a response\nfrom Cloud Storage that contains the CORS headers: \n\n```\nstorage.googleapis.com/BUCKET_NAME\n``` \n\n```\nBUCKET_NAME.storage.googleapis.com\n```\n\nFor information about XML API request URLs, see [Request Endpoints](/storage/docs/request-endpoints).\n\nComponents of a CORS configuration\n----------------------------------\n\nWhen using the XML API, the values you set on your bucket's CORS configuration\ndetermine the CORS headers Cloud Storage returns in an HTTP response.\nWhen using the JSON API, Cloud Storage does not evaluate your bucket's\nconfiguration and instead returns default header values.\n\nThe following table describes the fields in a CORS configuration and the\nresponse behavior of the XML and JSON APIs. To learn how these fields are used,\nsee [CORS configuration examples](/storage/docs/cors-configurations).\n\n^1^ Names documented in the Field column are specific to the JSON API.\nWhen using the XML API to set a CORS configuration, use the\n[XML-specific format](/storage/docs/xml-api/put-bucket-metadata#cors-body).\n\n### Specifying multiple origins, methods, or headers\n\nTo learn how to set multiple origins, methods, or headers in a CORS\nconfiguration, see the following list:\n\n- When using the JSON API, you can specify multiple origins, methods, or headers\n by using a comma-separated array. For example, `\"method\": [\"GET\", \"PUT\"]`.\n\n | **Caution:** When you set a CORS configuration using the JSON API, requests from all origins are accepted regardless of the `origin` field value in the CORS configuration.\n- When using the XML API, you can specify multiple origins, methods, or headers\n by using separate elements. For example:\n\n ```xml\n \u003cMethods\u003e\n \u003cMethod\u003ePUT\u003c/Method\u003e\n \u003cMethod\u003eGET\u003c/Method\u003e\n \u003c/Methods\u003e\n ```\n- To allow requests to be made from any origin, set the origin to `*`.\n For example, `\"origin\": [\"*\"]` in the JSON API or `\u003cOrigin\u003e*\u003c/Origin\u003e` in the\n XML API. While this origin is helpful for testing configurations, in most\n cases, you'll want to restrict request origins to prevent unwanted usage of\n your resources.\n\nAdditional considerations\n-------------------------\n\nThe following table describes considerations when making requests using\ncredentials or access control headers:\n\nAllowing buckets to access external resources\n---------------------------------------------\n\nSometimes, you might want to allow scripts hosted in Cloud Storage to\naccess static resources that are hosted on a website external to\nCloud Storage. In this scenario, the website serves CORS headers so\nthat content on `storage.googleapis.com` is allowed access.\n\nAs a best practice, you should dedicate a specific bucket for this data access.\nThis approach prevents your site from inadvertently over-exposing static\nresources to all of `storage.googleapis.com`. For example, if you want to\ndedicate a bucket named `mybucket` for data access, you should have the website\nserve the CORS header\n`Access-Control-Allow-Origin: https://mybucket.storage.googleapis.com` instead\nof `Access-Control-Allow-Origin: https://storage.googleapis.com`.\n\nClient-side CORS support\n------------------------\n\nMost browsers use the `XMLHttpRequest` object to make a cross-domain request.\n`XMLHttpRequest` takes care of all the work of inserting the right headers and\nhandling the CORS interaction with the server. You don't have to add any new\ncode to take advantage of CORS support on Cloud Storage buckets.\n\nWhat's next\n-----------\n\n- Learn how to [enable CORS for your bucket](/storage/docs/using-cors).\n- Explore [CORS configuration examples](/storage/docs/cors-configurations), including an example that removes the CORS configuration on a bucket."]]
