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, consultausers.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 dausers.get()
,roleId
(come descritto in Recupero dei ruoli esistenti) escope_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) escope_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 Recupero dei 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 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'"
}