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, 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 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, utilizza
my_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, utilizza
my_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, utilizza
my_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, consultausers.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 dausers.get()
, ilroleId
(come descritto in Ottenere i ruoli esistenti) e ilscope_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)), ilroleId
(come descritto in Ottenere i ruoli esistenti) e ilscope_type
.Per assegnare il ruolo a un gruppo, aggiungi un corpo JSON con il
group_id
del gruppo, che puoi ottenere dagroups.get()
,roleId
(come descritto in Ottenere i ruoli esistenti) escope_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'"
}