Azure AI Foundry Agents Web API with On-Behalf-Of Authentication

This project demonstrates how to build an ASP.NET Core Web API that interacts with Azure AI Foundry Agents using the Fabric Data agent tool. The API implements the OAuth 2.0 On-Behalf-Of (OBO) flow to exchange user tokens for service tokens, enabling secure, delegated access to Azure AI services.

Architecture Overview

The solution consists of three main components:

1. Web API (Server): ASP.NET Core API that receives user tokens and exchanges them via OBO flow to access Azure AI Foundry
2. Client Application: An Entra ID application that obtains user tokens to call the Web API
3. Azure AI Foundry: The AI service that hosts agents with Fabric Data agent capabilities

Authentication Flow

User → Client App → Obtain User Token → Call Web API with Bearer Token
                                              ↓
                            Web API exchanges token via OBO flow
                                              ↓
                            Azure AI Foundry validates OBO token
                                              ↓
                            Create Agent with Fabric Data agent tool
                                              ↓
                            Execute Agent and return results

Prerequisites

• Azure subscription with access to Azure AI Foundry
• Microsoft Fabric workspace with an active capacity
• Azure AI Foundry project with a Fabric connection configured
• Permissions to create Entra ID app registrations
• .NET 9.0 SDK or later

Setup Instructions

1. Create the Web API (Server) App Registration

This app registration represents your Web API service.

1.1 Create the App Registration

1. Navigate to Azure Portal → Entra ID → App registrations
2. Click New registration
3. Set the following:
   • Name: API app (or your preferred name)
   • Supported account types: Accounts in any organizational directory and personal Microsoft accounts
   • Redirect URI: Leave blank for now
4. Click Register
5. Note the Application (client) ID and Directory (tenant) ID

1.2 Configure Expose an API (Scopes)

1. Go to Expose an API in the left menu

2. Click Add a scope

3. Set Application ID URI to api://<your-client-id> (e.g., api://599719A0-8583-4A38-B7AE-3F7EAC025E87)

4. Add the following scope:

   Scope 1: user_impersonation

   • Scope name: user_impersonation
   • Who can consent: Admins and users
   • Admin consent display name: User Impersonation
   • Admin consent description: User impersonation
   • User consent display name: User Impersonation
   • User consent description: User Impersonation
   • State: Enabled

1.3 Configure API Permissions

Add the following API permissions:

1. Click API permissions → Add a permission

   Azure Machine Learning Services

   • Resource App ID: 18a66f5f-dbdf-4c17-9dd7-1634712a9cbe
   • Permission ID: 1a7925b5-f871-417a-9b8b-303f9f29fa10 (Delegated)
   • Type: Scope

2. Click Grant admin consent for your tenant

1.4 Create Client Secret

1. Go to Certificates & secrets
2. Click New client secret
3. Set Description: api secret
4. Set Expires: Choose appropriate expiration (e.g., 12 months)
5. Click Add
6. Copy the secret value immediately (you won't be able to see it again)

1.5 Configure Authentication Settings

1. Go to Authentication
2. Under Advanced settings:
   • Set Allow public client flows: Yes
3. Add Redirect URI:
   • Platform: Web
   • URI: https://localhost:7422 (adjust to your API's URL)
4. Under Implicit grant and hybrid flows, enable:
   • Access tokens
   • ID tokens

2. Create the Client App Registration

This app registration represents the client application that will call your Web API.

2.1 Create the App Registration

1. Navigate to Entra ID → App registrations
2. Click New registration
3. Set the following:
   • Name: Client app (or your client app name)
   • Supported account types: Accounts in any organizational directory and personal Microsoft accounts
   • Redirect URI: Web → https://localhost/signin-oidc
4. Click Register
5. Note the Application (client) ID

2.2 Configure API Permissions

1. Click API permissions → Add a permission → My APIs
2. Select your API app
3. Check the delegated permissions:
   • user_impersonation
4. Click Add permissions
5. Click Grant admin consent for your tenant

2.3 Create Client Secret

1. Go to Certificates & secrets
2. Click New client secret
3. Set Description: client-secret
4. Set Expires: Choose appropriate expiration
5. Click Add
6. Copy the secret value immediately

2.4 Configure Redirect URI

1. Go to Authentication
2. Ensure redirect URI is set to: https://localhost/signin-oidc

3. Pre-authorize the Client App (Optional but Recommended)

To avoid consent prompts, pre-authorize the client app in the Web API registration:

1. Go back to your API app registration
2. Navigate to Expose an API
3. Under Authorized client applications, click Add a client application
4. Enter the Client ID of your Client app app
5. Check scopes:
   • user_impersonation
6. Click Add application

4. Configure Azure AI Foundry

4.1 Create or Use Existing AI Foundry Project

1. Navigate to Azure AI Foundry
2. Create or select an existing project
3. Note the Project endpoint (e.g., https://yourproject.services.ai.azure.com/api/projects/name-of-project)

4.2 Create Fabric Connection

1. In your AI Foundry project, go to Settings → Connected resources
2. Create a connection to your Microsoft Fabric workspace
3. Ensure your Fabric capacity is running
4. Note the Connection ID (full resource path):

   /subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.CognitiveServices/accounts/<account-name>/projects/<project-name>/connections/<connection-name>
   

5. Configure the Web API Application

Update appsettings.json with your configuration values:

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning"
    }
  },
  "AllowedHosts": "*",
  "AzureAI": {
    "Endpoint": "https://<your-project>.services.ai.azure.com/api/projects/<project-name>",
    "TenantId": "<your-tenant-id>",
    "ClientId": "<web-api-client-id>",
    "ClientSecret": "<web-api-client-secret>",
    "ConnectionId": "/subscriptions/<subscription-id>/resourceGroups/<rg>/providers/Microsoft.CognitiveServices/accounts/<account>/projects/<project>/connections/<connection>"
  }
}

Configuration values:

• Endpoint: Your Azure AI Foundry project endpoint
• TenantId: Your Entra ID tenant ID
• ClientId: The Application ID of your API app registration
• ClientSecret: The client secret you created for the API app app
• ConnectionId: The full resource path to your Fabric connection

Testing the API

Step 0: Run the Application

Before testing, start the Web API application:

dotnet run

The API will start and listen on the configured port (typically http://localhost:5287). Keep this terminal running while you test the API.

Option 1: Using the HTTP File

The project includes a .http file for testing with Visual Studio or REST Client extensions.

Step 1: Get Authorization Code

1. Open the URL in a browser (replace with your values):

   https://login.microsoftonline.com/<tenant-id>/oauth2/v2.0/authorize?client_id=<client-app-id>&response_type=code&redirect_uri=https://localhost/signin-oidc&response_mode=query&scope=api://<web-api-client-id>/user_impersonation&state=12345
   

2. Sign in and consent to permissions

3. Copy the code parameter from the redirect URL

Step 2: Exchange Code for Token

Update the .http file with the authorization code:

POST https://login.microsoftonline.com/<tenant-id>/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded

client_id=<client-app-id>
&client_secret=<client-app-secret>
&grant_type=authorization_code
&code=<authorization-code-from-step-1>
&redirect_uri=https://localhost/signin-oidc
&scope=api://<web-api-client-id>/user_impersonation

Step 3: Call the Web API

POST http://localhost:5287/run-agent/
Accept: application/json
Authorization: Bearer <access-token-from-step-2>

Option 2: Using curl or Postman

Follow the same flow but use your preferred HTTP client.

How It Works

Code Flow Breakdown

1. Token Extraction: The Web API extracts the bearer token from the Authorization header

   string? originalToken = ExtractBearerToken(context);

2. On-Behalf-Of Token Exchange: Creates an OnBehalfOfCredential to exchange the user token

   var projectClient = new AIProjectClient(
       endpoint, 
       new OnBehalfOfCredential(tenantId, clientId, clientSecret, originalToken)
   );

3. Agent Creation: Creates a Persistent Agent with the Fabric Data agent tool

   MicrosoftFabricToolDefinition fabricTool = new(
       new FabricDataAgentToolParameters(connId)
   );
   
   PersistentAgent agent = await agentClient.Administration.CreateAgentAsync(
       model: "gpt-4.1",
       name: $"my-agent-{Guid.NewGuid()}",
       instructions: "You are a helpful agent.",
       tools: [fabricTool]
   );

4. Thread Creation and Execution: Creates a thread, sends a message, and runs the agent

   PersistentAgentThread thread = await agentClient.Threads.CreateThreadAsync();
   
   PersistentThreadMessage message = await agentClient.Messages.CreateMessageAsync(
       thread.Id,
       MessageRole.User,
       "What insights can you provide from the Fabric resource?"
   );
   
   ThreadRun run = await agentClient.Runs.CreateRunAsync(thread, agent);

5. Response Processing: Polls for completion and returns the agent's response

Key Concepts

On-Behalf-Of (OBO) Flow

The OBO flow allows your Web API to call downstream services (Azure AI Foundry) on behalf of the authenticated user. This maintains the security context throughout the call chain.

Benefits:

• User identity is preserved
• Fine-grained access control
• Audit trail shows actual user, not service principal

Fabric Data Agent Tool

The MicrosoftFabricToolDefinition enables your agent to query and analyze data from Microsoft Fabric workspaces. The agent can:

• Access Fabric data sources
• Run queries on behalf of the user
• Provide insights based on available data

Resources

• Azure AI Foundry Documentation
• OAuth 2.0 On-Behalf-Of Flow
• Microsoft Fabric Documentation
• Create Fabric Data agent
• Azure AI Agents SDK