Connect Microsoft Entra ID

This page describes how to connect Microsoft Entra ID to Agentspace Enterprise.

After you set up your data source and import data the first time, the data store syncs data from that source at a frequency that you select during setup.

Supported versions

The Entra ID connector supports all hosted versions of Entra ID through the Microsoft Graph API v1.0.

Before you begin

Before you set up your data store and import data, you must obtain a client ID and secret for authentication and configure the minimum required permissions for the application. This section provides information about how to complete these tasks.

Set up access control for Entra ID

Set up access control for your Entra ID data source. For information about setting up access control, see Use data source access control.

Obtain a client ID and client secret

  1. Create an Entra ID application:

    1. Sign in to Microsoft Entra administrator center as an administrator and click Application.
    2. In the Application drop-down list, click App registrations.
    3. In the App registrations page, click New registration.
    4. Click Add new registration and do the following:
      • Enter a name for the application.
      • Under Supported account types, select Accounts in the organizational directory only.
      • Under Redirect URI, add a web redirect URI pointing to: https://login.microsoftonline.com/common/oauth2/nativeclient.
    5. Click Register.
  2. Save credentials:

    On your registered application window, save the following values for later use:

    1. Use the Application (client) ID to set the Client ID parameter.
    2. Use the Directory (tenant) ID to set the Azure Tenant parameter.
  3. Create client secret:

    1. Navigate to Certificates & secrets.
    2. Click New client secret and specify a duration.
    3. Save the client secret and copy the client secret value for later use.
save-client-secret-value
Save the client secret value

Configure the minimum permissions required for the application

  1. On your registered application window, click API permissions.
  2. Under Configured permissions, select Microsoft Graph and configure the following permissions:

    • User.Read
    • User.Read.All (Application)

    If you want to ingest profileCardAttributes, then configure the following permissions:

    • People.Read.All (Application)
    • PeopleSettings.Read.All (Application)
    • PeopleSettings.Read.All (Delegated)

  3. Grant admin consent for all the added permissions. An administrator's consent is required to use client credentials in the authentication flow.

Minimum permissions

The following table lists the minimum permissions that you require to create an Entra ID connector:

Permission Usage reason Description
User.Read Data ingestion Read organization details during connection establishment.
User.Read.All (Application) Data ingestion Read all users in the organization.
People.Read.All (Application) Data ingestion Read all the relevant people information, such as contacts, for all users in an organization.
PeopleSettings.Read.All (Application) Data ingestion Read user configurations for all the users in the organization, such as profileCardSettings.
PeopleSettings.Read.All (Delegated) Data ingestion Read user configurations for all the users in the organization, such as profileCardSettings.

Create an Entra ID connector

To use the Google Cloud console to sync data from Entra ID to Agentspace Enterprise , follow these steps:

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

    Agentspace

  2. In the navigation menu, click Data stores.

  3. Click Create data store.

  4. On the Select a data source page, scroll or search for Entra ID to connect your third-party source.

  5. Under Authentication settings, enter the client ID and client secret.

  6. Under Advanced options:

    • If needed, click Enable Static IP Addresses. After creating the connector, you need to allowlist registered static IPs in order for sync runs to succeed.
    • To enable the connector to fetch extension properties, which are used to add a custom property to a directory object, select the Enable Extension Properties checkbox.
    • If you want to filter ingested user information, provide a custom SQL filter. The filter must be a valid SQL string.

      Keys in the filter string must correspond to the following fields:

      - `Id`
      - `employeeType`
      - `onPremisesSyncEnabled`
      - `accountEnabled`
      

      The following are examples of valid SQL filters:

      id = 'abc' AND accountEnabled = true
      
      employeeType='E' AND onPremisesSyncEnabled= true
      
    • In the Azure Tenant field, enter the Azure tenant ID that you obtained when you created an Entra ID application.

    • To apply a rate limit on the queries that the connector sends to the Entra ID instance, in the Max QPS field, specify the maximum queries per second. The default value is 80 QPS.

    • Click Continue.

  7. Under Choose entities you want to sync:

    • Click User Profiles.
    • Select the Full sync frequency.
  8. If you want the data updated in near real-time, select Enable realtime sync for all entities, and then enter a string value in the Client state field. The client state is used for the following purposes:

    • Auto registration of webhooks. The credentials that are passed during connection creation are reused for webhook authentication on the third-party app.
    • Authenticate change notifications.
  9. Click Continue.

  10. In Configure your data connector, select a region for your data store.

  11. Enter a name for your data connector.

  12. Click Create. Agentspace Enterprise creates your data store and displays your data stores on the Data stores page.

  13. If you selected Enable Static IP Addresses under Advanced options, view the registered static IP addresses for the connector and add them to your allowlist for Entra ID.

    1. Go to the Data stores page and click your connector name to see details about it on its Data page.
    2. In the Static IPs field, click View and confirm IPs.
    3. Copy the static IP addresses for the connector.
    4. In the Microsoft Entra administrator center, add the static IP addresses to a named or trusted location within an existing conditional access policy. For more information, see Conditional Access: Network assignment.

Check the connector state

  1. To check the status of your ingestion, go to the Data stores page and click your connector name to see details about it on its Data page. The Connector state changes from Creating to Running when it begins to synchronize data. When ingestion is complete, the state changes to Active to indicate that the connection to your data source is set up and awaiting the next scheduled synchronization.

    Depending on the size of your data, ingestion can take several minutes or several hours.

  2. When the connector state changes to Active, navigate to the Entity tab.

  3. Click the userprofiles entity.

  4. Check the number of ingested documents and verify that it matches the number of users in Entra ID.

    The following standard user attributes are ingested as part of each user record:

    Vertex AI schema field name Entra ID attribute name
    name.displayName Display Name
    name.familyName Last Name
    name.givenName First Name
    name.username User Principal Name
    email.value Email
    employeeId Employee Id
    personId
    employeeType Employee type
    hireDate Employee Hire Date
    department Department
    organizations.jobTitle Job title
    organizations.location Office Location
    Phone Business phone
    managers.email, managers.personId Not a direct attribute (management chain from immediate manager to top-level manager)
    directManager.personId Not a direct attribute (manager's personId)
    displayphoto.imagebinary.data Base64-encoded profile picture

    If the Entra ID app has the required permissions to ingest custom attributes, it ingests up to 15 profile card attributes per record. By default, the custom attributes are not searchable.

Configure searchable attributes

To make the custom attributes searchable, do the following:

  1. In the userprofiles page, navigate to the Schema tab.
  2. Click Edit.
  3. Deselect the attributes, such as address, from being retrievable, searchable, and indexable, then click Save.

    The Edit button remains inactive for a few minutes before reactivating.

  4. When the Edit button is in Active state, click Edit.

  5. Select the retrievable, searchable, and indexable boxes for the required custom attributes.

  6. Enable search.

  7. Click Save.

Test the search engine

After configuring your search engine, test its capabilities to verify whether it returns accurate results based on user access.

  1. Enable web app:

    1. Go to the app integration configurations and toggle to Enable the web app.
  2. Test web app:

    1. Click Open next to the web app link and sign in as a user.

    2. Verify that search results are restricted to items accessible by the user.

Preview people search results

  1. In the search app, navigate to Preview and start searching within the console when using Google IdP.

    • Alternatively, navigate to the provided link and sign in with your IdP to start searching.
    • The search results appear as people cards, displaying user details such as Name, Job title, Email, and Profile picture.
  2. Click a people card to view a detailed profile page, which includes the following:

    • Name
    • Profile picture
    • Job title
    • Department
    • Management chain
    • Direct reports
  3. If custom attributes (profile card properties) are ingested and made indexable, searchable, and retrievable:

    • Searching by a custom attribute value returns only person profiles containing those attributes.
    • Custom attributes appear in search results, but can only be accessed through the API, not the Vertex Search user interface.

Configure the workforce pool for non-Google IdP without SSO

  1. If your employees use a non-Google IdP, lack SSO with Google, or are not Google Workspace customers, set up a workforce pool as described in Use data source access control to enable the employee search.

    The workforce pool lets you to manage and authenticate users from external identity providers, such as Azure or Okta, within Google Cloud console.

  2. To configure your workforce pool and enable the web app for seamless user access, do the following:

    1. Create workforce pool at the organization level in Google Cloud by following the appropriate setup manual:

      1. Azure OIDC setup
      2. Azure SAML setup
      3. Okta & OIDC setup
      4. Okta & SAML setup
    2. Configure the workforce pool in Agentspace > Settings for the region where you create your app.

Recommended rate limits

The following table lists the recommended rate limits based on the number of users. Requests that exceed the limits are throttled.

Quota group Requests per second
S (Fewer than 50 users) 105
M (50-500 users) 150
L (More than 500 users) 240

Known limitations

This following are the known limitations for the Entra ID connector:

  • Incremental sync is not supported.
  • Access Control Lists (ACLs) are not supported. All the users are accessible across the organization.

Error messages

The following table lists the error messages that you might get when you use the Entra ID connector:

Error message Description Troubleshooting
Authorization_RequestDenied Insufficient privileges to complete the operation. The user account doesn't contain the required scopes to read data. Provide the required scopes to the user account that is used to create the connection.
Failed to retrieve OAuth token information The client credential provided when configuring the connector is invalid. Verify the following:
  • The client secret corresponding to the client ID is provided. When you configure the connection, specify the client secret value and not its secret ID.
  • The tenant ID is valid.

Next steps