Questa pagina è stata tradotta dall'API Cloud Translation.

Gestione ruoli

L'API Directory 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 dei termini comuni utilizzati dall'API Directory in merito a RBAC in Google Workspace:

Privilegio: L'autorizzazione necessaria per eseguire un'attività o un'operazione in un dominio di Google Workspace. Rappresentato dalla risorsa Privilege. Non esistono dati permanenti associati a questa risorsa.
Ruolo: Una raccolta di privilegi che conferisce alle entità con quel ruolo la capacità di eseguire determinate attività o operazioni. Rappresentato dalla risorsa Role.
Assegnazione del ruolo: Il record di un particolare ruolo assegnato all'utente o al gruppo. Rappresentato 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 alle assegnazioni di ruoli e ruoli

Puoi creare solo un numero limitato di assegnazioni o ruoli personalizzati, quindi se ti stai avvicinando al limite, consolidali o rimuovili per rimanere entro il limite. I ruoli e le assegnazioni dei ruoli presentano i seguenti limiti:

Puoi creare fino a 750 ruoli personalizzati per l'intera organizzazione.
Puoi creare fino a 500 assegnazioni di ruoli per unità organizzativa (UO), in cui l'organizzazione principale è considerata un'unità. Ad esempio, puoi assegnare 350 ruoli nell'organizzazione principale e 400 ruoli all'interno di un'altra UO da te definita, ad esempio un reparto di un'azienda. L'ambito predefinito di tutti i ruoli amministrativi predefiniti di Google Workspace è quella a livello di organizzazione. Scopri di più sui limiti dei privilegi che possono essere assegnati a livello di UO.

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

Puoi assegnare qualsiasi ruolo tranne Super amministratore.
Puoi avere fino a 250 assegnazioni di ruoli ai gruppi in totale nella UO complessiva e all'interno di ogni UO.
Il gruppo deve essere un gruppo di sicurezza della tua organizzazione.
Ti consigliamo di limitare l'iscrizione ai gruppi ai soli utenti della tua organizzazione. Puoi aggiungere utenti esterni all'organizzazione, ma questi potrebbero non ottenere i privilegi del ruolo. Per maggiori dettagli, vedi Limitare l'appartenenza ai gruppi.

Assegnazione dei ruoli ai gruppi

Se devi assegnare più di 500 ruoli in una UO, 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 per amministratori.

Mappatura ruolo-privilegi nella Console di amministrazione Google

Per assegnare ruoli agli utenti che accedono ai loro privilegi tramite la Console di amministrazione, potrebbe essere necessario concedere alcuni privilegi aggiuntivi. Ad esempio, per concedere a un utente la possibilità di creare altri utenti tramite la Console di amministrazione, non è necessario solo il privilegio USERS_CREATE, ma anche i privilegi USERS_UPDATE e ORGANIZATION_UNITS_RETRIEVE. La seguente tabella mappa le funzionalità della Console di amministrazione con le concessioni dei privilegi richieste 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 - Eliminazione	`ORGANIZATION_UNITS_RETRIEVE` + `ORGANIZATION_UNITS_DELETE`
Unità organizzative	`ORGANIZATION_UNITS_ALL`
Utenti - Letto	`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 della password	`USERS_FORCE_PASSWORD_CHANGE` + `USERS_RETRIEVE` + `ORGANIZATION_UNITS_RETRIEVE`
Utenti - Aggiungi/rimuovi alias	`USERS_ADD_NICKNAME` + `USERS_RETRIEVE` + `ORGANIZATION_UNITS_RETRIEVE`
Utenti - Sospensione di 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.

Ottieni un elenco dei privilegi di dominio

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

Se sei un amministratore che ottiene privilegi nel tuo dominio, utilizza my_customer come ID cliente.
Se sei un rivenditore che ottiene i privilegi per uno dei tuoi clienti, utilizza l'ID cliente restituito dall'operazione Recupera un utente.

Richiesta

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

Risposta

Una risposta corretta restituisce un codice di stato HTTP 200. Insieme 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
        }
      ]
    },
    ...
  ]
}

Recupero ruoli esistenti

Per ottenere un elenco dei ruoli esistenti, utilizza la seguente richiesta GET e includi l'autorizzazione descritta in Autorizzare le richieste.

Se sei un amministratore con ruoli nel tuo dominio, utilizza my_customer come ID cliente.
Se sei un rivenditore e vuoi ricevere ruoli per un cliente, utilizza l'ID cliente che hai ottenuto utilizzando l'operazione Recupera un utente.

Richiesta

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

Risposta

Una risposta corretta restituisce un codice di stato HTTP 200. Insieme 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 impaginato di tutte le assegnazioni di ruoli diretti, utilizza il metodo roleAssignments.list(). L'API potrebbe restituire risultati vuoti con un token di pagina quando è impostato il parametro userKey. Devi continuare l'impaginazione finché non viene restituito alcun token di pagina.

Se sei un amministratore che riceve assegnazioni dei ruoli nel tuo dominio, utilizza my_customer come ID cliente.
Se sei un rivenditore e ricevi le assegnazioni dei ruoli per uno dei tuoi clienti, utilizza l'ID cliente restituito dall'operazione Recupera un utente.

Richiesta

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

Risposta

Una risposta corretta restituisce un codice di stato HTTP 200. Insieme 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",
}

Elenco di tutte le assegnazioni di ruolo indirette

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

L'API potrebbe restituire risultati vuoti con un token di pagina. Continua la paginazione fino a quando non viene restituito alcun token di pagina.

Se sei un amministratore che riceve assegnazioni dei ruoli nel tuo dominio, utilizza my_customer come ID cliente.
Se sei un rivenditore e ricevi le assegnazioni dei ruoli per uno dei tuoi clienti, utilizza l'ID cliente restituito dall'operazione Recupera un utente.
Sostituisci USER_KEY con un valore che identifichi l'utente nella richiesta API. Per maggiori 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 corretta restituisce un codice di stato HTTP 200. Insieme 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 in Autorizzare le richieste. Aggiungi privilegeName e 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 corretta restituisce un codice di stato HTTP 200. Insieme al codice di stato, la risposta restituisce le proprietà per il 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 Autorizza richieste.

Per assegnare il ruolo a un utente, aggiungi un corpo JSON con il user_id dell'utente, che puoi recuperare da users.get(), roleId (come descritto in Recupero dei ruoli esistenti) e scope_type.
Per assegnare il ruolo a un account di servizio, aggiungi un corpo JSON con unique_id dell'account di servizio (come definito in Identity and Access Management (IAM)), roleId (come descritto in Recupero dei ruoli esistenti) e 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 Recupero dei 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 corretta restituisce un codice di stato HTTP 200. Insieme 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 di ruolo con condizioni

Puoi concedere ruoli per eseguire azioni che soddisfano condizioni specifiche. Attualmente, sono supportate solo due condizioni:

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

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

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

Aggiungi un corpo JSON con il valore user_id dell'utente, che puoi ottenere da users.get(), roleId come descritto in Recupera ruoli esistenti e condition. Le due stringhe di condizione devono essere utilizzate testualmente come mostrato di seguito e funzionano solo con i ruoli amministrativi predefiniti dell'Editor di gruppi e del Lettore di gruppi. Queste condizioni seguono 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 corretta restituisce un codice di stato HTTP 200. Insieme 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'"
}