역할 관리

Directory API를 사용하면 역할 기반 액세스 제어 (RBAC)를 사용하여 Google Workspace 도메인의 기능에 대한 액세스를 관리할 수 있습니다. Google Workspace에 제공되는 기본 제공 역할보다 더 구체적으로 관리자 액세스를 제한하는 권한으로 맞춤 역할을 만들 수 있습니다. 사용자 또는 보안 그룹에 역할을 할당할 수 있습니다. 이 가이드에서는 기본적인 역할 관련 작업을 수행하는 방법을 설명합니다.

다음은 Google Workspace 내 RBAC와 관련하여 Directory API에서 사용되는 일반적인 용어 목록입니다.

권한

Google Workspace 도메인에서 작업 또는 작업을 수행하는 데 필요한 권한입니다. Privilege 리소스로 표시됩니다. 이 리소스에는 영구 데이터가 연결되어 있지 않습니다.

직책

해당 역할이 있는 항목에 특정 작업 또는 작업을 수행할 수 있는 기능을 부여하는 권한 모음입니다. Role 리소스로 표시됩니다.

역할 할당

사용자 또는 그룹에 부여된 특정 역할의 기록입니다. RoleAssignment 리소스로 표시됩니다.

보안 그룹

조직 리소스에 대한 액세스를 제어하는 데 사용되는 Cloud ID 그룹의 유형입니다. 보안 그룹에는 개별 사용자와 그룹이 모두 포함될 수 있습니다.

역할 및 역할 할당 한도

커스텀 역할 또는 역할 할당은 제한된 수만 만들 수 있으므로 한도에 가까워지면 한도 미만으로 유지하기 위해 통합하거나 삭제하세요. 역할 및 역할 할당에는 다음과 같은 제한이 있습니다.

• 조직 전체에 최대 750개의 맞춤 역할을 만들 수 있습니다.
• 조직 단위 (OU)당 최대 1,000개의 역할 할당을 만들 수 있습니다. 여기서 루트 조직은 단위로 간주됩니다. 예를 들어 루트 조직에 600개의 역할을 할당하고 회사 부서와 같이 정의한 다른 OU 내에 700개의 역할을 할당할 수 있습니다. 모든 Google Workspace 기본 제공 관리자 역할은 기본적으로 조직 전체 범위로 설정됩니다. OU 수준에서 할당할 수 있는 권한 제한에 대해 자세히 알아보세요.

그룹의 역할 및 역할 할당에는 다음과 같은 제한이 있습니다.

• 최고 관리자를 제외한 모든 역할을 할당할 수 있습니다.
• 전체 OU 및 각 OU 내에서 그룹에 최대 250개의 역할을 할당할 수 있습니다.
• 그룹은 조직의 보안 그룹이어야 합니다.
• 그룹 멤버십은 조직 내 사용자로 제한하여 부여하는 것이 좋습니다. 조직 외부의 사용자를 추가할 수 있지만 해당 사용자에게 역할 권한이 부여되지 않을 수 있습니다. 자세한 내용은 그룹 멤버십 제한하기를 참고하세요. ### 그룹에 역할 할당

OU에 1, 000개가 넘는 역할을 할당해야 하는 경우 보안 그룹에 여러 회원을 추가하고 해당 그룹에 역할을 할당할 수 있습니다. 그룹 역할 할당에는 몇 가지 추가 제한사항이 있습니다. 자세한 내용은 관리자 고객센터를 참고하세요.

참고: 보안 그룹을 만들려면 Cloud Identity API를 사용해야 합니다. Directory API를 사용할 수 없습니다. 자세한 내용은 보안 그룹 문서를 참고하세요.

Google 관리 콘솔 역할-권한 매핑

관리 콘솔을 통해 권한에 액세스하는 사용자의 역할을 할당하려면 특정 추가 권한을 부여해야 할 수 있습니다. 예를 들어 사용자에게 관리 콘솔을 통해 다른 사용자를 만들 수 있는 기능을 부여하려면 USERS_CREATE 권한뿐만 아니라 USERS_UPDATE 및 ORGANIZATION_UNITS_RETRIEVE 권한도 필요합니다. 다음 표에서는 관리 콘솔 기능을 사용자 및 조직 단위 관리에 필요한 권한 부여에 매핑합니다.

관리 콘솔 기능	필요한 권한
조직 단위 - 읽기	ORGANIZATION_UNITS_RETRIEVE
조직 단위 - 만들기	ORGANIZATION_UNITS_RETRIEVE + ORGANIZATION_UNITS_CREATE
조직 단위 - 업데이트	ORGANIZATION_UNITS_RETRIEVE + ORGANIZATION_UNITS_UPDATE
조직 단위 - 삭제	ORGANIZATION_UNITS_RETRIEVE + ORGANIZATION_UNITS_DELETE
조직 단위	ORGANIZATION_UNITS_ALL
사용자 - 읽기	USERS_RETRIEVE + ORGANIZATION_UNITS_RETRIEVE
사용자 - 만들기	USERS_CREATE + USERS_UPDATE + ORGANIZATION_UNITS_RETRIEVE
사용자 - 업데이트	USERS_UPDATE + ORGANIZATION_UNITS_RETRIEVE
사용자 - 사용자 이동	USERS_MOVE + USERS_RETRIEVE + ORGANIZATION_UNITS_RETRIEVE
사용자 - 사용자 이름 바꾸기	USERS_ALIAS + USERS_RETRIEVE + ORGANIZATION_UNITS_RETRIEVE
사용자 - 비밀번호 재설정	USERS_RESET_PASSWORD + USERS_RETRIEVE + ORGANIZATION_UNITS_RETRIEVE
사용자 - 비밀번호 강제 변경	USERS_FORCE_PASSWORD_CHANGE + USERS_RETRIEVE + ORGANIZATION_UNITS_RETRIEVE
사용자 - 별칭 추가/삭제	USERS_ADD_NICKNAME + USERS_RETRIEVE + ORGANIZATION_UNITS_RETRIEVE
사용자 - 사용자 정지	USERS_SUSPEND + USERS_RETRIEVE + ORGANIZATION_UNITS_RETRIEVE
그룹	GROUPS_ALL
보안 - 사용자 보안 관리	USER_SECURITY_ALL + USERS_RETRIEVE + ORGANIZATION_UNITS_RETRIEVE

사용 사례

시작하기 전에

이 가이드의 예시를 실행하기 전에 인증 및 승인을 설정하세요.

1. OAuth 동의 화면 구성

2. 액세스 사용자 인증 정보 만들기

도메인 권한 목록 가져오기

도메인에서 지원되는 권한의 페이지로 구분된 목록을 가져오려면 privileges.list() 메서드를 사용하세요.

• 자체 도메인에서 권한을 부여받는 관리자인 경우 my_customer을 고객 ID로 사용합니다.

• 고객 중 한 명의 권한을 가져오는 리셀러인 경우 사용자 검색 작업에서 반환된 고객 ID를 사용하세요.

요청

GET https://admin.googleapis.com/admin/directory/v1/customer/customer_id/roles/ALL/privileges

응답

성공적인 응답은 HTTP 200 상태 코드를 반환합니다. 응답에는 상태 코드와 함께 도메인에서 지원되는 권한이 반환됩니다.

{
  "kind": "admin\#directory\#privileges",
  "etag": ...,
  "items": [
    {
      "kind": "admin\#directory\#privilege",
      "etag": ...,
      "serviceId": "02afmg282jiquyg",
      "privilegeName": "APP_ADMIN",
      "isOuScopable": false
    },
    {
      "kind": "admin\#directory\#privilege",
      "etag": ...,
      "serviceId": "04f1mdlm0ki64aw",
      "privilegeName": "MANAGE_USER_SETTINGS",
      "isOuScopable": true,
      "childPrivileges": [
        {
          "kind": "admin\#directory\#privilege",
          "etag": ...,
          "serviceId": "04f1mdlm0ki64aw",
          "privilegeName": "MANAGE_APPLICATION_SETTINGS",
          "isOuScopable": true
        }
      ]
    },
    ...
  ]
}

기존 역할 가져오기

기존 역할 목록을 가져오려면 다음 GET 요청을 사용하고 요청 승인에 설명된 승인을 포함합니다.

• 자체 도메인에서 역할을 가져오는 관리자인 경우 my_customer를 고객 ID로 사용합니다.

• 고객의 역할을 가져오는 리셀러인 경우 사용자 검색 작업을 사용하여 가져온 고객 ID를 사용하세요.

요청

GET https://admin.googleapis.com/admin/directory/v1/customer/customer_id/roles

응답

성공적인 응답은 HTTP 200 상태 코드를 반환합니다. 응답에는 상태 코드와 함께 도메인에 있는 역할이 반환됩니다.

{
  "kind": "admin\#directory\#roles",
  "etag": "\"sxH3n22L0-77khHtQ7tiK6I21Yo/DywA6_jaJCYw-f0lFs2-g17UWe8\"",
  "items": [
    {
      "kind": "admin\#directory\#role",
      "etag": ... ,
      "roleId": "3894208461012993",
      "roleName": "_SEED_ADMIN_ROLE",
      "roleDescription": "Google Workspace Administrator Seed Role",
      "rolePrivileges": [
        {
          "privilegeName": "SUPER_ADMIN",
          "serviceId": "01ci93xb3tmzyin"
        },
        {
          "privilegeName": "ROOT_APP_ADMIN",
          "serviceId": "00haapch16h1ysv"
        },
        {
          "privilegeName": "ADMIN_APIS_ALL",
          "serviceId": "00haapch16h1ysv"
        },
        ...
      ],
      "isSystemRole": true,
      "isSuperAdminRole": true
    },
    {
      "kind": "admin\#directory\#role",
      "etag": "\"sxH3n22L0-77khHtQ7tiK6I21Yo/bTXiZXfuK1NGr_f4paosCWXuHmw\"",
      "roleId": "3894208461012994",
      "roleName": "_GROUPS_ADMIN_ROLE",
      "roleDescription": "Groups Administrator",
      "rolePrivileges": [
        {
          "privilegeName": "CHANGE_USER_GROUP_MEMBERSHIP",
          "serviceId": "01ci93xb3tmzyin"
        },
        {
          "privilegeName": "USERS_RETRIEVE",
          "serviceId": "00haapch16h1ysv"
        },
        {
          "privilegeName": "GROUPS_ALL",
          "serviceId": "00haapch16h1ysv"
        },
        {
          "privilegeName": "ADMIN_DASHBOARD",
          "serviceId": "01ci93xb3tmzyin"
        },
        {
          "privilegeName": "ORGANIZATION_UNITS_RETRIEVE",
          "serviceId": "00haapch16h1ysv"
        }
      ],
      "isSystemRole": true
    },
    ...
  ]
}

모든 역할 할당 나열

모든 직접 역할 할당의 페이지로 구분된 목록을 가져오려면 roleAssignments.list() 메서드를 사용합니다. userKey 파라미터가 설정된 경우 API가 페이지 토큰과 함께 빈 결과를 반환할 수 있습니다. 페이지 토큰이 반환되지 않을 때까지 페이지로 나누기를 계속해야 합니다.

• 자체 도메인에서 역할 할당을 받는 관리자인 경우 my_customer을 고객 ID로 사용합니다.

• 고객 중 한 명의 역할 할당을 받는 리셀러인 경우 사용자 검색 작업에서 반환된 고객 ID를 사용하세요.

요청

GET https://admin.googleapis.com/admin/directory/v1/customer/customer_id/roleassignments

응답

성공적인 응답은 HTTP 200 상태 코드를 반환합니다. 응답에는 상태 코드와 함께 도메인에 할당된 모든 역할이 반환됩니다.

{
  "kind": "admin\#directory\#roleAssignment",
  "etag": "\"sxH3n22L0-77khHtQ7tiK6I21Yo/VdrrUEz7GyXqlr9I9JL0wGZn8yE\"",
  "roleAssignmentId:"3894208461013211",
  "assignedTo:"100662996240850794412",
  "assigneeType:"user",
  "scopeType:"CUSTOMER",
}

모든 간접 역할 할당 나열

사용자가 속한 그룹으로 인해 사용자에게 간접적으로 할당된 역할을 포함하여 모든 역할 할당의 페이지로 구분된 목록을 가져오려면 roleAssignments.list() 메서드를 사용합니다.

API가 페이지 토큰과 함께 빈 결과를 반환할 수 있습니다. 페이지 토큰이 반환되지 않을 때까지 페이지로 나누기를 계속해야 합니다.

• 자체 도메인에서 역할 할당을 받는 관리자인 경우 my_customer을 고객 ID로 사용합니다.

• 고객 중 한 명의 역할 할당을 받는 리셀러인 경우 사용자 검색 작업에서 반환된 고객 ID를 사용하세요.

• USER_KEY을 API 요청에서 사용자를 식별하는 값으로 바꿉니다. 자세한 내용은 users.get를 참고하세요.

요청

GET https://admin.googleapis.com/admin/directory/v1/customer/customer_id/roleassignments?userKey=USER_KEY&includeIndirectRoleAssignments=true

응답

성공적인 응답은 HTTP 200 상태 코드를 반환합니다. 상태 코드와 함께 응답은 도메인에 할당된 모든 역할과 assigneeType가 user인지 group인지 여부를 반환합니다.

{
  "kind": "admin\#directory\#roleAssignment",
  "etag": "\"sxH3n22L0-77khHtQ7tiK6I21Yo/VdrrUEz7GyXqlr9I9JL0wGZn8yE\"",
  "roleAssignmentId:"3894208461013211",
  "assignedTo:"100662996240850794412",
  "assigneeType:"group",
  "scopeType:"CUSTOMER",
}

역할 만들기

새 역할을 만들려면 다음 POST 요청을 사용하고 요청 승인에 설명된 승인을 포함합니다. 이 역할에 부여해야 하는 각 권한에 privilegeName 및 serviceId을 추가합니다. 요청 및 응답 속성은 API 참조를 참고하세요.

요청

POST https://admin.googleapis.com/admin/directory/v1/customer/customer_id/roles

{
  "roleName": "My New Role",
  "rolePrivileges": [
    {
      "privilegeName": "USERS_ALL",
      "serviceId": "00haapch16h1ysv"
    },
    {
      "privilegeName": "GROUPS_ALL",
      "serviceId": "00haapch16h1ysv"
    }
  ]
}

응답

성공적인 응답은 HTTP 200 상태 코드를 반환합니다. 응답에는 상태 코드와 함께 새 역할의 속성이 반환됩니다.

{
  "kind": "admin\#directory\#role",
  "etag": "\"sxH3n22L0-77khHtQ7tiK6I21Yo/uX9tXw0qyijC9nUKgCs08wo8aEM\"",
  "roleId": "3894208461013031",
  "roleName": "My New Role",
  "rolePrivileges": [
    {
      "privilegeName": "GROUPS_ALL",
      "serviceId": "00haapch16h1ysv"
    },
    {
      "privilegeName": "USERS_ALL",
      "serviceId": "00haapch16h1ysv"
    }
  ]
}

역할 할당 만들기

역할을 할당하려면 다음 POST 메서드를 사용하고 요청 승인에 설명된 승인을 포함합니다.

• 사용자에게 역할을 할당하려면 users.get(), roleId (기존 역할 가져오기에 설명됨), scope_type에서 가져올 수 있는 사용자의 user_id이 포함된 JSON 본문을 추가합니다.

• 서비스 계정에 역할을 할당하려면 서비스 계정의 unique_id (Identity and Access Management (IAM)에 정의됨), roleId (기존 역할 가져오기에 설명됨), scope_type이 포함된 JSON 본문을 추가합니다.

• 그룹에 역할을 할당하려면 groups.get(), roleId (기존 역할 가져오기에 설명됨), scope_type에서 가져올 수 있는 그룹의 group_id이 포함된 JSON 본문을 추가합니다.

요청

POST https://admin.googleapis.com/admin/directory/v1/customer/customer_id/roleassignments

{
  "roleId": "3894208461012995",
  "assignedTo": "100662996240850794412",
  "scopeType": "CUSTOMER"
}

응답

성공적인 응답은 HTTP 200 상태 코드를 반환합니다. 응답에는 상태 코드와 함께 새 역할 할당의 속성이 반환됩니다.

{
  "kind": "admin\#directory\#roleAssignment",
  "etag": "\"sxH3n22L0-77khHtQ7tiK6I21Yo/VdrrUEz7GyXqlr9I9JL0wGZn8yE\"",
  "roleAssignmentId": "3894208461013211",
  "roleId": "3894208461012995",
  "assignedTo": "100662996240850794412",
  "scopeType": "CUSTOMER"
}

조건이 있는 역할 할당 만들기

참고: 이 기능은 API의 v1.1beta1 버전에서만 사용할 수 있으며 Enterprise Standard, Enterprise Plus, Google Workspace for Education Plus, Cloud ID Premium 고객에게만 제공됩니다. 이 기능을 사용하기 위해 추가 설정이 필요하지 않습니다. 조건이 있는 역할 할당은 아직 관리 콘솔에서 적용되지 않습니다.

특정 조건을 충족하는 작업을 수행할 수 있는 역할을 부여할 수 있습니다. 현재는 다음 두 가지 조건만 지원됩니다.

• 보안 그룹에만 적용 가능
• 보안 그룹에는 적용되지 않음

condition이 설정된 경우 액세스하는 리소스가 조건을 충족할 때만 적용됩니다. condition이 비어 있으면 역할 (roleId)이 범위 (scopeType)의 배우 (assignedTo)에게 무조건 적용됩니다.

사용자에게 역할을 할당하려면 다음 POST 메서드를 사용하고 승인 요청에 설명된 승인을 포함합니다.

users.get()에서 가져올 수 있는 사용자의 user_id, 기존 역할 가져오기에 설명된 대로 roleId, condition이 포함된 JSON 본문을 추가합니다. 두 조건 문자열은 아래와 같이 그대로 사용해야 하며 그룹 편집자 및 그룹 리더 사전 빌드된 관리자 역할에서만 작동합니다. 이러한 조건은 Cloud IAM 조건 구문을 따릅니다.

요청

보안 그룹에만 적용 가능

POST https://admin.googleapis.com/admin/directory/v1.1beta1/customer/customer_id/roleassignments

{
  "roleId": "3894208461012995",
  "assignedTo": "100662996240850794412",
  "scopeType": "CUSTOMER",
  "condition": "api.getAttribute('cloudidentity.googleapis.com/groups.labels',
    []).hasAny(['groups.security']) && resource.type ==
    'cloudidentity.googleapis.com/Group'"
}

보안 그룹에는 적용되지 않음

POST https://admin.googleapis.com/admin/directory/v1.1beta1/customer/customer_id/roleassignments

{
  "roleId": "3894208461012995",
  "assignedTo": "100662996240850794412",
  "scopeType": "CUSTOMER",
  "condition": "!api.getAttribute('cloudidentity.googleapis.com/groups.labels',
    []).hasAny(['groups.security']) && resource.type ==
    'cloudidentity.googleapis.com/Group'"
}

응답

성공적인 응답은 HTTP 200 상태 코드를 반환합니다. 응답에는 상태 코드와 함께 새 역할 할당의 속성이 반환됩니다.

{
  "kind": "admin\#directory\#roleAssignment",
  "etag": "\"sxH3n22L0-77khHtQ7tiK6I21Yo/VdrrUEz7GyXqlr9I9JL0wGZn8yE\"",
  "roleAssignmentId": "3894208461013211",
  "roleId": "3894208461012995",
  "assignedTo": "100662996240850794412",
  "scopeType": "CUSTOMER",
  "condition": "!api.getAttribute('cloudidentity.googleapis.com/groups.labels',
    []).hasAny(['groups.security']) && resource.type ==
    'cloudidentity.googleapis.com/Group'"
}