역할 관리

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개가 넘는 역할을 할당해야 하는 경우 보안 그룹에 여러 명의 회원을 추가하고 그룹에 역할을 할당할 수 있습니다. 그룹 역할 할당에는 몇 가지 추가 제한사항이 있습니다. 자세한 내용은 관리자 고객센터를 참고하세요.

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가 페이지 토큰과 함께 빈 결과를 반환할 수 있습니다. 페이지 토큰이 반환되지 않을 때까지 페이지로 나누기를 계속해야 합니다.

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

  • 고객 중 한 명의 역할 할당을 받는 리셀러인 경우 사용자 검색 작업에서 반환된 고객 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가 페이지 토큰과 함께 빈 결과를 반환할 수 있습니다. 페이지 토큰이 반환되지 않을 때까지 페이지네이션을 계속해야 합니다.

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

  • 고객 중 한 명의 역할 할당을 받는 리셀러인 경우 사용자 검색 작업에서 반환된 고객 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()에서 가져올 수 있는 사용자의 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'"
}