L'API Directory consente di utilizzare controllo controllo dell'accesso basato sui ruoli (RBAC) per gestire l'accesso alle funzionalità del tuo dominio Google Workspace. Puoi creare ruoli personalizzati con privilegi per limitare l'accesso amministrativo in modo più specifico rispetto a i ruoli predefiniti forniti con Google Workspace. Puoi assegnare ruoli a utenti o gruppi di sicurezza. Questa guida spiega come eseguire attività di base correlate al ruolo.
Di seguito è riportato un elenco dei termini comuni utilizzati dall'API Directory con riguardo a RBAC in Google Workspace:
- Privilegio
- L'autorizzazione necessaria per eseguire un'attività o un'operazione in una
dominio Google Workspace. Rappresentato dal
Privilege
. Là non sono presenti dati permanenti associati a questa risorsa. - Role
- Un insieme di privilegi che concede alle entità con quel ruolo:
di eseguire determinate attività o operazioni. Rappresentato dal
Role
. - Assegnazione del ruolo
- Il record di un ruolo specifico assegnato all'utente o al gruppo. Rappresentata da
RoleAssignment
. - Gruppo di sicurezza
- Un tipo di Gruppo Cloud Identity utilizzata per controllare l'accesso all'organizzazione Google Cloud. I gruppi di sicurezza possono contenere sia singoli utenti sia gruppi.
Limiti relativi alle assegnazioni dei ruoli e dei ruoli
Puoi creare solo un numero limitato di ruoli personalizzati o assegnazioni di ruoli, quindi se stai per raggiungere il limite, consolidali o rimuovili per rimanere entro 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), in cui l'organizzazione principale è considerata un'unità. Ad esempio, puoi assegnare 600 ruoli nell'organizzazione principale e 700 ruoli all'interno di un'altra UO da te definita, ad esempio un reparto di un'azienda. Tutti i ruoli amministrativi predefiniti di Google Workspace a livello di organizzazione. Scopri di più su limiti dei privilegi che possono essere assegnate a livello di UO.
I ruoli e le assegnazioni dei ruoli presentano i seguenti limiti per i gruppi:
- Puoi assegnare qualsiasi ruolo tranne Super amministratore.
- Puoi avere fino a 250 assegnazioni dei ruoli ai gruppi in totale nell'UO complessiva e all'interno di ogni UO.
- Il gruppo deve essere un gruppo di sicurezza della tua organizzazione.
- Ti consigliamo di limitare l'appartenenza ai gruppi agli utenti della tua organizzazione. Tu possono aggiungere utenti esterni all'organizzazione, ma potrebbero non ricevere i privilegi del ruolo. Per maggiori dettagli, vedi Limitare l'appartenenza ai gruppi. ### Assegnazione dei ruoli ai gruppi
Se devi assegnare più di 1000 ruoli in una UO, puoi aggiungere più a un gruppo di sicurezza e assegnargli un ruolo. Ruolo gruppo assegnate hanno alcune limitazioni aggiuntive: Centro assistenza per amministratori per informazioni specifiche.
Mappatura dei ruoli nella Console di amministrazione Google
Per assegnare ruoli agli utenti che accedono ai propri privilegi tramite
Console di amministrazione, potrebbe essere necessario
concesso. Ad esempio, per concedere a un utente la possibilità di creare altri utenti tramite
Console di amministrazione, non solo il privilegio USERS_CREATE
ma anche USERS_UPDATE
e ORGANIZATION_UNITS_RETRIEVE
privilegiati. La tabella seguente mappa la Console di amministrazione
le necessarie concessioni di privilegi per la gestione di utenti
le unità organizzative del dominio.
Funzionalità della Console di amministrazione | Privilegi necessari |
---|---|
Unità organizzative - Leggi | 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 la 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 la autenticazione e autorizzazione passaggi per Google Workspace.
Visualizzare un elenco dei privilegi di dominio
Per visualizzare un elenco impaginato dei privilegi supportati nel tuo dominio, utilizza il
privileges.list()
.
Se sei un amministratore e vuoi disporre dei privilegi nel tuo dominio, utilizza
my_customer
come ID cliente.Se sei un rivenditore e vuoi ottenere i privilegi per uno dei tuoi clienti, utilizzare l'ID cliente restituito dalla recuperare un utente.
Richiesta
GET https://admin.googleapis.com/admin/directory/v1/customer/customer_id/roles/ALL/privileges
Risposta
Una risposta corretta restituisce uno stato HTTP 200 Google Cloud. Insieme alle 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
}
]
},
...
]
}
Ottieni ruoli esistenti
Per ottenere un elenco dei ruoli esistenti, utilizza la seguente richiesta GET
e includi il
l'autorizzazione descritta in Autorizzare
richieste di assistenza.
Se sei un amministratore che ottiene ruoli nel tuo dominio, utilizza
my_customer
come ID cliente.Se sei un rivenditore e hai dei ruoli per un cliente, utilizza l'ID cliente che ottenuta utilizzando il comando Recupera utente.
Richiesta
GET https://admin.googleapis.com/admin/directory/v1/customer/customer_id/roles
Risposta
Una risposta corretta restituisce uno stato HTTP 200
Google Cloud. Insieme alle
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 dirette dei ruoli, utilizza il
roleAssignments.list()
. L'API potrebbe restituire risultati vuoti con un token di pagina quando userKey
è impostato. Devi continuare l'impaginazione finché non viene aggiunto alcun token di pagina
restituito.
Se sei un amministratore e ricevi assegnazioni dei ruoli nel tuo dominio, utilizza
my_customer
come ID cliente.Se sei un rivenditore e ricevi assegnazioni dei ruoli per uno dei tuoi clienti, utilizzare l'ID cliente restituito dalla recuperare un utente.
Richiesta
GET https://admin.googleapis.com/admin/directory/v1/customer/customer_id/roleassignments
Risposta
Una risposta corretta restituisce uno stato HTTP 200
Google Cloud. Insieme alle
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 dei ruoli indirette
Per ottenere un elenco impaginato di tutte le assegnazioni dei ruoli, incluse quelle
assegnate a un utente in base ai gruppi a cui appartengono, utilizza
roleAssignments.list()
.
L'API potrebbe restituire risultati vuoti con un token di pagina. Dovresti continuare l'impaginazione finché non viene restituito alcun token di pagina.
Se sei un amministratore e ricevi assegnazioni dei ruoli nel tuo dominio, utilizza
my_customer
come ID cliente.Se sei un rivenditore e ricevi assegnazioni dei ruoli per uno dei tuoi clienti, utilizzare l'ID cliente restituito dalla recuperare un utente.
Sostituisci
USER_KEY
con un valore che identifica il un utente nella richiesta API. Per ulteriori informazioni, vediusers.get
Richiesta
GET https://admin.googleapis.com/admin/directory/v1/customer/customer_id/roleassignments?userKey=USER_KEY&includeIndirectRoleAssignments=true
Risposta
Una risposta corretta restituisce uno stato HTTP 200
Google Cloud. Insieme alle
codice di stato, la risposta restituisce tutti i ruoli assegnati nel dominio
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 il
l'autorizzazione descritta in Autorizzare
richieste di assistenza.
Aggiungi privilegeName
e serviceId
per ogni privilegio che dovrebbe essere
a cui è assegnato questo ruolo. Per le proprietà della richiesta e della risposta, consulta la sezione API
Riferimento.
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 uno stato HTTP 200
Google Cloud. Insieme alle
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 del ruolo
Per assegnare un ruolo, usa il seguente metodo POST
e includi l'autorizzazione
descritti in
Autorizzare le richieste.
Per assegnare il ruolo a un utente, aggiungi un corpo JSON con il
user_id
dell'utente, che puoi utilizzare dausers.get()
,roleId
(come descritto in Ottieni i ruoli esistenti) e ilscope_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 Ottieni i ruoli esistenti) e ilscope_type
.Per assegnare il ruolo a un gruppo, aggiungi un corpo JSON con il valore
group_id
del che puoi otteneregroups.get()
,roleId
(come descritto in Ricevi 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 corretta restituisce uno stato HTTP 200
Google Cloud. Insieme alle
il 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. Al momento, sono supportate solo due condizioni:
- Applicabile solo ai gruppi di sicurezza
- Non applicabile ai gruppi di sicurezza
Se il criterio condition
è impostato, ha effetto solo quando la risorsa viene
a cui si accede soddisfa la condizione. Se il campo condition
è vuoto, il ruolo (roleId
) è
applicata all'attore (assignedTo
) nell'ambito (scopeType
) in modo incondizionato.
Per assegnare un ruolo a un utente, utilizza il seguente metodo POST e includi il l'autorizzazione descritta in Autorizza richieste.
Aggiungi un corpo JSON con il campo user_id
dell'utente, che puoi recuperare
users.get(), mentre roleId
descritto in Recuperare i ruoli esistenti e condition
. La
due stringhe di condizioni devono essere usate parola per parola, come mostrato di seguito,
funzionano solo con l'editor di gruppi e il lettore di gruppi
ruoli amministrativi predefiniti.
Queste condizioni seguono
Sintassi delle condizioni di 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 uno stato HTTP 200
Google Cloud. Insieme alle
il 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'"
}