인증 (Authentication)

기존 S3 호환 SDK나 XML API에서 사용할 Access Key 역할을 하는 API 토큰을 생성할 수 있어요.

출처: 문서

본문

참고

이 페이지에는 R2 전용 API 토큰 생성 방법이 나와 있어요. 다른 서비스의 API 토큰 생성 방법은 Create API token 문서에 설명되어 있으니, 그것과는 다르다는 점을 참고해 주세요.

API 토큰을 생성하려면 먼저 R2를 구매해야 해요.

API 토큰을 만들려면:

1. Cloudflare 대시보드에서 R2 object storage 페이지로 이동해요. Overview로 이동 ↗
2. Account Details 섹션에서 API Tokens 옆의 Manage를 선택해요.
3. 다음 중 하나를 만들어요:
   • Create Account API token - 이 토큰은 Cloudflare 계정 자체에 연결되며 인증된 시스템이나 사용자라면 누구나 사용할 수 있어요. 역할과 권한 요구사항은 Account API tokens을 참고해 주세요. 이 토큰은 수동으로 해지하거나 미리 설정한 만료 날짜에 도달할 때까지 유효해요.
   • Create User API token - 이 토큰은 개별 Cloudflare 사용자에게 연결돼요. 개인 권한을 상속하며, 사용자가 계정에서 제거되면 비활성화돼요.
4. Permissions 아래에서 토큰에 대한 권한 유형을 선택해요. 각 옵션에 대한 설명은 권한을 참고해 주세요.
5. (선택 사항) Object Read and Write 또는 Object Read 권한을 선택했다면 토큰을 버킷 집합으로 범위를 제한할 수 있어요.
6. Create Account API token 또는 Create User API token을 선택해요.

토큰이 성공적으로 생성되면 Secret Access Key와 Access Key ID 값을 확인해요. 이 값들은 각각 Client Secret과 Client ID라고 불리는 경우도 많아요.

주의

이 단계 이후에는 Secret Access Key에 다시 접근할 수 없어요. 두 값을 복사해서 기록해 두어 잃어버리지 않도록 해요.

S3 클라이언트의 endpoint도 https://<ACCOUNT_ID>.r2.cloudflarestorage.com으로 설정해야 해요.

Cloudflare 대시보드에서 계정 ID를 찾아보세요.

저장소(관할권)와 함께 생성된 버킷은 관할권별 엔드포인트로 접근해야 해요:

• 유럽 연합(EU): https://<ACCOUNT_ID>.eu.r2.cloudflarestorage.com
• FedRAMP: https://<ACCOUNT_ID>.fedramp.r2.cloudflarestorage.com
• 미국(US): https://<ACCOUNT_ID>.us.r2.cloudflarestorage.com

주의

관할권 버킷은 해당 관할권 엔드포인트로만 접근할 수 있어요. 대부분의 S3 클라이언트는 여러 endpoint를 구성하게 하지 않으므로, 일반적으로 관할권마다 클라이언트를 하나씩 초기화해야 해요.

권한 (Permissions)

고려사항

• Basin Catalog는 Admin Read & Write 또는 Admin Read only 권한이 필요해요. 읽기 전용 카탈로그 작업(namespace 나열, 테이블 로드, 데이터 쿼리 등)은 Admin Read only로 동작하고, 쓰기 작업(테이블 생성·삭제, 트랜잭션 커밋 등)은 Admin Read & Write가 필요해요. 자세한 내용은 Iceberg 엔진 인증을 참고해 주세요.
• Object Read & Write와 Object Read only 권한은 Cloudflare REST API가 아니라 S3 호환 API에서만 지원돼요.

API로 API 토큰 생성

API를 통해 API 토큰을 만들고 이를 사용해 해당 Access Key ID와 Secret Access Key 값을 생성할 수 있어요. 시작하려면 API로 API 토큰 생성을 참고해 주세요. 아래는 R2에 해당하는 구체적인 내용이에요.

Access Policy

Access Policy는 토큰이 접근할 수 있는 리소스와 그 권한을 지정해요.

리소스 (Resources)

R2에 해당하는 리소스 유형은 Account와 Bucket 두 가지가 있어요. Account 리소스 유형에 대한 자세한 내용은 Account를 참고해 주세요.

Bucket

R2 버킷 집합 또는 계정의 모든 버킷을 포함해요.

특정 버킷은 다음과 같이 표현돼요:

"com.cloudflare.edge.r2.bucket.<ACCOUNT_ID>_<JURISDICTION>_<BUCKET_NAME>": "*"

• ACCOUNT_ID: Zone 및 account ID 찾기를 참고해 주세요.
• JURISDICTION: R2 버킷이 있는 관할권이에요. 특정 관할권에서 생성되지 않은 버킷의 경우 이 값은 default예요.
• BUCKET_NAME: Access Policy가 적용되는 버킷의 이름이에요.

계정의 모든 버킷은 다음과 같이 표현돼요:

"com.cloudflare.api.account.<ACCOUNT_ID>": {
  "com.cloudflare.edge.r2.bucket.*": "*"
}

• ACCOUNT_ID: Zone 및 account ID 찾기를 참고해 주세요.

권한 그룹 (Permission groups)

어떤 권한 그룹을 적용할지 결정해요.

Access Policy 예시

[
	{
		"id": "f267e341f3dd4697bd3b9f71dd96247f",
		"effect": "allow",
		"resources": {
			"com.cloudflare.edge.r2.bucket.4793d734c0b8e484dfc37ec392b5fa8a_default_my-bucket": "*",
			"com.cloudflare.edge.r2.bucket.4793d734c0b8e484dfc37ec392b5fa8a_eu_my-eu-bucket": "*"
		},
		"permission_groups": [
			{
				"id": "6a018a9f2fc74eb6b293b0c548f38b39",
				"name": "Workers R2 Storage Bucket Item Read"
			}
		]
	}
]

API 토큰에서 S3 API 자격 증명 가져오기

Create Token API의 응답에서 Access Key ID와 Secret Access Key 값을 얻을 수 있어요:

• Access Key ID: API 토큰의 id.
• Secret Access Key: API 토큰 value의 SHA-256 해시.

JavaScript, Python, Go 예시가 있는 튜토리얼은 auth 토큰으로 R2 API 인증하기를 참고해 주세요.

임시 자격 증명 (Temporary credentials)

API 토큰에서 파생되는 수명이 짧고 범위가 제한된 자격 증명을 발급하려면 임시 자격 증명을 사용해요. R2는 임시 자격 증명 API를 통해 생성하거나, 상위 토큰의 secret access key로 JWT를 서명해 로컬에서 생성하는 방식을 지원해요.

더 알아보기 (Learn more)

• 임시 자격 증명 — API 토큰에서 파생되는 수명이 짧은 자격 증명
• auth 토큰으로 R2 API 인증하기 — JavaScript, Python, Go 예시
• Create API token — 일반적인 API 토큰 생성 방법