Configure authentication for Agentic Retrieval in Foundry Local

For your Agentic Retrieval deployment, register an application, create app roles, and assign users or groups in Microsoft Entra ID. This article is part of the deployment prerequisites checklist and also a prerequisite of Quickstart: Install Agentic Retrieval.

You might need to work with your Microsoft Entra or cloud administrator to configure authentication.

Prerequisites

Before you begin, make sure you have:

• An active Azure subscription. If you don't have a service subscription, create a free account before you begin.
• Microsoft Entra ID permissions:
  • Permissions to create a Microsoft Enterprise Entra application.
  • Ability to add new or existing Microsoft Entra users and groups to the application.

Register an application in Microsoft Entra ID

Create and configure an application registration for Agentic Retrieval in your Microsoft Entra ID tenant.

1. In the Azure portal, go to Microsoft Entra ID.

2. Go to the appropriate tenant and select Manage > App registrations.

3. Select New registration to create an application registration.

   

4. Enter EdgeRAG for Name.

5. Select Accounts in any organizational directory (Any Microsoft Entra ID tenant - Multitenant).

6. Select Register.

   

7. After the application is registered, go to the registration and select Manage > Authentication.

8. Select Add a platform > Single-page application.

9. Specify your domain name (for example, https://arcrag.contoso.com/) as the Redirect URIs.

   

10. Select Configure.

11. For Supported account types, select Accounts in any organizational directory (Any Microsoft Entra ID tenant - Multitenant).

    

12. Select + Add a platform > Mobile and desktop applications.

13. For Redirect URIs, select https://login.microsoftonline.com/common/oauth2/nativeclient.

14. Select Configure.

Create app roles for Agentic Retrieval

Within the Agentic Retrieval app registration, create app roles for AI application developers and end users of the chat endpoint.

1. In the app registration, on the left-hand side menu, under Manage, select App roles.

2. Create two app roles. One for EdgeRAGDeveloper and another for EdgeRAGEndUser. Use the appropriate values listed in the table that follows the image.

   

   Field	Value
   Display name	EdgeRAGDeveloper or EdgeRAGEndUser
   Allowed member types	User/Groups
   Value	EdgeRAGDeveloper or EdgeRAGEndUser
   Description	EdgeRAGDeveloper or EdgeRAGEndUser
   Do you want to enable this app role?	Checked

3. When complete, close the App roles page.

Assign users or groups to roles

Next, in the Microsoft Entra ID tenant, assign users or groups to the roles you created for Agentic Retrieval.

1. In the Microsoft Entra ID tenant, on the left-hand side menu under Manage, select Enterprise applications.
2. Search for and select the EdgeRag application you created.
3. Go to Manage > Properties.
4. Disable Assignment Required.
5. On the left-hand side menu, select Users and groups > Add user/group.
6. Select users and groups and assign the EdgeRAGDeveloper or EdgeRAGEndUser role as appropriate. Assign both roles to the developers working on the chat solution.
7. When complete, close the Users and groups page.

Create app roles for collection access

The EdgeRAGEndUser role alone doesn't grant query access. Each end user also needs an app role whose Value exactly matches each collection name they can query.

Start with the default edgeragapp collection that's created when you deploy the extension. If you don't specify a collection during ingestion, data is ingested into edgeragapp. After deployment, create and assign one matching app role for each additional collection you add.

Create and assign collection app roles for edgeragapp and every additional collection before end users query data. Data ingestion succeeds without these roles, but queries fail with 403 Forbidden.

Create a collection app role

1. In the Azure portal, go to Microsoft Entra ID > App registrations and select your Agents and Tools app registration.

2. On the left-hand side menu, under Manage, select App roles.

3. Select Create app role.

4. Create an app role for the default edgeragapp collection or a collection you create after you install the extension. Use the following values:

   Field	Value
   Display name	A descriptive name (for example, Default Collection or Finance Docs Collection)
   Allowed member types	Users/Groups
   Value	The exact collection name. For the default collection, use edgeragapp. This value must match the collection name used in the API.
   Description	Description of the collection access (for example, Grants query access to the default edgeragapp collection)
   Do you want to enable this app role?	Checked

5. Select Apply.

6. After deployment, if you create additional collections, repeat these steps for each collection (for example, finance-docs).

Assign users to collection app roles

1. In the Microsoft Entra ID tenant, on the left-hand side menu under Manage, select Enterprise applications.
2. Search for and select the EdgeRag application.
3. On the left-hand side menu, select Users and groups > Add user/group.
4. Select the users or groups who need access to the collection.
5. Select the collection app role (for example, edgeragapp for the default collection).
6. Complete the assignment.

Example

The following table shows an example of collection app role assignments:

At query time, a user querying edgeragapp must have the edgeragapp app role in their token. The same rule applies to each additional collection (for example, finance-docs). Otherwise, the request is denied with 403 Forbidden.

For more information about how collections use RBAC, see Collections and RBAC.

(Optional) Register a Foundry Local application

If you use Foundry Local as your model endpoint, you need a second app registration to identify the Foundry inference service. This registration provides the foundryClientId value used for managed identity token scope (<client_id>/.default).

For instructions on creating the Foundry Local app registration, see Configure authentication for Foundry Local.

After you deploy the extension, configure Foundry Local managed identity role assignments. For steps, see Configure Foundry Local inference authentication for Agentic Retrieval.

(Optional) Get app and tenant IDs

If you plan to use the quickstart or want to deploy Agentic Retrieval by using the command line, get the application ID for the registration you created and the tenant ID.

1. In the Azure portal, search for app registration.
2. Select the Agentic Retrieval registration you created.
3. Copy the Application (client) ID and Directory (tenant) ID.
4. Paste the values to an app like Windows Notepad to use later.

Next step