Note
Access to this page requires authorization. You can try signing in or changing directories.
Access to this page requires authorization. You can try changing directories.
Call your custom API with the signed-in user's access, rather than the agent's application permissions. This article uses the OAuth On-Behalf-Of (OBO) flow: a client signs in the user, calls your agent, and the agent gets a token for the downstream API.
You'll extend the agent API from the authentication walkthrough and test the complete call with the same client. You can use an existing protected API or the local test API below. The agent doesn't start another interactive sign-in.
Prerequisites
- Complete Authenticate users to an ASP.NET Core agent API.
- A credential on the agent identity blueprint. For local testing, use the certificate registered during provisioning and the local certificate configuration. For production, configure a managed identity federated credential.
- An existing custom API's delegated scope, HTTPS endpoint, and user authorization requirements, or permission to set up the local test API.
- The management client and consent permissions from the authentication walkthrough, to grant the test user's downstream access.
- An app role assigned to the user if the agent uses app roles to control access.
The authentication walkthrough establishes client-to-agent consent. You also need agent-to-API consent; one grant doesn't replace the other.
Prepare a downstream API
For an existing API, ask its owner for the application (client) ID, enterprise application object ID, fully qualified delegated scope, HTTPS endpoint, and test user's access requirements. Skip the local API steps only when that API is ready to validate and authorize delegated requests.
To create an isolated local API:
Register a single-tenant application named Agent downstream test API.
Expose a delegated permission with application ID URI
api://<custom-api-client-id>and scope valueread_data. Record the scope's GUID. In the app manifest, setapi.requestedAccessTokenVersionto2.Record the corresponding enterprise application's Object ID for consent. Don't use its client ID in place of this object ID.
Create a web API project in a separate directory:
dotnet new webapi --framework net10.0 --name DownstreamApi cd DownstreamApi dotnet add package Microsoft.Identity.Web --version 4.17.0Configure
AzureAdin this project'sappsettings.jsonwithInstanceset tohttps://login.microsoftonline.com/, yourTenantId, andClientIdset to the downstream API's client ID. This resource API validates tokens and doesn't need a client credential.Replace this project's
Program.cswith:using Microsoft.Identity.Web; using Microsoft.Identity.Web.Resource; var builder = WebApplication.CreateBuilder(args); builder.Services.AddMicrosoftIdentityWebApiAuthentication(builder.Configuration); builder.Services.AddAuthorization(); var app = builder.Build(); app.UseAuthentication(); app.UseAuthorization(); app.MapGet("/user-data", (HttpContext context) => { context.VerifyUserHasAnyAcceptedScope("read_data"); return Results.Ok(new { objectId = context.User.GetObjectId(), tenantId = context.User.GetTenantId() }); }).RequireAuthorization(); app.Run();Run
dotnet run --urls https://localhost:5002and leave this terminal open. Use the trusted development certificate from the authentication walkthrough.
The test endpoint returns only the authenticated caller's identity. For real data, enforce the user's access to each requested resource as well as the delegated scope. A scope alone doesn't authorize access to another user's records.
Grant downstream access
Declare the API's delegated scope on the blueprint using Declare the API permissions. Use the downstream API's client ID for resourceAppId and its scope GUID with "type": "Scope". A declaration isn't consent.
Through the authorized management client, check for an existing grant:
GET https://graph.microsoft.com/v1.0/oauth2PermissionGrants?$filter=clientId eq '<agent-identity-object-id>' and resourceId eq '<custom-api-service-principal-object-id>'
Follow pagination. If an applicable grant already includes the scope, reuse it. If a grant for this user lacks the scope, update the OAuth2 permission grant with the union of existing and required scopes. Otherwise, grant access for the same user who signs in through the test client:
POST https://graph.microsoft.com/v1.0/oauth2PermissionGrants
Content-Type: application/json
{
"clientId": "<agent-identity-object-id>",
"resourceId": "<custom-api-service-principal-object-id>",
"consentType": "Principal",
"principalId": "<user-object-id>",
"scope": "read_data"
}
Expect 201 Created and save the grant's id for cleanup. For an existing API, replace read_data with its scope value, without the api:// prefix. For other consent options, see Grant delegated permissions to an agent identity.
Configure the blueprint credential
Keep the agent API's existing AzureAd settings from the authentication walkthrough. Add the credential for where you run the API.
Follow Configure a local development credential to add the registered certificate in appsettings.Development.json and supply its password through the environment.
Keep the tenant ID and agent client ID from the authentication walkthrough. Don't use the downstream API's client ID for the agent, and don't add a managed identity credential to the local configuration.
Warning
Client secrets shouldn't be used as client credentials in production environments for agent identity blueprints due to security risks. Instead, use more secure authentication methods such as federated identity credentials (FIC) with managed identities or client certificates. These methods provide enhanced security by eliminating the need to store sensitive secrets directly within your application configuration.
Configure token validation and OBO
Replace the agent API's Program.cs from the authentication walkthrough with the following code and the endpoint in Call the API, in that order. Don't append a second application builder or a second app.Run(). This version adds token acquisition and uses an in-memory token cache for the local test.
using System.Net.Http.Headers;
using Microsoft.Identity.Abstractions;
using Microsoft.Identity.Web;
using Microsoft.Identity.Web.Resource;
var builder = WebApplication.CreateBuilder(args);
builder.Services
.AddMicrosoftIdentityWebApiAuthentication(builder.Configuration)
.EnableTokenAcquisitionToCallDownstreamApi()
.AddInMemoryTokenCaches();
builder.Services.AddHttpClient();
builder.Services.AddAuthorization();
var app = builder.Build();
app.UseAuthentication();
app.UseAuthorization();
app.MapGet("/whoami", (HttpContext context) =>
{
context.VerifyUserHasAnyAcceptedScope("access_agent");
return Results.Ok(new
{
objectId = context.User.GetObjectId(),
tenantId = context.User.GetTenantId()
});
}).RequireAuthorization();
Call the API
Use CreateAuthorizationHeaderForUserAsync with the authenticated HttpContext.User. Microsoft.Identity.Web uses the validated incoming access token as the OBO assertion and authenticates with the configured shared client ID and blueprint credential.
Append this endpoint after the /whoami mapping in the previous block. Keep /whoami so you can compare the inbound and downstream identities. Replace the client ID, scope value, and URL with your API's values. For the local test API, use read_data and https://localhost:5002/user-data.
app.MapGet("/custom-api-for-user", async (
HttpContext context,
IAuthorizationHeaderProvider authorizationHeaderProvider,
IHttpClientFactory httpClientFactory) =>
{
context.VerifyUserHasAnyAcceptedScope("access_agent");
string authorizationHeader = await authorizationHeaderProvider
.CreateAuthorizationHeaderForUserAsync(
["api://<custom-api-client-id>/<delegated-scope>"],
claimsPrincipal: context.User);
HttpClient client = httpClientFactory.CreateClient();
client.DefaultRequestHeaders.Authorization =
AuthenticationHeaderValue.Parse(authorizationHeader);
using HttpResponseMessage response =
await client.GetAsync("https://api.contoso.com/user-data");
response.EnsureSuccessStatusCode();
return Results.Content(
await response.Content.ReadAsStringAsync(),
response.Content.Headers.ContentType?.ToString());
})
.RequireAuthorization();
app.Run();
The returned authorization header includes the Bearer scheme. Send it only to the intended custom API, and don't return or log it.
The custom API must validate the token and enforce both the delegated scope and resource-level access for the user. For protocol details, see OAuth protocols in Microsoft Entra Agent ID and the OAuth 2.0 On-Behalf-Of flow.
Verify delegated access
- If the downstream API isn't already running, start it at
https://localhost:5002. Leave it running while you start the agent API in its own terminal withdotnet run --urls https://localhost:5001. - In the test client, change only the request URL from
https://localhost:5001/whoamitohttps://localhost:5001/custom-api-for-user. Keep the requested scope asapi://<agent-client-id>/access_agent, not the downstream scope. - Run the test client and sign in as the user in both consent grants. Expect
HTTP 200. For the local API, the response must contain the same user and tenant IDs returned by/whoami. - Call the agent endpoint without a bearer token. Expect
401. A token issued for the agent must also be rejected if sent directly to the downstream API because its audience is wrong. - For an existing API, test a resource the signed-in user isn't allowed to access. The local identity-only endpoint doesn't expose another user's records, so this resource-level test doesn't apply to it.
If either API exposes another delegated scope, you can also run a scope-negative test against it. For a direct call from the test client, declare and grant that client the alternate scope on the target API. Request only that scope, then send the resulting token directly to that API's endpoint and confirm rejection. The token must have the target API's audience but lack the endpoint's required scope. If you instead test a downstream token acquired through OBO, the alternate downstream grant belongs to the agent identity, not the upstream test client. The minimal local setup doesn't define alternate scopes, so these tests are optional. Don't treat the wrong-audience test as a substitute.
If OBO reports missing consent, check front-end access to the agent separately from the agent's downstream permission. OBO can't display an interactive consent prompt. Record correlation IDs for failures, not tokens or assertions.
Clean up the local test
Stop the three projects. Through the management client, delete test-only grants with DELETE https://graph.microsoft.com/v1.0/oauth2PermissionGrants/<grant-id> before deleting their client or resource registrations. Delete the test client's and downstream API's app registrations only if you created them for this test. For a test-only agent, follow Delete agent identity objects. Don't delete shared registrations, scopes, or grants.