Configure identity provider

To enforce data source access control and secure data in Agentspace, you must configure an identity provider. This involves setting up the identity provider and managing permissions for your data sources. Google uses your identity provider to identify the end user performing a search and determine if they have access to the documents that are returned as results.

Choose your identity provider type

The type of the identity provider you choose, depends on the data sources connected to your Agentspace app. Agentspace supports the following options:

Identity provider type	When to use
Google Identity	When you connect Agentspace to Google Workspace data sources, you must use Google Identity. Before configuring Google identity, you must determine the unique user attribute used by your organization, typically the user's email. If users have more than one email address, you must add an email alias.
Third-party identity provider	When you only connect Agentspace to third-party data sources, and you are already using a third-party identity provider that supports OIDC or SAML 2.0, such as Microsoft Entra ID, Active Directory Federation Services (AD FS), Okta, and others, you must use Workforce Identity Federation. For more information, see Workforce Identity Federation. Before configuring Workforce Identity Federation, you must determine the unique user attributes used by your organization, and these attributes must be mapped with Workforce Identity Federation.

Workforce Identity Federation for third-party identity providers

This section describes how to configure Workforce Identity Federation for third-party identity providers. Optionally, you can verify if the Workforce Identity Federation set up works as expected.

Configure Workforce Identity Federation

For details on configuring Workforce Identity Federation with your third-party identity connector, see the following resources:

Identity provider	Resources
Entra ID	Configure Workforce Identity Federation with Microsoft Entra ID and sign in users Configure Workforce Identity Federation with Microsoft Entra ID and a large number of groups
Okta	Configure Workforce Identity Federation with Okta and sign in users
OIDC or SAML 2.0	Configure Workforce Identity Federation with an identity provider (IdP) that supports OIDC or SAML 2.0

Configure attribute mapping

Attribute mapping helps you connect your third-party identity information with Google using Workforce Identity Federation.

When configuring attribute mapping in Workforce Identity Federation, consider the following:

• The google.subject attribute must map to the field that uniquely identifies end-users in third-party data sources. For example, email, principal name, user ID, or employee ID.

• If your organization has more than one unique identifier, map these unique organizational attributes using the attribute.as_user_identifier_number between 1 and 50 attribute.

  For example, if your organization uses both email and principal name as user identifiers across different applications, and the principal name is set as the preferred_username in your third-party identity provider, you can map it to Agentspace using the Workforce Identity Federation attribute mapping (for example, attribute.as_user_identifier_1=assertion.preferred_username).

The following are example google.subject and google.groups attribute mappings for commonly used identity providers.

• Entra ID with OIDC protocol
  This example uses the email to uniquely identify users.

  google.subject=assertion.email
  google.groups=assertion.groups
  google.display_name=assertion.given_name
  

• Entra ID with SAML protocol
  This example uses the SAML name ID to uniquely identify users.

  google.subject=assertion.attributes['http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress'][0]
  google.groups=assertion.attributes['http://schemas.microsoft.com/ws/2008/06/identity/claims/groups']
  google.display_name=assertion.attributes['http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname'][0]
  

• Okta with OIDC protocol
  This example uses the email to uniquely identify users.

  google.subject=assertion.email
  google.groups=assertion.groups
  

• Okta with SAML protocol
  This example uses the subject assertion of the JWT to uniquely identify users.

  google.subject=assertion.subject
  google.groups=assertion.attributes['groups']
  

Optional: Verify Workforce Identity Federation setup

To verify successful sign-ins and correct attribute mapping using the Workforce Identity Federation audit logging feature, do the following:

1. Enable audit logs for the Data Access activity's Security Token Service API.

   1. In the Google Cloud console, go to the Audit Logs page:

      Go to Audit Logs

      If you use the search bar to find this page, then select the result whose subheading is IAM & Admin.

   2. Select an existing Google Cloud project, folder, or organization.
   3. Enable the Data Access audit logs.
      1. See the Logging documentation for detailed steps on how to Enable audit logs.
      2. For the Security Token Service API, select the Admin Read audit log type. For more information, see Example logs for Workforce Identity Federation.

2. Enable detailed logging in your workforce pool. The Workforce Identity Federation extended groups feature for Microsoft Entra ID doesn't produce detailed audit logging information.

   1. Go to the Workforce Identity Pools page:

      Go to Workforce Identity Pools

   2. In the table, select the pool.

   3. Click the Enable detailed audit logging toggle to the on position.

   4. Click Save Pool.

3. In the Providers section, click the Sign in URL for your provider, and sign in to Google Cloud console as a workforce pool user.

4. See the audit logs that generated when you signed in.

   1. Go to the Workforce Identity Pools page:

      Go to Workforce Identity Pools

   2. In the table, select the pool you signed into.

   3. Click View next to Logs.

   4. On the audit log page clear the protoPayload.resourceName filter from the query.

   5. Click Run query.

5. Check the audit logs for an entry with the google.identity.sts.SecurityTokenService.WebSignIn method that matches the sign-in timestamp.

6. Confirm that the metadata.mapped_attributes field in the log matches the attribute that you used when configuring Workforce Identity Federation for third-party identity providers.

   For example:

   "metadata": {
     "mapped_attributes": {
       "attributes.as_user_identifier_1": "alex@admin.altostrat.com"
       "google.subject": "alex@altostrat.com"
       "google.groups": "[123abc-456d, efg-h789-ijk]"
     }
   },
   

Limitations

When connecting your data sources using a connector to create data stores, the following limitations apply:

• 3000 readers are allowed per document. Each principal counts as a reader, where a principal can be a group or an individual user.

• You can select one identity provider type per location supported in Agentspace.

• If the identity provider settings are updated by changing the identity provider type or the workforce pool, existing data stores won't automatically update to the new settings. You must delete and recreate these data stores to apply the new identity settings.

• To set a data source as access-controlled, you must select this setting during data store creation. You can't turn this setting on or off for an existing data store.

• To preview UI results for search apps that use third-party access control, you must sign in to the federated console or use the web app. See Preview your app.

Connect to your identity provider

The following section describes how to connect to your identity provider using Google Cloud console.

Before you begin

Before connecting the identity provider, do the following:

• Grant permissions to admins.

• If you are connecting a third-party identity provider, configure Workforce Identity Federation.

Connect identity provider

To specify an identity provider for Agentspace and turn on data source access control, follow these steps:

1. In the Google Cloud console, go to the Agentspace page.

   Agentspace

2. Click Settings > Authentication.

3. Click Add identity provider for the location you want to update.

4. Click Add identity provider and select your identity provider type.
   If you select 3rd party identity, you also need to select the workforce pool that applies for your data sources.

5. Click Save changes.

Grant permissions to users

Users need the Discovery Engine User (roles/discoveryengine.user) role to access, manage, and share apps.

Identity provider type	Description
Google Identity	If you use Google Identity, Google recommends creating a Google group that includes all employees who use the app. If you're a Google Workspace administrator, you can include all users in an organization to a Google group by following the steps in Add all your organization's users to a group. Grant the Discovery Engine User (roles/discoveryengine.user) role to users. For more information on adding the role, see Grant permissions to your users.
Third-party identity provider	Grant the Discovery Engine User (roles/discoveryengine.user) role to your users and workforce pool users in IAM policies. For more information on adding the role, see Grant permissions to your users. Google recommends configuring group claims for your third-party identities.

What's next?

• If you have Cloud Storage or BigQuery data stores and you want to enforce access control on the data, then you must configure access controls for custom data sources.

• If you connect to your own custom data source, learn how you can set up external identities.

• Preview your app.

• When you are ready to share the app with your users, you can turn on the app and share the URL with your user. Users need to sign in before they can access the app. For more information, see View the search web app.