Questa pagina è stata tradotta dall'API Cloud Translation.

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 sono associati dati permanenti 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.

Visualizzare un elenco di privilegi di 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.

Per assegnare il ruolo a un utente, 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 scope_type.
Per assegnare il ruolo a un account di servizio, aggiungi un corpo JSON con il unique_id dell'account di servizio (come definito in Identity and Access Management (IAM)), il roleId (come descritto in Ottenere i ruoli esistenti) e il scope_type.
Per assegnare il ruolo a un gruppo, aggiungi un corpo JSON con il group_id del gruppo, che puoi ottenere da groups.get(), roleId (come descritto in Ottenere i ruoli esistenti) e scope_type.

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