역할 관리

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

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

권한
Google Workspace 도메인에서 태스크 또는 작업을 수행하는 데 필요한 권한입니다. Privilege 리소스로 표현됩니다. 이 리소스에 연결된 영구 데이터는 없습니다.
역할
역할이 있는 항목에 특정 작업 또는 작업을 수행할 수 있는 권한을 부여하는 권한 모음입니다. Role 리소스로 표현됩니다.
역할 할당
사용자 또는 그룹에 부여된 특정 역할의 레코드입니다. RoleAssignment 리소스로 표현됩니다.
보안 그룹
조직 리소스에 대한 액세스를 제어하는 데 사용되는 Cloud ID 그룹 유형입니다. 보안 그룹에는 개별 사용자와 그룹이 모두 포함될 수 있습니다.

역할 및 역할 할당 한도

만들 수 있는 커스텀 역할 또는 역할 할당의 한도는 제한되어 있으므로, 한도에 거의 도달한 경우 한도를 초과하지 않도록 통합하거나 삭제하세요. 역할 및 역할 할당에는 다음과 같은 제한이 있습니다.

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

역할 및 역할 할당에는 다음과 같은 그룹 한도가 적용됩니다.

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

그룹에 역할 할당

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

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 GROUPS_ALL
보안 - 사용자 보안 관리 USER_SECURITY_ALL + USERS_RETRIEVE + ORGANIZATION_UNITS_RETRIEVE

사용 사례

시작하기 전에

Google Workspace의 인증 및 승인 단계를 완료합니다.

도메인 권한 목록 가져오기

도메인에서 지원되는 권한의 페이지로 나눈 목록을 가져오려면 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 메서드를 사용하고 요청 승인에 설명된 승인을 포함합니다.

요청

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"
}

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

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

  • 보안 그룹에만 적용됨
  • 보안 그룹에 적용되지 않음

condition를 설정하면 액세스하는 리소스가 조건을 충족하는 경우에만 적용됩니다. condition가 비어 있으면 역할 (roleId)이 범위 (scopeType)에서 작업 수행자 (assignedTo)에 무조건 적용됩니다.

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

users.get(), 기존 역할 가져오기에 설명된 roleId, condition에서 가져올 수 있는 사용자의 user_id를 사용하여 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'"
}