이 페이지에서는 사용자 인증 정보 액세스 경계를 사용하여 단기 사용자 인증 정보가 사용할 수 있는 Identity and Access Management(IAM) 권한을 축소 또는 제한하는 방법을 설명합니다.
사용자 인증 정보 액세스 경계를 사용하여 서비스 계정을 나타내지만 서비스 계정보다 권한이 적은 OAuth 2.0 액세스 토큰을 생성할 수 있습니다. 예를 들어 고객 중 한 명이 개발자가 제어하는 Cloud Storage 데이터에 액세스해야 하는 경우 다음을 수행할 수 있습니다.
- 개발자가 소유한 모든 Cloud Storage 버킷에 액세스할 수 있는 서비스 계정을 만듭니다.
- 서비스 계정에 대한 OAuth 2.0 액세스 토큰을 생성합니다.
- 고객 데이터가 포함된 버킷에 대한 액세스만 허용하는 사용자 인증 정보 액세스 경계를 적용합니다.
사용자 인증 정보 액세스 경계 작동 방식
권한을 축소하려면 단기 사용자 인증 정보가 액세스할 수 있는 리소스와 각 리소스에서 사용할 수 있는 권한의 상한값을 지정하는 사용자 인증 정보 액세스 경계를 정의합니다. 그런 다음 단기 사용자 인증 정보를 만든 후 사용자 인증 정보 액세스 경계를 준수하는 새 사용자 인증 정보로 교환할 수 있습니다.
주 구성원에게 각 세션에 대한 고유한 권한 집합을 부여해야 하는 경우 사용자 인증 정보 액세스 경계를 사용하는 것이 여러 서비스 계정을 만들고 각 서비스 계정에 다른 역할 집합을 부여하는 것보다 더 효율적일 수 있습니다.
사용자 인증 정보 액세스 경계 예시
다음 섹션에서는 사용자 인증 정보 액세스 경계 예시를 통해 일반적인 사용 사례를 보여줍니다. 축소된 토큰을 OAuth 2.0 액세스 토큰으로 교환할 때 사용자 인증 정보 액세스 경계를 사용합니다.
버킷에 대한 권한 제한
다음 예시에서는 간단한 사용자 인증 정보 액세스 경계를 보여줍니다. 이 사용자 인증 정보 액세스 경계는 Cloud Storage 버킷 example-bucket
에 적용되고 스토리지 객체 뷰어 역할(roles/storage.objectViewer
)에 포함된 권한에 상한값을 설정합니다.
{
"accessBoundary": {
"accessBoundaryRules": [
{
"availablePermissions": [
"inRole:roles/storage.objectViewer"
],
"availableResource": "//storage.googleapis.com/projects/_/buckets/example-bucket"
}
]
}
}
여러 버킷에 대한 권한 제한
다음 예시에서는 여러 버킷에 대한 규칙이 포함된 사용자 인증 정보 액세스 경계를 보여줍니다.
- Cloud Storage 버킷
example-bucket-1
: 이 버킷에는 스토리지 객체 뷰어 역할(roles/storage.objectViewer
)의 권한만 사용할 수 있습니다. - Cloud Storage 버킷
example-bucket-2
: 이 버킷에는 스토리지 객체 생성자 역할(roles/storage.objectCreator
)의 권한만 사용할 수 있습니다.
{
"accessBoundary": {
"accessBoundaryRules": [
{
"availablePermissions": [
"inRole:roles/storage.objectViewer"
],
"availableResource": "//storage.googleapis.com/projects/_/buckets/example-bucket-1"
},
{
"availablePermissions": [
"inRole:roles/storage.objectCreator"
],
"availableResource": "//storage.googleapis.com/projects/_/buckets/example-bucket-2"
}
]
}
}
특정 객체에 대한 권한 제한
IAM 조건을 사용하여 주 구성원이 액세스할 수 있는 Cloud Storage 객체를 지정할 수도 있습니다. 예를 들어 이름이 customer-a
로 시작하는 객체에 권한을 부여하는 조건을 추가할 수 있습니다.
{ "accessBoundary": { "accessBoundaryRules": [ { "availablePermissions": [ "inRole:roles/storage.objectViewer" ], "availableResource": "//storage.googleapis.com/projects/_/buckets/example-bucket", "availabilityCondition": { "expression" : "resource.name.startsWith('projects/_/buckets/example-bucket/objects/customer-a')" } } ] } }
객체 나열 시 권한 제한
Cloud Storage 버킷의 객체를 나열하는 경우 객체 리소스가 아닌 버킷 리소스에서 메서드를 호출합니다. 따라서 list 요청에 대한 조건이 평가되고 조건이 리소스 이름을 참조하는 경우 리소스 이름은 버킷 내 객체가 아니라 버킷을 식별합니다. 예를 들어 example-bucket
에 있는 객체를 나열하는 경우 리소스 이름은 projects/_/buckets/example-bucket
입니다.
이러한 명명 규칙으로 인해 객체를 나열할 때 예기치 않은 동작이 발생할 수 있습니다.
예를 들어 프리픽스가 customer-a/invoices/
인 example-bucket
의 객체에 대한 보기 액세스를 허용하는 사용자 인증 정보 액세스 경계가 필요하다고 가정해 보겠습니다.
사용자 인증 정보 액세스 경계에서 다음 조건을 사용해 볼 수 있습니다.
미완료: 리소스 이름만 확인하는 조건
resource.name.startsWith('projects/_/buckets/example-bucket/objects/customer-a/invoices/')
이 조건은 객체 읽기에서는 작동하지만 객체를 나열하는 경우에는 작동하지 않습니다.
- 주 구성원이
customer-a/invoices/
프리픽스가 있는example-bucket
의 객체를 읽으려고 하면 조건은true
로 평가됩니다. - 주 구성원이 이 프리픽스가 있는 객체를 나열하려고 하면 조건은
false
로 평가됩니다.resource.name
값은projects/_/buckets/example-bucket
이며projects/_/buckets/example-bucket/objects/customer-a/invoices/
로 시작하지 않습니다.
이 문제를 방지하려면 조건에서 resource.name.startsWith()
를 사용하고 storage.googleapis.com/objectListPrefix
라는 API 속성을 확인하면 됩니다. 이 속성에는 객체 목록을 필터링하는 데 사용된 prefix
매개변수의 값이 포함됩니다. 따라서 prefix
매개변수 값을 참조하는 조건을 작성할 수 있습니다.
다음 예시에서는 조건에서 API 속성을 사용하는 방법을 보여줍니다. 프리픽스가 customer-a/invoices/
인 example-bucket
의 객체를 읽기 및 나열할 수 있습니다.
완료: 리소스 이름과 프리픽스를 확인하는 조건
resource.name.startsWith('projects/_/buckets/example-bucket/objects/customer-a/invoices/') || api.getAttribute('storage.googleapis.com/objectListPrefix', '') .startsWith('customer-a/invoices/')
이제 사용자 인증 정보 액세스 경계에서 이 조건을 사용할 수 있습니다.
{
"accessBoundary": {
"accessBoundaryRules": [
{
"availablePermissions": [
"inRole:roles/storage.objectViewer"
],
"availableResource": "//storage.googleapis.com/projects/_/buckets/example-bucket",
"availabilityCondition": {
"expression":
"resource.name.startsWith('projects/_/buckets/example-bucket/objects/customer-a/invoices/') || api.getAttribute('storage.googleapis.com/objectListPrefix', '').startsWith('customer-a/invoices/')"
}
}
]
}
}
시작하기 전에
사용자 인증 정보 액세스 경계를 사용하기 전에 다음 요구사항을 충족하는지 확인하세요.
다른 Google Cloud 서비스가 아닌 Cloud Storage의 권한만 축소해야 합니다.
다른 Google Cloud 서비스의 권한을 축소해야 하는 경우 서비스 계정을 여러 개 만들고 서비스 계정마다 서로 다른 역할 집합을 부여하면 됩니다.
인증에 OAuth 2.0 액세스 토큰을 사용할 수 있습니다. 다른 유형의 단기 사용자 인증 정보는 사용자 인증 정보 액세스 경계를 지원하지 않습니다.
또한 필수 API를 사용 설정해야 합니다.
-
Enable the IAM and Security Token Service APIs.
권한이 축소된 단기 사용자 인증 정보 만들기
권한이 축소된 OAuth 2.0 액세스 토큰을 만들려면 다음 단계를 따릅니다.
- 사용자 또는 서비스 계정에 적절한 IAM 역할을 부여합니다.
- 사용자 또는 서비스 계정에 사용할 수 있는 권한의 상한값을 설정하는 사용자 인증 정보 액세스 경계를 정의합니다.
- 사용자 또는 서비스 계정에 대한 OAuth 2.0 액세스 토큰을 만듭니다.
- 사용자 인증 정보 액세스 경계를 준수하는 새 토큰으로 OAuth 2.0 액세스 토큰을 교환합니다.
권한이 축소된 새로운 OAuth 2.0 액세스 토큰을 사용하여 Cloud Storage에 대한 요청을 인증할 수 있습니다.
IAM 역할 부여
사용자 인증 정보 액세스 경계는 리소스에 사용 가능한 권한의 상한값을 설정합니다. 주 구성원의 권한을 뺄 수 있지만 주 구성원이 아직 보유하지 않은 권한을 추가할 수는 없습니다.
따라서 주 구성원에게 Cloud Storage 버킷에서 또는 프로젝트와 같은 상위 수준의 리소스에서 필요한 권한을 제공하는 역할을 부여해야 합니다.
예를 들어 서비스 계정이 버킷에 객체를 만들 수 있도록 권한을 축소한 단기 사용자 인증 정보를 만들어야 한다고 가정합니다.
- 최소한 스토리지 객체 생성자 역할(
roles/storage.objectCreator
)과 같이storage.objects.create
권한이 포함된 역할을 서비스 계정에 부여해야 합니다. 또한 사용자 인증 정보 액세스 경계에 이 권한이 있어야 합니다. - 스토리지 객체 관리자 역할(
roles/storage.objectAdmin
)과 같이 더 많은 권한이 포함된 역할을 부여할 수도 있습니다. 서비스 계정은 역할 부여 및 사용자 인증 정보 액세스 경계 모두에 표시되는 권한만 사용할 수 있습니다.
Cloud Storage의 사전 정의된 역할은 Cloud Storage 역할을 참조하세요.
사용자 인증 정보 액세스 경계의 구성요소
사용자 인증 정보 액세스 경계는 액세스 경계 규칙 목록을 포함하는 객체입니다. 각 규칙에는 다음 정보가 포함됩니다.
- 규칙이 적용되는 리소스
- 리소스에서 사용할 수 있는 권한의 상한값
- 선택사항: 권한을 추가로 제한하는 조건. 조건에는 다음이 포함됩니다.
true
또는false
로 평가되는 조건 표현식.true
로 평가되면 액세스가 허용됩니다. 그렇지 않으면 액세스가 거부됩니다.- 선택사항: 조건을 식별하는 제목
- 선택사항: 조건에 대한 자세한 정보가 포함된 설명
단기 사용자 인증 정보에 사용자 인증 정보 액세스 경계를 적용하면 사용자 인증 정보는 사용자 인증 정보 액세스 경계의 리소스에만 액세스할 수 있습니다. 다른 리소스에서 사용할 수 있는 권한은 없습니다.
사용자 인증 정보 액세스 경계는 최대 10개의 액세스 경계 규칙을 포함할 수 있습니다. 각 단기 사용자 인증 정보에는 하나의 사용자 인증 정보 액세스 경계만 적용할 수 있습니다.
JSON 객체로 표현할 경우, 사용자 인증 정보 액세스 경계에는 다음과 같은 필드가 포함됩니다.
필드 | |
---|---|
accessBoundary |
사용자 인증 정보 액세스 경계의 래퍼입니다. |
accessBoundary.accessBoundaryRules[] |
단기 사용자 인증 정보에 적용할 액세스 경계 규칙의 목록입니다. |
accessBoundary.accessBoundaryRules[].availablePermissions[] |
리소스에 사용 가능한 권한의 상한값을 정의하는 목록입니다.
각 값은 프리픽스 |
accessBoundary.accessBoundaryRules[].availableResource |
규칙이 적용되는 Cloud Storage 버킷의 전체 리소스 이름입니다. |
accessBoundary.accessBoundaryRules[].availabilityCondition |
선택사항. 권한 사용을 특정 Cloud Storage 객체로 제한하는 조건입니다. Cloud Storage 버킷의 모든 객체가 아닌 특정 객체에 대한 권한을 부여하려면 이 필드를 사용합니다. |
accessBoundary.accessBoundaryRules[].availabilityCondition.expression |
권한이 있는 Cloud Storage 객체를 지정하는 조건 표현식입니다.
조건 표현식에서 특정 객체를 참조하는 방법은 |
accessBoundary.accessBoundaryRules[].availabilityCondition.title |
선택사항. 조건 목적을 식별하는 짧은 문자열입니다. |
accessBoundary.accessBoundaryRules[].availabilityCondition.description |
선택사항. 조건 목적에 대한 세부정보입니다. |
JSON 형식의 예시는 이 페이지의 사용자 인증 정보 액세스 경계 예시를 참조하세요.
OAuth 2.0 액세스 토큰 만들기
권한이 축소된 단기 사용자 인증 정보를 만들려면 일반 OAuth 2.0 액세스 토큰을 만들어야 합니다. 그러면 일반 사용자 인증 정보를 권한이 축소된 사용자 인증 정보와 교환할 수 있습니다. 액세스 토큰을 만들 때 OAuth 2.0 범위 https://www.googleapis.com/auth/cloud-platform
을 사용합니다.
서비스 계정에 대한 액세스 토큰을 만들려면 서버 간 OAuth 2.0 흐름을 완료하거나 Service Account Credentials API를 사용하여 OAuth 2.0 액세스 토큰을 생성할 수 있습니다.
사용자의 액세스 토큰을 만들려면 OAuth 2.0 액세스 토큰 가져오기를 참조하세요. OAuth 2.0 Playground를 사용하여 자신의 Google 계정에 대한 액세스 토큰을 만들 수도 있습니다.
OAuth 2.0 액세스 토큰 교환
OAuth 2.0 액세스 토큰을 만든 후에 액세스 토큰을 사용자 인증 정보 액세스 경계를 준수하는 권한이 축소된 토큰으로 교환할 수 있습니다. 이 프로세스에는 일반적으로 토큰 브로커 및 토큰 소비자가 포함됩니다.
토큰 브로커는 사용자 인증 정보 액세스 경계를 정의하고 액세스 토큰을 범위가 축소된 토큰으로 교환합니다.
토큰 브로커는 지원되는 인증 라이브러리를 사용하여 액세스 토큰을 자동으로 교환할 수도 있고, 보안 토큰 서비스를 호출하여 수동으로 토큰을 교환할 수도 있습니다.
토큰 소비자는 토큰 브로커에서 권한이 축소된 액세스 토큰을 요청한 다음 권한이 축소된 액세스 토큰을 사용하여 다른 작업을 수행합니다.
토큰 소비자는 지원되는 인증 라이브러리를 사용하여 만료되기 전에 액세스 토큰을 자동으로 새로고침할 수 있습니다. 또는 토큰을 수동으로 새로고침하거나 토큰을 갱신하지 않고 만료시킬 수도 있습니다.
자동으로 액세스 토큰 교환 및 새로고침
다음 언어 중 하나를 사용하여 토큰 브로커와 토큰 소비자를 만들 경우 Google의 인증 라이브러리를 사용하여 자동으로 토큰을 교환하고 새로고침할 수 있습니다.
Go
Go의 경우 golang.org/x/oauth2
패키지 v0.0.0-20210819190943-2bc19b11175f 버전 이상으로 토큰을 자동으로 교환하고 새로고침할 수 있습니다.
사용 중인 이 패키지의 버전을 확인하려면 애플리케이션 디렉터리에서 다음 명령어를 실행합니다.
go list -m golang.org/x/oauth2
다음 예시에서는 토큰 브로커가 권한이 축소된 토큰을 생성하는 방법을 보여줍니다.
다음 예시에서는 토큰 소비자가 새로고침 핸들러를 사용하여 권한이 축소된 토큰을 자동으로 가져오고 새로고침하는 방법을 보여줍니다.
Java
자바의 경우 com.google.auth:google-auth-library-oauth2-http
아티팩트 버전 1.1.0 이상을 사용하여 자동으로 토큰을 교환하고 새로고침할 수 있습니다.
사용 중인 이 아티팩트의 버전을 확인하려면 애플리케이션 디렉터리에서 다음 Maven 명령어를 실행합니다.
mvn dependency:list -DincludeArtifactIds=google-auth-library-oauth2-http
다음 예시에서는 토큰 브로커가 권한이 축소된 토큰을 생성하는 방법을 보여줍니다.
다음 예시에서는 토큰 소비자가 새로고침 핸들러를 사용하여 권한이 축소된 토큰을 자동으로 가져오고 새로고침하는 방법을 보여줍니다.
Node.js
Node.js의 경우 google-auth-library
패키지 버전 7.9.0 이상을 사용하여 토큰을 자동으로 교환하고 새로고침할 수 있습니다.
사용 중인 이 패키지의 버전을 확인하려면 애플리케이션 디렉터리에서 다음 명령어를 실행합니다.
npm list google-auth-library
다음 예시에서는 토큰 브로커가 권한이 축소된 토큰을 생성하는 방법을 보여줍니다.
다음 예시에서는 토큰 소비자가 권한이 축소된 토큰을 자동으로 가져오고 새로고침하는 새로고침 핸들러를 제공하는 방법을 보여줍니다.
Python
Python의 경우 google-auth
패키지 버전 2.0.0 이상을 사용하여 토큰을 자동으로 교환하고 새로고침할 수 있습니다.
사용 중인 이 패키지의 버전을 확인하려면 패키지가 설치된 환경에서 다음 명령어를 실행합니다.
pip show google-auth
다음 예시에서는 토큰 브로커가 권한이 축소된 토큰을 생성하는 방법을 보여줍니다.
다음 예시에서는 토큰 소비자가 권한이 축소된 토큰을 자동으로 가져오고 새로고침하는 새로고침 핸들러를 제공하는 방법을 보여줍니다.
수동으로 액세스 토큰 교환 및 새로고침
토큰 브로커는 Security Token Service API를 사용하여 액세스 토큰을 권한이 축소된 액세스 토큰으로 교환할 수 있습니다. 그런 다음 권한이 축소된 토큰을 토큰 소비자에게 제공할 수 있습니다.
액세스 토큰을 교환하려면 다음 HTTP 메서드와 URL을 사용합니다.
POST https://sts.googleapis.com/v1/token
요청의 Content-Type
헤더를 application/x-www-form-urlencoded
로 설정합니다. 요청 본문에 다음 필드를 포함합니다.
필드 | |
---|---|
grant_type |
|
options |
백분율 인코딩으로 인코딩된 JSON 형식의 사용자 인증 정보 액세스 경계입니다. |
requested_token_type |
|
subject_token |
교환하려는 OAuth 2.0 액세스 토큰입니다. |
subject_token_type |
|
응답은 다음 필드를 포함하는 JSON 객체입니다.
필드 | |
---|---|
access_token |
사용자 인증 정보 액세스 경계를 준수하는 권한이 축소된 OAuth 2.0 액세스 토큰입니다. |
expires_in |
권한이 축소된 토큰이 만료될 때까지의 시간(초)입니다. 이 필드는 원본 액세스 토큰이 서비스 계정을 나타내는 경우에만 존재합니다. 이 필드가 없으면 권한이 축소된 토큰은 원본 액세스 토큰과 동일한 시각에 만료됩니다. |
issued_token_type |
|
token_type |
|
예를 들어 JSON 형식의 사용자 인증 정보 액세스 경계가 ./access-boundary.json
파일에 저장되는 경우, 다음 curl
명령어를 사용하여 액세스 토큰을 교환합니다. original-token
을 원본 액세스 토큰과 바꿉니다.
curl -H "Content-Type:application/x-www-form-urlencoded" \ -X POST \ https://sts.googleapis.com/v1/token \ -d "grant_type=urn:ietf:params:oauth:grant-type:token-exchange&subject_token_type=urn:ietf:params:oauth:token-type:access_token&requested_token_type=urn:ietf:params:oauth:token-type:access_token&subject_token=original-token" \ --data-urlencode "options=$(cat ./access-boundary.json)"
응답은 다음 예시와 비슷합니다.
{
"access_token": "ya29.dr.AbCDeFg-123456...",
"issued_token_type": "urn:ietf:params:oauth:token-type:access_token",
"token_type": "Bearer",
"expires_in": 3600
}
토큰 소비자가 권한이 축소된 토큰을 요청하면 토큰 브로커는 권한이 축소된 토큰과 만료될 때까지의 시간(초)으로 응답해야 합니다. 권한이 축소된 토큰을 새로 고치려면 소비자는 기존 토큰이 만료되기 전에 브로커에서 범위가 축소된 토큰을 요청할 수 있습니다.
다음 단계
- Cloud Storage의 액세스 제어 알아보기
- 단기 서비스 계정 사용자 인증 정보 만들기
- 서버 간 OAuth 2.0 흐름 또는 Service Account Credentials API를 사용하여 서비스 계정에 대한 OAuth 2.0 액세스 토큰 만들기
- 사용자의 OAuth 2.0 액세스 토큰 만들기
- 각 사전 정의된 역할의 권한 알아보기
- 커스텀 역할에 관해 알아보기