Gestione ruoli

L'API Directory ti consente di utilizzare il controllo degli accessi basato sui ruoli (RBAC) per gestire l'accesso alle funzionalità nel tuo dominio Google Workspace. Puoi creare ruoli personalizzati con privilegi per limitare l'accesso amministrativo in modo più specifico rispetto ai ruoli predefiniti forniti con Google Workspace. Puoi assegnare ruoli a utenti o gruppi di sicurezza. Questa guida spiega come eseguire alcune attività di base relative ai ruoli.

Di seguito è riportato un elenco di termini comuni utilizzati dall'API Directory in merito al RBAC in Google Workspace:

Privilegio
L'autorizzazione necessaria per eseguire un'attività o un'operazione in un dominio Google Workspace. Rappresentata dalla risorsa Privilege. Non esistono dati permanenti associati a questa risorsa.
Role
Un insieme di privilegi che concede alle entità con quel ruolo la possibilità di eseguire determinate attività o operazioni. Rappresentata dalla risorsa Role.
Assegnazione del ruolo
Il record di un determinato ruolo assegnato all'utente o al gruppo. Rappresentata dalla risorsa RoleAssignment.
Gruppo di sicurezza
Un tipo di gruppo Cloud Identity utilizzato per controllare l'accesso alle risorse dell'organizzazione. I gruppi di sicurezza possono contenere sia singoli utenti che gruppi.

Limiti per i ruoli e le relative assegnazioni

Puoi creare solo un numero limitato di ruoli o assegnazioni dei ruoli personalizzati, quindi se stai per raggiungere il limite, consolidali o rimuovili per rimanere al di sotto del limite. I ruoli e le relative assegnazioni hanno i seguenti limiti:

  • Puoi creare fino a 750 ruoli personalizzati per l'intera organizzazione.
  • Puoi creare fino a 1000 assegnazioni di ruoli per unità organizzativa (UO), dove l'organizzazione principale è considerata un'unità. Ad esempio, puoi assegnare 600 ruoli nell'organizzazione principale e 700 ruoli in un'altra OU che hai definito, ad esempio un reparto di un'azienda. Per impostazione predefinita, tutti i ruoli amministrativi predefiniti di Google Workspace hanno ambito per l'intera organizzazione. Scopri di più sui limiti dei privilegi che possono essere assegnati a livello di OU.

I ruoli e l'assegnazione dei ruoli hanno i seguenti limiti per i gruppi:

  • Puoi assegnare qualsiasi ruolo ad eccezione del ruolo di super amministratore.
  • Puoi avere fino a 250 assegnazioni di ruoli ai gruppi in totale nell'OU complessiva e all'interno di ogni OU.
  • Il gruppo deve essere un gruppo di sicurezza all'interno della tua organizzazione.
  • Ti consigliamo di limitare l'appartenenza ai gruppi agli utenti della tua organizzazione. Puoi aggiungere utenti esterni all'organizzazione, ma potrebbero non ottenere i privilegi dei ruoli. Per maggiori dettagli, vedi Limitare l'appartenenza ai gruppi. ### Assegnazione dei ruoli ai gruppi

Se devi assegnare più di 1000 ruoli a un'OU, puoi aggiungere più membri a un gruppo di sicurezza e assegnare un ruolo al gruppo. Le assegnazioni dei ruoli di gruppo presentano alcune limitazioni aggiuntive. Per informazioni specifiche, consulta il Centro assistenza Amministrazione.

Mappatura dei ruoli ai privilegi nella Console di amministrazione Google

Per assegnare i ruoli agli utenti che accedono ai propri privilegi tramite la Console di amministrazione, potrebbe essere necessario concedere determinati privilegi aggiuntivi. Ad esempio, per concedere a un utente la possibilità di creare altri utenti tramite la Console di amministrazione, non è richiesto solo il privilegio USERS_CREATE, ma anche i privilegi USERS_UPDATE e ORGANIZATION_UNITS_RETRIEVE. La tabella seguente mappa le funzionalità della Console di amministrazione ai privilegi richiesti per la gestione di utenti e unità organizzative.

Funzionalità della Console di amministrazione Privilegi necessari
Unità organizzative - Lettura ORGANIZATION_UNITS_RETRIEVE
Unità organizzative - Crea ORGANIZATION_UNITS_RETRIEVE + ORGANIZATION_UNITS_CREATE
Unità organizzative - Aggiornamento ORGANIZATION_UNITS_RETRIEVE + ORGANIZATION_UNITS_UPDATE
Unità organizzative - Elimina ORGANIZATION_UNITS_RETRIEVE + ORGANIZATION_UNITS_DELETE
Unità organizzative ORGANIZATION_UNITS_ALL
Utenti - Lettura USERS_RETRIEVE + ORGANIZATION_UNITS_RETRIEVE
Utenti - Crea USERS_CREATE + USERS_UPDATE + ORGANIZATION_UNITS_RETRIEVE
Utenti - Aggiornamento USERS_UPDATE + ORGANIZATION_UNITS_RETRIEVE
Utenti - Sposta utenti USERS_MOVE + USERS_RETRIEVE + ORGANIZATION_UNITS_RETRIEVE
Utenti - Rinomina utenti USERS_ALIAS + USERS_RETRIEVE + ORGANIZATION_UNITS_RETRIEVE
Utenti - Reimposta password USERS_RESET_PASSWORD + USERS_RETRIEVE + ORGANIZATION_UNITS_RETRIEVE
Utenti - Forza modifica password USERS_FORCE_PASSWORD_CHANGE + USERS_RETRIEVE + ORGANIZATION_UNITS_RETRIEVE
Utenti - Aggiungi/Rimuovi alias USERS_ADD_NICKNAME + USERS_RETRIEVE + ORGANIZATION_UNITS_RETRIEVE
Utenti - Sospendi utenti USERS_SUSPEND + USERS_RETRIEVE + ORGANIZATION_UNITS_RETRIEVE
GRUPPI GROUPS_ALL
Sicurezza - Gestione della sicurezza degli utenti USER_SECURITY_ALL + USERS_RETRIEVE + ORGANIZATION_UNITS_RETRIEVE

Esempi di casi d'uso

Prima di iniziare

Completa i passaggi di autenticazione e autorizzazione per Google Workspace.

Visualizza un elenco dei privilegi del dominio

Per ottenere un elenco paginato dei privilegi supportati nel tuo dominio, utilizza il metodo privileges.list().

  • Se sei un amministratore che ottiene privilegi nel tuo dominio, utilizzamy_customer come ID cliente.

  • Se sei un rivenditore che ottiene i privilegi per uno dei tuoi clienti, utilizza l'ID cliente restituito dall'operazione Retrieve a user.

Richiesta

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

Risposta

Una risposta riuscita restituisce un codice di stato HTTP 200. Oltre al codice di stato, la risposta restituisce i privilegi supportati nel dominio:

{
  "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
        }
      ]
    },
    ...
  ]
}

Ottenere i ruoli esistenti

Per ottenere un elenco dei ruoli esistenti, utilizza la seguente richiesta GET e includi l'autorizzazione descritta nell'articolo relativo all'autorizzazione delle richieste.

  • Se sei un amministratore che riceve i ruoli nel tuo dominio, utilizzamy_customer come ID cliente.

  • Se sei un rivenditore che ottiene i ruoli per un cliente, utilizza l'ID cliente ottenuto utilizzando l'operazione Retrieve a user.

Richiesta

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

Risposta

Una risposta riuscita restituisce un codice di stato HTTP 200. Oltre al codice di stato, la risposta restituisce i ruoli esistenti nel dominio:

{
  "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
    },
    ...
  ]
}

Elenco di tutte le assegnazioni dei ruoli

Per ottenere un elenco paginato di tutte le assegnazioni di ruoli diretti, utilizza il metodo roleAssignments.list(). L'API potrebbe restituire risultati vuoti con un token pagina quando è impostato il parametro userKey. Devi continuare la paginazione finché non viene restituito alcun token pagina.

  • Se sei un amministratore che riceve le assegnazioni dei ruoli nel tuo dominio, utilizzamy_customer come ID cliente.

  • Se sei un rivenditore che riceve le assegnazioni dei ruoli per uno dei tuoi clienti, utilizza l'ID cliente restituito dall'operazione Retrieve a user.

Richiesta

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

Risposta

Una risposta riuscita restituisce un codice di stato HTTP 200. Oltre al codice di stato, la risposta restituisce tutti i ruoli assegnati nel dominio:

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

Elenca tutte le assegnazioni di ruoli indiretti

Per ottenere un elenco paginato di tutte le assegnazioni dei ruoli, incluse quelle indirettamente assegnate a un utente a causa dei gruppi di appartenenza, utilizza il metodo roleAssignments.list().

L'API potrebbe restituire risultati vuoti con un token di pagina. Devi continuare la paginazione finché non viene restituito alcun token pagina.

  • Se sei un amministratore che riceve le assegnazioni dei ruoli nel tuo dominio, utilizzamy_customer come ID cliente.

  • Se sei un rivenditore che riceve le assegnazioni dei ruoli per uno dei tuoi clienti, utilizza l'ID cliente restituito dall'operazione Retrieve a user.

  • Sostituisci USER_KEY con un valore che identifichi l'utente nella richiesta API. Per ulteriori informazioni, consulta users.get.

Richiesta

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

Risposta

Una risposta riuscita restituisce un codice di stato HTTP 200. Oltre al codice di stato, la risposta restituisce tutti i ruoli assegnati nel dominio e se assigneeType è user o group:

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

Creare un ruolo

Per creare un nuovo ruolo, utilizza la seguente richiesta POST e includi l'autorizzazione descritta nell'articolo relativo all'autorizzazione delle richieste. Aggiungi un privilegeName e un serviceId per ogni privilegio che deve essere concesso con questo ruolo. Per le proprietà di richiesta e risposta, consulta il riferimento API.

Richiesta

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

Risposta

Una risposta riuscita restituisce un codice di stato HTTP 200. Oltre al codice di stato, la risposta restituisce le proprietà del nuovo ruolo:

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

Creare un'assegnazione di ruolo

Per assegnare un ruolo, utilizza il seguente metodo POST e includi l'autorizzazione descritta in Autorizzare le richieste.

Richiesta

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

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

Risposta

Una risposta riuscita restituisce un codice di stato HTTP 200. Oltre al codice di stato, la risposta restituisce le proprietà per la nuova assegnazione del ruolo:

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

Creare un'assegnazione del ruolo con condizioni

Puoi concedere i ruoli per eseguire azioni che soddisfano condizioni specifiche. Al momento sono supportate solo due condizioni:

  • Applicabile solo ai gruppi di sicurezza
  • Non applicabile ai gruppi di sicurezza

Quando condition è impostato, avrà effetto solo quando la risorsa a cui si accede soddisfa la condizione. Se condition è vuoto, il ruolo (roleId) viene applicato all'attore (assignedTo) nell'ambito (scopeType) in modo incondizionato.

Per assegnare un ruolo a un utente, utilizza il seguente metodo POST e includi l'autorizzazione descritta nell'articolo relativo all'autorizzazione delle richieste.

Aggiungi un corpo JSON con il user_id dell'utente, che puoi ottenere da users.get(), il roleId come descritto in Ottenere i ruoli esistenti e il condition. Le due stringhe di condizione devono essere utilizzate esattamente come mostrato di seguito e funzionano solo con i ruoli amministrativi predefiniti di Editor di gruppi e Lettore di gruppi. Queste condizioni rispettano la sintassi delle condizioni Cloud IAM.

Richiesta

Applicabile solo ai gruppi di sicurezza
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'"
}
Non applicabile ai gruppi di sicurezza
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'"
}

Risposta

Una risposta riuscita restituisce un codice di stato HTTP 200. Oltre al codice di stato, la risposta restituisce le proprietà per la nuova assegnazione del ruolo:

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