Questa pagina è stata tradotta dall'API Cloud Translation.

Gestisci 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 correlate ai ruoli.

Di seguito è riportato un elenco di termini comuni utilizzati dall'API Directory in relazione al controllo dell'accesso basato sui ruoli (RBAC) in Google Workspace:

Privilegio: L'autorizzazione necessaria per eseguire un'attività o un'operazione in un dominio Google Workspace. Rappresentato dalla risorsa Privilege. Non sono presenti dati persistenti associati a questa risorsa.
Role: Un insieme di privilegi che concede alle entità con quel ruolo la possibilità di eseguire determinate attività o operazioni. Rappresentato dalla risorsa Role.
Assegnazione dei ruoli: Il record di un ruolo specifico 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 per ruoli e assegnazioni di ruoli

Puoi creare solo un numero limitato di ruoli personalizzati o assegnazioni di ruoli, quindi se ti stai avvicinando al limite, consolidali o rimuovili per rimanere al di sotto del 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 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 all'interno di un'altra UO che hai definito, ad esempio un reparto di un'azienda. Tutti i ruoli amministrativi predefiniti di Google Workspace hanno come ambito predefinito l'intera organizzazione. Scopri di più sui limiti dei privilegi che possono essere assegnati a livello di unità organizzativa.

Per i gruppi, i ruoli e l'assegnazione dei ruoli presentano i seguenti limiti:

Puoi assegnare qualsiasi ruolo ad eccezione del ruolo di super amministratore.
Puoi avere fino a 250 assegnazioni di ruoli ai gruppi in totale a livello di UO e all'interno di ciascuna UO.
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 alla tua organizzazione, ma potrebbero non ottenere i privilegi dei ruoli. Per maggiori dettagli, vedi Limitare l'appartenenza ai gruppi. ### Assegnazione di ruoli ai gruppi

Se devi assegnare più di 1000 ruoli in un'unità organizzativa, puoi aggiungere più membri a un gruppo di sicurezza e assegnare un ruolo al gruppo. L'assegnazione dei ruoli di gruppo presenta alcune limitazioni aggiuntive. Per informazioni specifiche, consulta il Centro assistenza Amministratore.

Mappatura dei ruoli e dei privilegi della Console di amministrazione Google

Per assegnare ruoli agli utenti che accedono ai propri 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 tabella seguente mappa la funzionalità della Console di amministrazione con le concessioni di privilegi richieste per la gestione degli utenti e delle 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

Prima di eseguire gli esempi in questa guida, configura l'autenticazione e l'autorizzazione.

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 proprio dominio, utilizza my_customer come ID cliente.
Se sei un rivenditore che ottiene privilegi per uno dei suoi 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 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
        }
      ]
    },
    ...
  ]
}

Recuperare i 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 che ottiene ruoli nel proprio dominio, utilizza my_customer come ID cliente.
Se sei un rivenditore che ottiene 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 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 di ruoli

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

Se sei un amministratore che riceve assegnazioni di ruoli nel proprio dominio, utilizza my_customer come ID cliente.
Se sei un rivenditore che riceve assegnazioni di 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 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",
}

Elenco di tutte le assegnazioni di ruolo indirette

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

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

Se sei un amministratore che riceve assegnazioni di ruoli nel proprio dominio, utilizza my_customer come ID cliente.
Se sei un rivenditore che riceve assegnazioni di 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 ulteriori informazioni, vedi 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 indica se assigneeType è user o group:

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

Crea 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 da concedere con questo ruolo. Per le proprietà della richiesta e della 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 l'user_id dell'utente, che puoi ottenere da users.get(), l'roleId (come descritto in Recuperare i ruoli esistenti) e l'scope_type.
Per assegnare il ruolo a un service account, aggiungi un corpo JSON con l'unique_id del service account (come definito in Identity and Access Management (IAM)), l'roleId (come descritto in Recuperare i ruoli esistenti) e l'scope_type.
Per assegnare il ruolo a un gruppo, aggiungi un corpo JSON con l'group_id del gruppo, che puoi ottenere da groups.get(), l'roleId (come descritto in Ottenere i ruoli esistenti) e l'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à della nuova assegnazione di 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. 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 Autorizzare le richieste.

Aggiungi un corpo JSON con l'user_id dell'utente, che puoi ottenere da users.get(), il roleId come descritto in Recuperare i ruoli esistenti e il condition. Le due stringhe di condizioni devono essere utilizzate letteralmente come mostrato di seguito e funzionano solo con i ruoli amministratore predefiniti di Editor di gruppi e 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 riuscita restituisce un codice di stato HTTP 200. Oltre al codice di stato, la risposta restituisce le proprietà della nuova assegnazione di 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'"
}

Gestisci ruoli Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.

Limiti per ruoli e assegnazioni di ruoli

Mappatura dei ruoli e dei privilegi della Console di amministrazione Google

Esempi di casi d'uso

Prima di iniziare

Visualizzare un elenco di privilegi di dominio

Richiesta

Risposta

Recuperare i ruoli esistenti

Richiesta

Risposta

Elenco di tutte le assegnazioni di ruoli

Richiesta

Risposta

Elenco di tutte le assegnazioni di ruolo indirette

Richiesta

Risposta

Crea un ruolo

Richiesta

Risposta

Creare un'assegnazione di ruolo

Richiesta

Risposta

Creare un'assegnazione di ruolo con condizioni

Richiesta

Applicabile solo ai gruppi di sicurezza

Non applicabile ai gruppi di sicurezza

Risposta

Gestisci ruoli