Configurare i controlli dell'accesso per le app

Questa pagina spiega come un amministratore di Gemini Enterprise può utilizzare l'API per gestire il controllo dell'accesso granulare per le singole app Gemini Enterprise.

Per impostazione predefinita, le autorizzazioni IAM vengono spesso gestite a livello di progetto. IAM a livello di app consente un controllo più granulare, consentendo agli amministratori di:

• Limitare l'accesso degli utenti ad app specifiche all'interno dello stesso Google Cloud progetto.
• Allineare le autorizzazioni alle esigenze organizzative e ai silos di dati per i deployment di Gemini Enterprise.

Importante: le autorizzazioni IAM a livello di progetto hanno la precedenza sulle policy a livello di app. Se a un utente viene concesso un ruolo (ad esempio roles/discoveryengine.agentspaceUser) a livello di progetto, può accedere a tutte le app del progetto, indipendentemente dalle autorizzazioni a livello di app. Per limitare un utente ad app specifiche, devi rimuovere il ruolo dalle autorizzazioni a livello di progetto e poi concederlo a livello di app.

Nota: gli utenti con autorizzazioni IAM a livello di app per un' app Gemini Enterprise possono accedere e utilizzare solo l'app specifica. Si tratta di autorizzazioni a livello di utente che non includono funzionalità di amministrazione.

Ad esempio, considera un'organizzazione con un'app per RU e un'app a livello aziendale. Un membro del team delle RU con autorizzazioni a livello di progetto può accedere a entrambe le app. Al contrario, utilizzando una policy IAM a livello di app, puoi concedere a un membro del team di vendita l'accesso solo all'app a livello aziendale, impedendogli di accedere all'app per le RU.

Prima di iniziare

• Assicurati di avere il ruolo di amministratore di Gemini Enterprise.

• Assicurati che tutti gli utenti di Gemini Enterprise con una licenza valida abbiano il ruolo Utente con limitazioni di Gemini Enterprise.

Eseguire la transizione dall'accesso a livello di progetto a quello a livello di app

Per limitare gli utenti ad app specifiche, devi rimuovere il ruolo corrispondente dalle autorizzazioni a livello di progetto e poi concederlo a livello di app.

Ad esempio, per spostare un utente con il ruolo Utente di Gemini Enterprise (roles/discoveryengine.agentspaceUser) dal livello di progetto a quello di app, segui questi passaggi:

1. Nella Google Cloud console vai alla pagina IAM.
2. Trova l'utente e rimuovi il ruolo roles/discoveryengine.agentspaceUser dalle autorizzazioni a livello di progetto.
3. Utilizza il metodo setIamPolicy per concedere all'utente il roles/discoveryengine.agentspaceUser ruolo per l'app specifica. Per saperne di più, consulta Gestire le policy IAM per le app.

Gestire le policy IAM per le app

Per gestire l'accesso all'app Gemini Enterprise, puoi utilizzare i metodi API getIamPolicy e setIamPolicy.

I passaggi riportati di seguito mostrano come recuperare la policy attuale e poi aggiornarla per concedere o revocare l'accesso degli utenti.

Recuperare la policy IAM dell'app

Recupera la policy IAM attuale dell'app utilizzando il getIamPolicy metodo. Ti consigliamo di recuperare prima la policy esistente per evitare di sovrascrivere le autorizzazioni attuali.

REST

Termine chiave: in Gemini Enterprise, il termine app può essere utilizzato in modo intercambiabile con il termine motore nel contesto delle API. Un motore Gemini Enterprise è un motore di ricerca generico in cui il campo app_type è impostato su APP_TYPE_INTRANET.

curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
"https://ENDPOINT_LOCATION-discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/collections/default_collection/engines/APP_ID:getIamPolicy"

Sostituisci quanto segue:

• PROJECT_ID: l'ID progetto.
• ENDPOINT_LOCATION: la multi-regione per la richiesta API. Specifica uno dei seguenti valori:
  • us per la multi-regione Stati Uniti
  • eu per la multi-regione UE
  • global per la località globale
  Per saperne di più, consulta Specifica una multi-regione per il datastore.
• LOCATION: la multi-regione del datastore: global, us o eu

• APP_ID: l'ID dell'app che vuoi configurare.

  Nota: copia il valore etag dalla risposta. Questo valore è necessario per aggiornare la policy IAM. Il valore etag cambia a ogni aggiornamento della policy.

Esempio di comando e risultato

curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
"https://global-discoveryengine.googleapis.com/v1/projects/my-project-123/locations/global/collections/default_collection/engines/my-app:getIamPolicy"

{
  "version": 1,
  "etag": "1234567890"
}
  

Aggiornare la policy IAM dell'app

Per concedere o revocare l'accesso degli utenti all'app, aggiorna la policy IAM dell'app utilizzando il setIamPolicy metodo.

Importante: il metodo setIamPolicy sostituisce la policy esistente. Per evitare di rimuovere le autorizzazioni esistenti, la richiesta deve includere tutte le associazioni di policy che vuoi conservare, oltre a eventuali associazioni nuove o modificate.

La policy IAM utilizza il ruolo Utente di Gemini Enterprise (roles/discoveryengine.agentspaceUser) per concedere agli utenti l'accesso diretto all'app.

Nota: le modifiche alle policy IAM, come quelle apportate utilizzando setIamPolicy, sono soggette a ritardi di propagazione. La propagazione completa delle autorizzazioni può richiedere diversi minuti. Per saperne di più, consulta Ritardo di propagazione di IAM.

REST

Termine chiave: in Gemini Enterprise, il termine app può essere utilizzato in modo intercambiabile con il termine motore nel contesto delle API. Un motore Gemini Enterprise è un motore di ricerca generico in cui il campo app_type è impostato su APP_TYPE_INTRANET.

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-d '{
      "policy": {
         "etag": "ETAG",
         "bindings": [
          {
            "role": "roles/discoveryengine.agentspaceUser",
            "members": [
              "user:USER_EMAIL",
              "group:GROUP_EMAIL",
              "principal://iam.googleapis.com/locations/global/workloadIdentityPools/POOL_ID/subject/SUBJECT_ID",
              "principalSet://iam.googleapis.com/locations/global/workloadIdentityPools/POOL_ID/attribute.NAME/VALUE"
            ]
          }
        ]
      }
    }' \
"https://ENDPOINT_LOCATION-discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/collections/default_collection/engines/APP_ID:setIamPolicy"

Sostituisci quanto segue:

• ETAG: il valore etag che hai ricevuto come risposta quando hai utilizzato il metodo getIamPolicy.

• USER_EMAIL, GROUP_EMAIL: uno o più indirizzi email di utenti o email di gruppo. Oltre a user e group, principal e principalSet sono tipi di membri validi per la federazione delle identità per i workload.

  • Per concedere l'accesso, aggiungi le entità all'array members. Ad esempio, "user:[e-mail]" o "group:[e-mail]".

    Nota: evita spazi aggiuntivi prima o dopo l'indirizzo email.

  • Per revocare l'accesso, rimuovi le entità dall'array members.

• POOL_ID: l'ID del pool di identità del workload.

• SUBJECT_ID: l'identificatore del soggetto per un'identità specifica.

• NAME: il nome di un attributo.

• VALUE: il valore di un attributo.

• PROJECT_ID: l'ID progetto.

• ENDPOINT_LOCATION: la multi-regione per la richiesta API. Specifica uno dei seguenti valori:

  • us per la multi-regione Stati Uniti
  • eu per la multi-regione UE
  • global per la località globale
  Per saperne di più, consulta Specifica una multi-regione per il datastore.

• LOCATION: la multi-regione del datastore: global, us o eu.

• APP_ID: l'ID dell'app che vuoi configurare.

  Nota: il valore etag cambia a ogni aggiornamento della policy. Per aggiornare di nuovo la policy, devi prima recuperare il nuovo etag seguendo la procedura descritta in Recuperare la policy IAM dell'app.

Esempio di comando e risultato

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-d '{
      "policy": {
         "etag": "1234567890",
         "bindings": [
          {
            "role": "roles/discoveryengine.user",
            "members": [
              "user:[e-mail]",
              "group:[e-mail]"
            ]
          }
        ]
      }
    }' \
"https://global-discoveryengine.googleapis.com/v1/projects/my-project-123/locations/global/collections/default_collection/engines/my-app:setIamPolicy"

{
  "version": 1,
  "etag": "2345678901",
  "bindings": [
    {
      "role": "roles/discoveryengine.user",
      "members": [
        "user:cloudysanfrancisco.com",
        "group:[e-mail]"
      ]
    }
  ]
}
  

Passaggi successivi

Se vuoi eliminare un'app con una policy IAM, puoi rimuovere gli utenti dalla policy prima di eliminare l'app. Per saperne di più, consulta Best practice per l'eliminazione di un'app con una policy IAM.