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 a determinate app all'interno dello stesso progetto Google Cloud .
• Allinea le autorizzazioni alle esigenze organizzative e ai silos di dati per i tuoi deployment di Gemini Enterprise.

Importante: le autorizzazioni IAM a livello di progetto hanno la precedenza sui criteri 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 in quel progetto, indipendentemente dalle autorizzazioni a livello di app. Per limitare un utente a 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 quell'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 le risorse RU e un'app a livello aziendale. Un membro del team delleRUe con autorizzazioni a livello di progetto può accedere a entrambe le app. Al contrario, utilizzando un criterio IAM a livello di app, puoi concedere a un membro del team di vendita l'accesso solo all'app a livello aziendale, impedendogli così di accedere all'app RU.

Prima di iniziare

• Conferma di disporre del ruolo Amministratore Gemini Enterprise.

• Verifica che tutti gli utenti di Gemini Enterprise con una licenza valida dispongano del ruolo Utente Gemini Enterprise con limitazioni.

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 Gemini Enterprise (roles/discoveryengine.agentspaceUser) dal livello di progetto al livello di app, segui questi passaggi:

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

Gestire i criteri IAM per le app

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

I passaggi riportati di seguito mostrano come recuperare il criterio corrente e poi aggiornarlo per concedere o revocare l'accesso utente.

Recupera il criterio IAM dell'app

Recupera la policy IAM attuale della tua app utilizzando il metodo getIamPolicy. 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 multiregione per la tua richiesta API. Specifica uno dei seguenti valori:
  • us per la multi-regione Stati Uniti
  • eu per la multiregione EU
  • global per la località globale
  Per saperne di più, consulta Specifica una multi-regione per il datastore.
• LOCATION: la regione multipla del datastore: global, us o eu

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

  Nota: copia il valore etag dalla risposta. Questo valore è obbligatorio per aggiornare il criterio IAM. Il valore di etag cambia a ogni aggiornamento delle norme.

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"
}
  

Aggiorna la policy IAM dell'app

Per concedere o revocare l'accesso utente all'app, aggiorna il criterio IAM dell'app utilizzando il metodo setIamPolicy.

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

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

Nota: le modifiche alle norme IAM, ad esempio 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 ottenuto come risposta quando hai utilizzato il metodo getIamPolicy.

• USER_EMAIL, GROUP_EMAIL: uno o più indirizzi email di utenti o gruppi. 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 multiregione per la tua richiesta API. Specifica uno dei seguenti valori:

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

• LOCATION: la multiregione del datastore: global, us o eu.

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

  Nota: il valore etag cambia a ogni aggiornamento delle norme. Per aggiornare di nuovo la policy, devi prima ottenere 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.