Configurar controles de acesso para apps

Nesta página, explicamos como um admin do Gemini Enterprise pode usar a API para gerenciar o controle de acesso refinado para apps individuais do Gemini Enterprise.

Se você precisar configurar controles de acesso granulares no nível do recurso em apps e repositórios de dados, consulte Configurar controles de acesso granulares para apps e repositórios de dados.

Por padrão, as permissões do IAM costumam ser gerenciadas no nível do projeto. O IAM no nível do app permite um controle mais granular, permitindo que os admins:

• Restrinjam o acesso do usuário a apps específicos no mesmo Google Cloud projeto.
• Alinhem as permissões às necessidades organizacionais e aos silos de dados para as implantações do Gemini Enterprise.

Importante: as permissões do IAM no nível do projeto têm precedência sobre as políticas no nível do app. Se um usuário receber o papel de usuário corporativo do Gemini Enterprise (roles/discoveryengine.agentspaceUser) no nível do projeto, ele poderá acessar todos os apps nesse projeto, independentemente das permissões no nível do app. Para restringir um usuário a apps específicos, substitua o papel de usuário do Gemini Enterprise no nível do projeto pelo papel de usuário restrito do Gemini Enterprise (roles/discoveryengine.agentspaceRestrictedUser) e conceda o papel de usuário do Gemini Enterprise em cada app que ele precisar acessar.

Observação: os usuários com permissões do IAM no nível do app para um app do Gemini Enterprise só podem acessar e usar esse app específico. Essas são permissões no nível do usuário que não incluem recursos de admin.

Por exemplo, considere uma organização com um app de RH e um app para toda a empresa. Um membro da equipe de RH com permissões no nível do projeto pode acessar os dois apps. Por outro lado, usando uma política do IAM no nível do app, você pode conceder a um membro da equipe de vendas acesso apenas ao app de toda a empresa, impedindo que ele acesse o app de RH.

Antes de começar

• Confirme se você tem o papel de admin do Gemini Enterprise (roles/discoveryengine.agentspaceAdmin).

• Confirme se todos os usuários corporativos do Gemini Enterprise têm uma licença válida e recebem o papel de usuário restrito do Gemini Enterprise (roles/discoveryengine.agentspaceRestrictedUser) no nível do projeto. Para instruções, consulte Conceder permissões aos usuários.

  Esse papel não concede acesso a nenhum app por conta própria. Ele fornece o acesso no nível do projeto de que os usuários precisam, e você concede acesso a apps individuais. Se você usar um papel personalizado para envolvidos no projeto em vez do papel predefinido roles/discoveryengine.agentspaceRestrictedUser, verifique se o papel personalizado inclui as permissões discoveryengine.locations.buildAuthorizationUrl, discoveryengine.dataStores.get, discoveryengine.collections.get e discoveryengine.devToolsConfigs.get. A omissão de discoveryengine.devToolsConfigs.get causa um erro403 PERMISSION_DENIED nos Registros de auditoria do Cloud quando o app da Web verifica devToolsConfig.

Transição do acesso para envolvidos no projeto para o acesso no nível do app

Para restringir os usuários a apps específicos, substitua a função de usuário corporativo do Gemini Enterprise para envolvidos no projeto pela função de usuário restrito do Gemini Enterprise e conceda a função de usuário corporativo do Gemini Enterprise no nível do app individual.

Para fazer a transição de um usuário do acesso para envolvidos no projeto para o acesso no nível do app, siga estas etapas. Você usa o Google Cloud console para as mudanças para envolvidos no projeto, e a API para a concessão no nível do app, que o Google Cloud console não oferece suporte.

1. No Google Cloud console, acesse a página IAM.
2. Encontre o usuário e remova o papel de usuário corporativo do Gemini Enterprise (roles/discoveryengine.agentspaceUser) das permissões para envolvidos no projeto.
3. Se ainda não tiver feito isso, conceda ao usuário o papel de usuário restrito do Gemini Enterprise (roles/discoveryengine.agentspaceRestrictedUser) no nível do projeto.
4. Use o método setIamPolicy para conceder ao usuário o papel de usuário corporativo do Gemini Enterprise (roles/discoveryengine.agentspaceUser) para cada app específico que ele precisar acessar. Para mais informações, consulte Gerenciar políticas do IAM para apps.

Gerenciar políticas do IAM para apps

Para gerenciar o acesso ao app do Gemini Enterprise, você pode usar os métodos de API getIamPolicy e setIamPolicy.

As etapas a seguir mostram como recuperar a política atual e atualizá-la para conceder ou revogar o acesso do usuário.

Receber a política do IAM do app

Receba a política do IAM atual do app usando o getIamPolicy método. Recomendamos buscar a política atual primeiro para evitar a substituição de permissões atuais.

REST

Termo principal: no Gemini Enterprise, o termo app pode ser usado de forma intercambiável com o termo mecanismo no contexto das APIs. Um mecanismo do Gemini Enterprise é um mecanismo de pesquisa genérico em que o app_type campo está definido como 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"

Substitua:

• PROJECT_ID: ID do projeto.
• ENDPOINT_LOCATION: a multirregião da sua solicitação de API. Especifique um dos seguintes valores:
  • us para a multirregião dos EUA
  • eu para a multirregião da UE
  • global para o local global
  Para mais informações, consulte Especificar uma multirregião para seu repositório de dados.
• LOCATION: a multirregião do seu repositório de dados: global, us ou eu

• APP_ID: o ID do app que você quer configurar.

  Observação: Copie o valor etag da resposta. Esse valor é necessário para atualizar a política do IAM. O valor etag muda a cada atualização da política.

Exemplo de comando e resultado

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

Atualizar a política do IAM do app

Para conceder ou revogar o acesso do usuário ao app, atualize a política do IAM do app usando o setIamPolicy método.

Importante: O método setIamPolicy substitui a política atual. Para evitar a remoção de permissões atuais, sua solicitação precisa incluir todas as vinculações de política que você quer manter, além de vinculações novas ou modificadas.

A política do IAM usa o usuário do Gemini Enterprise (roles/discoveryengine.agentspaceUser) para conceder aos usuários acesso direto ao app.

Observação: as mudanças nas políticas do IAM, como as feitas usando setIamPolicy, estão sujeitas a atrasos de propagação. Pode levar vários minutos para que as permissões sejam totalmente propagadas. Para mais informações, consulte Atraso de propagação do IAM.

REST

Termo principal: no Gemini Enterprise, o termo app pode ser usado de forma intercambiável com o termo mecanismo no contexto das APIs. Um mecanismo do Gemini Enterprise é um mecanismo de pesquisa genérico em que o app_type campo está definido como 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"

Substitua:

• ETAG: o valor etag que você recebeu como resposta ao usar o método getIamPolicy.

• USER_EMAIL, GROUP_EMAIL: um ou mais endereços de e-mail de usuário ou grupo. Além de user e group, principal e principalSet são tipos de membros válidos para a federação de identidade da carga de trabalho.

  • Para conceder acesso, adicione principais à matriz members. Por exemplo, "user:[e-mail]" ou "group:[e-mail]".

    Observação: evite espaços extras antes ou depois do endereço de e-mail.

  • Para revogar o acesso, remova os principais da matriz members.

• POOL_ID: o ID do pool de Identidade da carga de trabalho.

• SUBJECT_ID: o identificador de assunto para uma identidade específica.

• NAME: o nome de um atributo.

• VALUE: o valor de um atributo.

• PROJECT_ID: ID do projeto.

• ENDPOINT_LOCATION: a multirregião da sua solicitação de API. Especifique um dos seguintes valores:

  • us para a multirregião dos EUA
  • eu para a multirregião da UE
  • global para o local global
  Para mais informações, consulte Especificar uma multirregião para seu repositório de dados.

• LOCATION: a multirregião do seu repositório de dados: global, us ou eu.

• APP_ID: o ID do app que você quer configurar.

  Observação: O valor etag muda a cada atualização da política. Para atualizar a política novamente, primeiro receba o novo etag seguindo as instruções em Receber a política do IAM do app.

Exemplo de comando e resultado

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

A seguir

Se você quiser excluir um app com uma política do IAM, remova os usuários da política antes de excluir o app. Para mais informações, consulte Práticas recomendadas para excluir um app com uma política do IAM.