Configurar controles de acesso para apps

Nesta página, explicamos como um administrador do Gemini Enterprise pode usar a API para gerenciar o controle de acesso refinado de 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 administradores:

• Restringir o acesso do usuário a apps específicos no mesmo projeto do Google Cloud .
• Alinhe as permissões com as necessidades organizacionais e os silos de dados para suas 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 desse 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, em seguida, conceda o papel de usuário do Gemini Enterprise em cada app que ele precisa acessar.

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

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, é possível 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 administrador do Gemini Enterprise (roles/discoveryengine.agentspaceAdmin).

• Confirme se todos os usuários corporativos do Gemini Enterprise têm uma licença válida e se receberam 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 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. Omitir discoveryengine.devToolsConfigs.get causa um erro 403 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 o papel de usuário do Gemini Enterprise no nível do projeto pelo papel de usuário restrito do Gemini Enterprise e, em seguida, conceda o papel de usuário 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. Use o console do Google Cloud para as mudanças para envolvidos no projeto e a API para a concessão no nível do app, que não é compatível com o console do Google Cloud .

1. No console do Google Cloud , 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 a função de usuário corporativo do Gemini Enterprise (roles/discoveryengine.agentspaceUser) para cada app específico que ele precisa 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, use 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.

Acessar a política de IAM do app

Consiga a política atual do IAM do seu app usando o método getIamPolicy. É recomendável buscar primeiro a política atual para evitar a substituição de permissões.

REST

Termo-chave:no Gemini Enterprise, o termo app pode ser usado como sinônimo de mecanismo no contexto de APIs. Um mecanismo do Gemini Enterprise é um mecanismo de pesquisa genérico em que o campo app_type é 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 é obrigatório para atualizar a política do IAM. O valor de 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 de IAM do app

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

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

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

Observação : as alterações 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-chave:no Gemini Enterprise, o termo app pode ser usado como sinônimo de mecanismo no contexto de APIs. Um mecanismo do Gemini Enterprise é um mecanismo de pesquisa genérico em que o campo app_type é 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 de 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 de 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 é preciso receber o novo etag seguindo 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.