---
title: "PutBucketPolicy"
slug: "ncloudstorage-putbucketpolicy"
updated: 2026-10-14T02:30:03Z
published: 2026-10-14T09:00:20Z
canonical: "api.ncloud-docs.com/ncloudstorage-putbucketpolicy"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://api.ncloud-docs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# PutBucketPolicy

Classic/VPC 환경에서 이용 가능합니다.

Ncloud Storage 버킷에 버킷 정책(Bucket Policy)을 등록하거나 기존 정책을 덮어씁니다. 버킷 정책은 버킷과 버킷 내 객체에 대해 누가 어떤 작업을 할 수 있는지 정의하는 JSON 문서입니다.

참고

버킷 정책에 대해 다음 내용을 참고해 주십시오.

- 버킷 정책은 버킷을 생성한 계정만 등록·조회·삭제할 수 있습니다. 다른 계정에는 위임할 수 없으며, Sub Account 사용자는 해당 액션의 IAM 권한이 있으면 등록·조회·삭제할 수 있습니다.
- 공개 정책은 `BlockPublicPolicy`가 켜져 있으면 저장되지 않고, `RestrictPublicBuckets`가 켜져 있으면 저장되어도 익명 요청과 다른 계정의 요청에 적용되지 않습니다. 버킷을 공개하려면 `PutPublicAccessBlock`으로 두 항목을 모두 해제해 주십시오.
- 모든 요청에 대해 거부(`Deny`)는 허용(`Allow`)보다 우선합니다.
- 자기 계정의 요청을 차단하는 정책을 등록한 경우에도 버킷을 생성한 계정의 메인 계정은 정책을 등록할 수 있습니다. Sub Account 사용자는 차단 정책의 적용을 받습니다.

## 요청

요청 형식을 설명합니다. 요청 형식은 다음과 같습니다.

| 메서드 | URI |
| --- | --- |
| PUT | - |

### 요청 헤더

요청 헤더에 대한 설명은 다음과 같습니다.

참고

Ncloud Storage API에서 공통으로 사용하는 헤더에 대한 정보는 [Ncloud Storage 요청 헤더](/docs/storage-ncloudstorage#%EC%9A%94%EC%B2%AD%ED%97%A4%EB%8D%94)를 참조해 주십시오.

| 필드 | 필수 여부 | 설명 |
| --- | --- | --- |
| `Content-MD5` | Optional | 요청 바디의 Base64 인코딩된 128비트 MD5 해시값 - 요청 바디 무결성 검증에 사용 |
| `x-amz-checksum-*` | Optional | 체크섬 해시값 - 키의 `*`에 사용한 알고리즘 입력 - 지원 알고리즘: `crc32` \| `crc32c` \| `sha1` \| `sha256` \| `crc64nvme` |

### 요청 쿼리 파라미터

요청 쿼리 파라미터에 대한 설명은 다음과 같습니다.

| 필드 | 타입 | 필수 여부 | 설명 |
| --- | --- | --- | --- |
| `policy` | String | Required | 버킷 정책 변경 요청 - 값 없이 키만 입력 |

### 요청 바디

요청 바디는 JSON 형식의 정책 문서입니다. 문서 구조는 Amazon S3 버킷 정책과 같지만 주체·작업·대상은 Ncloud Storage 표기를 사용하므로, Amazon S3 정책 문서를 그대로 사용할 수 없습니다. 요청 바디에 대한 설명은 다음과 같습니다.

| 필드 | 타입 | 필수 여부 | 설명 |
| --- | --- | --- | --- |
| `Version` | String | Optional | 정책 문법 버전 - `2012-10-17` \| `2008-10-17` - 미입력 시 `2008-10-17`로 저장 |
| `Id` | String | Optional | 정책 문서 식별자 |
| `Statement` | List | Required | 정책 구문 목록 - 구문 1개만 입력하는 경우 배열 없이 입력 가능 |
| `Statement.Sid` | String | Optional | 구문 식별자 - 구문 간 중복 가능 |
| `Statement.Effect` | String | Required | 구문 적용 방식 - `Allow` \| `Deny` - 대소문자 구분 없이 입력 가능하며 `Allow`, `Deny`로 저장 |
| `Statement.Principal` | String \| Object | Conditional | 구문을 적용할 주체 - [`Principal` 유효값](/docs/ncloudstorage-putbucketpolicy#Principal%EC%9C%A0%ED%9A%A8%EA%B0%92) 참조 - `NotPrincipal`과 동시 입력 불가하며 둘 중 하나는 필수 입력 |
| `Statement.NotPrincipal` | Object | Conditional | 구문 적용에서 제외할 주체 - `Effect`가 `Deny`인 구문에만 입력 가능 - `Principal`과 동시 입력 불가 |
| `Statement.Action` | String \| List | Conditional | 구문을 적용할 작업 - [`Action` 유효값](/docs/ncloudstorage-putbucketpolicy#Action%EC%9C%A0%ED%9A%A8%EA%B0%92) 참조 - `NotAction`과 동시 입력 불가하며 둘 중 하나는 필수 입력 |
| `Statement.NotAction` | String \| List | Conditional | 구문 적용에서 제외할 작업 - `Action`과 동시 입력 불가 |
| `Statement.Resource` | String \| List | Conditional | 구문을 적용할 대상 - [`Resource` 유효값](/docs/ncloudstorage-putbucketpolicy#Resource%EC%9C%A0%ED%9A%A8%EA%B0%92) 참조 - `NotResource`와 동시 입력 불가하며 둘 중 하나는 필수 입력 |
| `Statement.NotResource` | String \| List | Conditional | 구문 적용에서 제외할 대상 - `Resource`와 동시 입력 불가 |
| `Statement.Condition` | Object | Optional | 구문을 적용할 조건 - `{"조건 연산자": {"조건 키": "값"}}` 형식으로 입력 - [`Condition` 유효값](/docs/ncloudstorage-putbucketpolicy#Condition%EC%9C%A0%ED%9A%A8%EA%B0%92) 참조 - 조건을 여러 개 입력한 경우, 모두 충족해야 구문 적용 |

참고

요청 바디 관련하여 다음 내용을 참고해 주십시오.

- 정책 문서는 최대 20KB입니다.
- 정책 문서는 정규화하여 저장하므로, `GetBucketPolicy`로 조회한 문서는 입력한 문서와 표기가 다를 수 있습니다.

#### `Principal` 유효값

`Principal`과 `NotPrincipal`에는 모든 주체를 뜻하는 `"*"` 또는 주체의 NRN(Ncloud Resource Name)을 입력합니다. NRN은 직접 조합하지 않고 콘솔에서 확인하여 복사해 주십시오.

| 주체 | 입력 값 | NRN 확인 위치 |
| --- | --- | --- |
| 모든 주체(익명 포함) | `"*"` 또는 `{"NCP": "*"}` | - |
| 메인 계정 | `{"NCP": "메인 계정의 NRN"}` | 콘솔 > My Account > 계정 및 보안 관리 > 계정 관리 > 계정 정보 > NRN |
| Sub Account | `{"NCP": "Sub Account의 NRN"}` | 콘솔 > Sub Account > Sub Accounts > 해당 서브 계정 - [서브 계정 생성 및 관리](https://guide.ncloud-docs.com/docs/subaccount-use) 참조 |
| Role | `{"NCP": "Role의 NRN"}` | 콘솔 > Sub Account > Roles > 해당 역할 - [정책 및 역할 관리](https://guide.ncloud-docs.com/docs/subaccount-policy-role) 참조 |

참고

Principal 관련하여 다음 내용을 참고해 주십시오.

- 여러 주체를 입력하는 경우 `NCP` 값을 배열로 입력하며, 하나라도 일치하면 구문이 적용됩니다.
- 메인 계정의 NRN을 `Principal`에 입력하면 그 계정의 Sub Account와 Role까지 적용됩니다. 단, `NotPrincipal`에 입력한 경우에는 메인 계정만 제외 대상이 됩니다.
- 모든 주체를 뜻하는 `"*"`를 제외하고, NRN 값 안에는 와일드카드(`*`, `?`)를 사용할 수 없습니다. <예시> `nrn:PUB:IAM::12345678:SubAccount/*`는 오류를 반환합니다.

#### `Action` 유효값

`Action`과 `NotAction`에 입력할 수 있는 액션은 [Ncloud Storage 권한 관리](https://guide.ncloud-docs.com/docs/ncloudstorage-subaccount#%EC%82%AC%EC%9A%A9%EC%9E%90%EC%A0%95%EC%9D%98%EC%A0%95%EC%B1%85)를 참조해 주십시오. 대소문자를 구분하지 않으며, 와일드카드(`*`, `?`)를 사용할 수 있습니다.

참고

Action 관련하여 다음 내용을 참고해 주십시오.

- 액션의 대상 수준과 `Resource`의 대상 수준이 일치해야 합니다. 객체 대상 액션에는 객체 NRN(버킷 NRN 뒤에 객체 키를 붙인 값)을, 버킷 대상 액션에는 버킷 NRN을 입력해 주십시오.
- `NotAction`은 액션 이름을 검사하지 않습니다. 존재하지 않는 이름을 입력하면 제외 대상이 없는 것으로 처리되어 구문이 모든 액션에 적용됩니다.

#### `Resource` 유효값

`Resource`와 `NotResource`에는 요청을 보낸 버킷의 NRN(Ncloud Resource Name)을 입력합니다. NRN은 직접 조합하지 않고 콘솔에서 확인하여 복사해 주십시오.

| 대상 | 입력 값 | NRN 확인 위치 |
| --- | --- | --- |
| 버킷 | 버킷의 NRN | 콘솔 > Management & Governance > Resource Manager > Resource > 해당 버킷 > 상세 정보 > NRN |
| 버킷 내 객체 | 버킷의 NRN 뒤에 `/`와 객체 키를 덧붙인 값 - 객체 키에 와일드카드(`*`, `?`) 사용 가능 | 위와 같음 |

참고

Resource 관련하여 다음 내용을 참고해 주십시오.

- 요청을 보낸 버킷이 아닌 다른 버킷의 NRN이나 `"*"`를 입력하면 오류를 반환합니다.

#### `Condition` 유효값

`Condition`에 입력할 수 있는 조건 연산자는 다음과 같습니다. 연산자 이름은 대소문자를 구분합니다.

| 조건 연산자 | 설명 |
| --- | --- |
| `IpAddress` | 접속 IP 주소가 지정한 대역에 포함되면 충족 |
| `NotIpAddress` | 접속 IP 주소가 지정한 대역에 포함되지 않으면 충족 |
| `StringEquals` | 문자열이 일치하면 충족 |
| `StringLike` | 와일드카드(`*`, `?`)를 포함한 문자열 패턴이 일치하면 충족 |
| `Bool` | 불리언 값이 일치하면 충족 |

`Condition`에 입력할 수 있는 조건 키는 다음과 같습니다.

| 조건 키 | 타입 | 설명 |
| --- | --- | --- |
| `aws:SourceIp` | IP | 요청을 보낸 IP 주소 - IP 주소 또는 CIDR 형식 |
| `aws:SecureTransport` | Boolean | HTTPS 요청 여부 |
| `aws:Referer` | String | 요청 헤더의 `Referer` 값 |
| `s3:prefix` | String | 목록 조회 요청의 `prefix` 값 - 목록 조회 액션에만 입력 가능 |
| `s3:delimiter` | String | 목록 조회 요청의 `delimiter` 값 - 목록 조회 액션에만 입력 가능 |
| `ncp:principalType` | String | 요청을 보낸 주체의 유형 - `MainAccount` \| `IamUser` \| `IamRole` \| `Anonymous` |
| `ncp:principalAccount` | String | 요청을 보낸 주체가 속한 계정의 계정 번호 |

참고

Condition 관련하여 다음 내용을 참고해 주십시오.

- 조건 연산자 뒤에 `IfExists`를 붙이면(<예시> `StringEqualsIfExists`) 요청에 해당 조건 키가 없을 때 조건을 충족한 것으로 처리합니다. `Bool` 연산자에도 사용할 수 있습니다.
- 위 표에 없는 조건 연산자와 조건 키는 사용할 수 없습니다.
- 주체를 지정하는 조건은 `ncp:` 이름만 사용할 수 있습니다. `aws:PrincipalArn`, `aws:userid` 등 `aws:` 형식의 주체 조건 키는 사용할 수 없습니다.

### 요청 예시

요청 예시는 다음과 같습니다.

#### 조건 없이 허용하는 경우

인증 정보 없이 버킷 내 모든 객체를 읽을 수 있도록 허용하는 요청 예시는 다음과 같습니다.

```
PUT /?policy HTTP/1.1
Host: bucket.kr.ncloudstorage.com

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "PublicRead",
      "Effect": "Allow",
      "Principal": "*",
      "Action": "View/GetObject",
      "Resource": "nrn:PUB:NcloudStorage:KR:12345678:Bucket/2e2b461e-303f-4928-9e81-302d1aea9629/*"
    }
  ]
}
```

#### 조건을 지정하는 경우

특정 Sub Account와 Role에 대해 지정한 IP 대역에서만 객체 조회를 허용하는 요청 예시는 다음과 같습니다.

```
PUT /?policy HTTP/1.1
Host: bucket.kr.ncloudstorage.com

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AllowFromOfficeOnly",
      "Effect": "Allow",
      "Principal": {
        "NCP": [
          "nrn:PUB:IAM::12345678:SubAccount/8f14e45f-ceea-467a-9cbd-3a1b0f5c9e21",
          "nrn:PUB:IAM::12345678:Role/1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed"
        ]
      },
      "Action": [
        "View/GetObject",
        "View/ListBucket"
      ],
      "Resource": [
        "nrn:PUB:NcloudStorage:KR:12345678:Bucket/2e2b461e-303f-4928-9e81-302d1aea9629",
        "nrn:PUB:NcloudStorage:KR:12345678:Bucket/2e2b461e-303f-4928-9e81-302d1aea9629/*"
      ],
      "Condition": {
        "IpAddress": {
          "aws:SourceIp": ["10.0.0.0/24", "192.168.0.1"]
        }
      }
    }
  ]
}
```

## 응답

응답 형식을 설명합니다.

### 응답 헤더

응답 헤더에 대한 설명은 다음과 같습니다.

참고

Ncloud Storage API에서 공통으로 사용하는 헤더에 대한 정보는 [Ncloud Storage 응답 헤더](/docs/storage-ncloudstorage#%EC%9D%91%EB%8B%B5%ED%97%A4%EB%8D%94)를 참조해 주십시오.

### 응답 상태 코드

응답 상태 코드에 대한 설명은 다음과 같습니다.

참고

Ncloud Storage API에서 공통으로 사용하는 응답 상태 코드에 대한 정보는 [Ncloud Storage 응답 상태 코드](/docs/storage-ncloudstorage#%EC%9D%91%EB%8B%B5%EC%83%81%ED%83%9C%EC%BD%94%EB%93%9C)를 참조해 주십시오.

| 오류 코드 | HTTP 상태 코드 | 설명 |
| --- | --- | --- |
| `MalformedPolicy` | 400 | 정책 문서가 유효하지 않음 - JSON 형식이 아니거나 첫 문자가 `{`가 아님 - 필수 필드 누락, 알 수 없는 필드, `Action`·`NotAction`처럼 함께 쓸 수 없는 필드 동시 입력 - `Principal`·`Action`·`Resource`·`Condition` 값이 유효값이 아님(다른 버킷의 NRN, 지원하지 않는 조건 키·연산자 이름 포함) - 요청 바디가 200KB를 초과하거나 정규화한 문서가 20KB를 초과 |
| `NotImplemented` | 400 | 지원하지 않는 조건 연산자 또는 액션을 입력함 - `StringNotEquals`, `Null`, `Numeric*`, `Date*`, `ForAnyValue:*` 등 |
| `AccessDenied` | 403 | 정책을 등록할 수 없음 - `BlockPublicPolicy`가 켜진 버킷에 공개 정책을 등록함 - 버킷을 생성한 계정이 아닌 계정의 요청 |
| `MethodNotAllowed` | 405 | 버킷을 생성한 계정이 아닌 계정의 요청이며, 버킷 정책이 그 계정에 `Change/PutBucketPolicy`를 허용함 |

### 응답 예시

응답 예시는 다음과 같습니다.

```
HTTP/1.1 204 No Content
```