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.

Se devi configurare controlli dell'accesso granulari a livello di risorsa sia per le app sia per i datastore, consulta Configurare controlli dell'accesso granulari per app e datastore.

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 le implementazioni 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 il ruolo Gemini Enterprise User (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, sostituisci il suo ruolo Gemini Enterprise User a livello di progetto con il ruolo Gemini Enterprise Restricted User (roles/discoveryengine.agentspaceRestrictedUser) e poi concedi il ruolo Gemini Enterprise User a ogni app a cui deve accedere.

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 RU e un'app a livello aziendale. Un membro del team 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 RU.

Prima di iniziare

• Verifica di avere il ruolo Gemini Enterprise Admin (roles/discoveryengine.agentspaceAdmin).

• Verifica che tutti gli utenti di Gemini Enterprise abbiano una licenza valida e che sia stato concesso loro il ruolo Gemini Enterprise Restricted User (roles/discoveryengine.agentspaceRestrictedUser) a livello di progetto. Per istruzioni, consulta Concedere autorizzazioni agli utenti.

  Questo ruolo non concede l'accesso a nessuna app. Fornisce l'accesso a livello di progetto di cui gli utenti hanno bisogno, quindi concedi l'accesso alle singole app. Se utilizzi un ruolo personalizzato a livello di progetto anziché il ruolo predefinito roles/discoveryengine.agentspaceRestrictedUser, assicurati che il ruolo personalizzato includa le autorizzazioni discoveryengine.locations.buildAuthorizationUrl, discoveryengine.dataStores.get, discoveryengine.collections.get e discoveryengine.devToolsConfigs.get. L'omissione di discoveryengine.devToolsConfigs.get causa un errore 403 PERMISSION_DENIED in Cloud Audit Logs quando l'app web controlla devToolsConfig.

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

Per limitare gli utenti ad app specifiche, devi sostituire il loro ruolo utente aziendale Gemini Enterprise a livello di progetto con il ruolo Gemini Enterprise Restricted User e poi concedere il ruolo utente aziendale Gemini Enterprise a livello di singola app.

Per eseguire la transizione di un utente dall'accesso a livello di progetto all'accesso a livello di app: Utilizza la Google Cloud console per le modifiche a livello di progetto, e l'API per la concessione a livello di app, che la Google Cloud console non supporta.

1. Nella Google Cloud console vai alla pagina IAM.
2. Trova l'utente e rimuovi il ruolo Utente aziendale Gemini Enterprise (roles/discoveryengine.agentspaceUser) dalle sue autorizzazioni a livello di progetto.
3. Se non l'hai ancora fatto, concedi all'utente il ruolo Gemini Enterprise Restricted User (roles/discoveryengine.agentspaceRestrictedUser) a livello di progetto.
4. Utilizza il metodo setIamPolicy per concedere all'utente il ruolo Gemini Enterprise User (roles/discoveryengine.agentspaceUser) per ogni app specifica a cui deve accedere. 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 seguenti mostrano come recuperare la policy corrente e poi aggiornarla per concedere o revocare l'accesso degli utenti.

Recuperare la policy IAM dell'app

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

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 Unione Europea
  • 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 Gemini Enterprise User (roles/discoveryengine.agentspaceUser) per concedere agli utenti l'accesso diretto a l'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 gruppi. Oltre a user e group, principal e principalSet sono tipi di membri validi per la federazione Workload Identity.

  • 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à per i 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 Unione Europea
  • 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 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.