Configure access controls for apps

This page explains how a Gemini Enterprise admin can use the API to manage fine-grained access control for individual Gemini Enterprise apps.

By default, IAM permissions are often managed at the project level. App-level IAM allows for more granular control, enabling admins to:

• Restrict user access to specific apps within the same Google Cloud project.
• Align permissions with organizational needs and data silos for your Gemini Enterprise deployments.

Note: Users with app-level IAM permissions for a Gemini Enterprise app can access and use only that specific app. These are user-level permissions that don't include admin capabilities.

For example, consider an organization with an HR app and a company-wide app. An HR team member with project-level permissions can access both the apps. By contrast, using an app-level IAM policy, you can grant a sales team member access to only the company-wide app, thereby preventing them from accessing the HR app.

Before you begin

• Confirm that you have the Gemini Enterprise Admin role.

• Confirm that all Gemini Enterprise users with a valid license have the Gemini Enterprise Restricted User role.

Manage IAM policies for apps

To manage access to your Gemini Enterprise app, you can use the getIamPolicy and setIamPolicy API methods.

The following steps show you how to retrieve the current policy and then update it to grant or revoke user access.

Get the app IAM policy

Get the current IAM policy of your app using the getIamPolicy method. It's recommended to fetch the existing policy first to avoid overwriting any current permissions.

REST

Key Term: In Gemini Enterprise, the term app can be used interchangeably with the term engine in the context of APIs. A Gemini Enterprise engine is a generic search engine where the app_type field is set to 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"

Replace the following:

• PROJECT_ID: the ID of your project.
• ENDPOINT_LOCATION: the multi-region for your API request. Specify one of the following values:
  • us for the US multi-region
  • eu for the EU multi-region
  • global for the Global location
  For more information, see Specify a multi-region for your data store.
• LOCATION: the multi-region of your data store: global, us, or eu

• APP_ID: the ID of the app that you want to configure.

  Note: Copy the etag value from the response. This value is required to update the IAM policy. The etag value changes with each policy update.

Example command and result

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

Update the app IAM policy

To grant or revoke user access to the app, update the app's IAM policy using the setIamPolicy method.

Important: The setIamPolicy method replaces the existing policy. To avoid removing existing permissions, your request must include all the policy bindings you want to retain, in addition to any new or modified bindings.

The IAM policy uses the Gemini Enterprise User (roles/discoveryengine.agentspaceUser) role to grant users direct access to the app.

Note: Changes to IAM policies, such as those made using setIamPolicy, are subject to propagation delays. It can take several minutes for permissions to fully propagate. For more information, see IAM propagation delay.

REST

Key Term: In Gemini Enterprise, the term app can be used interchangeably with the term engine in the context of APIs. A Gemini Enterprise engine is a generic search engine where the app_type field is set to 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_1",
              "user:USER_EMAIL_2"
            ]
          }
        ]
      }
    }' \
"https://ENDPOINT_LOCATION-discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/collections/default_collection/engines/APP_ID:setIamPolicy"

Replace the following:

• ETAG: the etag value you got as the response when you used the getIamPolicy method.

• USER_EMAIL_1, USER_EMAIL_2: one or more user email addresses.

  • To grant access, add user emails to the members array, each prefixed with user:

    Note: Avoid extra spaces before or after the email address.

  • To revoke access, remove the user email addresses from the members array.

• PROJECT_ID: the ID of your project.

• ENDPOINT_LOCATION: the multi-region for your API request. Specify one of the following values:

  • us for the US multi-region
  • eu for the EU multi-region
  • global for the Global location
  For more information, see Specify a multi-region for your data store.

• LOCATION: the multi-region of your data store: global, us, or eu.

• APP_ID: the ID of the app that you want to configure.

  Note: The etag value changes with each policy update. To update the policy again, you must first get the new etag by following Get the app IAM policy.

Example command and result

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-d '{
      "policy": {
         "etag": "1234567890",
         "bindings": [
          {
            "role": "roles/discoveryengine.agentspaceUser",
            "members": [
              "user:[e-mail]",
              "user:[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.agentspaceUser",
      "members": [
        "user:[e-mail]",
        "user:[e-mail]"
      ]
    }
  ]
}
  

What's next?

If you want to delete an app with an IAM policy, you can remove the users from the policy before deleting the app. For more information, see Best practices for deleting an app with an IAM policy.