Merge pull request #13393 from MicrosoftDocs/main

Auto Publish – main to live - 2026-06-04 17:30 UTC

Author: learn-build-service-prod[bot]

docs/agent-id/how-to-validate-agent-tokens-downstream-api.md

@@ -57,7 +57,7 @@ The following diagram shows how tokens flow from the agent through the sidecar t
 
 :::image type="content" source="media/how-to-validate-agent-tokens-downstream-api/agent-token-flow-to-downstream-api.png" alt-text="Diagram showing the agent caller sending a Bearer token to the weather API, which verifies the token and calls Open-Meteo." lightbox="media/how-to-validate-agent-tokens-downstream-api/agent-token-flow-to-downstream-api.png":::
 
-TR is the agent identity token issued by Microsoft Entra ID through the sidecar. It contains the claims your API validates, including the `xms_par_app_azp` agent identity marker. For a detailed breakdown of all tokens in the flow, see [Run the sidecar for local development](sidecar-local-development.md#understand-the-token-flow).
+The agent identity token, TR, is issued by Microsoft Entra ID through the sidecar. It contains the claims your API validates, including the `xms_par_app_azp` agent identity marker. For a detailed breakdown of all tokens in the flow, see [Run the sidecar for local development](sidecar-local-development.md#understand-the-token-flow).
 
 Token validation libraries differ across ecosystems (Python, Node.js, .NET). This sample uses PyJWT with the `cryptography` backend for RS256 signature verification. When you build your own downstream API, choose the equivalent JWT validation library for your technology stack.
 

docs/agent-id/integrate-aws-bedrock-agent.md

@@ -126,6 +126,8 @@ Run the following commands once per tenant to create the Blueprint app, Agent ID
    - **`AGENT_CLIENT_ID`:** The Agent ID created from the Blueprint.
 
 1. (Optional) Create the SPA app and configure OBO. This step is required only if you want to use the OBO identity flow:
+    
+   Run the following scripts to create the SPA app registration and configure OBO permissions on the Blueprint. The scripts register the SPA redirect URI and grant the required delegated permissions.
 
    **Bash:**
 
@@ -156,7 +158,7 @@ The sidecar supports multiple credential types through the `AzureAd__ClientCrede
 - **`KeyVault`:** Certificate from Azure Key Vault.
 - **`StoreWithThumbprint`:** Certificate from local machine store.
 
-1. Copy the environment template and open it in your editor:
+1.  Create a local `.env` configuration file from the included template. This file stores your tenant, app, and AWS credentials:
 
    **Bash:**
 
@@ -191,13 +193,15 @@ The sidecar supports multiple credential types through the `AzureAd__ClientCrede
 
 ## Start the stack
 
-1. Make sure Docker is running and then start all containers:
+1. Verify that Docker Desktop (or Docker Engine) is running on your machine.
+
+1. Build the container images and start all three services (agent, sidecar, and weather API) in detached mode:
 
    ```bash
    docker compose up --build -d
    ```
 
-1. Verify the stack is ready:
+1. Check that all containers started successfully by querying the status endpoint. The response reports whether the agent can reach AWS Bedrock:
 
    **Bash:**
 
@@ -245,28 +249,28 @@ If something isn't working as expected, check the following table for common iss
 | OBO sign-in popup blocked | Browser popup blocker. | Allow popups for `localhost:3001`. |
 | `4xx` from sidecar during OBO | `CLIENT_SPA_APP_ID` missing or SPA redirect URI mismatch. | Rerun `setup-obo-client-app`. Ensure `http://localhost:3001` is on the SPA's redirect URIs. |
 
-View container logs for debugging:
+If an issue persists even after following the troubleshooting steps, inspect the container logs directly. Each service logs to its own container:
 
 ```bash
-docker logs llm-agent-aws
-docker logs agent-id-sidecar-aws
-docker logs weather-api-aws
+docker logs llm-agent-aws          # Agent app: Bedrock calls, tool invocations
+docker logs agent-id-sidecar-aws   # Sidecar: token acquisition, credential errors
+docker logs weather-api-aws        # Weather API: JWT validation, request handling
 ```
-
 ## Clean up resources
 
-Stop and remove the containers when you're done:
+When you finish testing, stop the local containers to free system resources. Choose one of the following cleanup options based on whether you want to keep images for faster restarts.
+
+> [!IMPORTANT]
+> `docker compose down` removes only the local Docker containers. Microsoft Entra objects (agent blueprint, Agent ID, SPA app registration) are tenant-side state and persist. Delete them manually in the Microsoft Entra admin center if you no longer need them.
 
 ```bash
-# Stop containers but keep volumes and images
+# Stop containers but keep volumes and images for faster restarts
 docker compose down
 
 # Remove everything including volumes and images
 docker compose down -v --rmi all
 ```
 
-The Entra objects (agent blueprint, Agent ID, SPA app registration) are tenant-side state, so using `docker compose down` won't remove them. Remove them manually in the Microsoft Entra admin center if no longer needed.
-
 ## Related content
 
 - [Authentication with Microsoft Entra Auth SDK (sidecar)](authentication-with-auth-sdk-sidecar.md)

docs/agent-id/interactive-agent-authentication-authorization-flow.md

@@ -7,13 +7,14 @@ ms.author: dmwendia
 ms.topic: how-to
 ms.date: 03/17/2026
 ms.reviewer: dastrock, jomondi
+ai-usage: ai-assisted
 
 #customer-intent: As a developer building interactive agents, I want to authenticate users, configure authorization, and acquire tokens through the On-Behalf-Of flow, so that my agent can securely act on behalf of users to access protected resources.
 ---
 
 # Authenticate users and acquire tokens for interactive agents
 
-Interactive agents take actions on behalf of users. To do so securely, the agent must authenticate the user, obtain consent for the required permissions, and acquire access tokens for downstream APIs. This article walks you through implementing the end-to-end flow for your interactive agent:
+Interactive agents take actions on behalf of users. To act on behalf of users securely, the agent authenticates the user, gets consent for required permissions, and acquires access tokens for downstream APIs. This article walks you through the end-to-end authentication and token acquisition flow for your interactive agent:
 
 1. Register a redirect URI for your agent identity blueprint.
 1. Configure user or admin authorization (consent).
@@ -32,6 +33,7 @@ Before you begin, ensure you have:
 - An [agent identity](create-delete-agent-identities.md).
 - A client application registered in Microsoft Entra to handle user authentication.
 - Familiarity with the [OAuth 2.0 authorization code flow](/entra/identity-platform/v2-oauth2-auth-code-flow).
+- The ability to run an ASP.NET Core web API if you plan to use the token validation and OBO samples in this article.
 
 For admin authorization, you also need:
 
@@ -41,9 +43,9 @@ For admin authorization, you also need:
 
 To support delegated permissions, your agent identity blueprint must be configured with a valid redirect URI. This URI is where Microsoft Entra ID sends users after they grant or deny consent to your agent.
 
-### [Microsoft Graph API](#tab/microsoft-graph-api)
+### [Use Microsoft Graph API](#tab/microsoft-graph-api)
 
-To send this request, you first need to obtain an access token with the delegated permission `AgentIdentityBlueprint.ReadWrite.All`.
+To update the redirect URI on the agent identity blueprint, you first need to obtain an access token with the delegated permission `AgentIdentityBlueprint.ReadWrite.All`. Then send a PATCH request to the application object for the agent identity blueprint:
 
 ```http
 PATCH https://graph.microsoft.com/beta/applications/<agent-blueprint-id>
@@ -60,7 +62,9 @@ Authorization: Bearer <token>
 }
 ```
 
-### [Microsoft Graph PowerShell](#tab/microsoft-graph-powershell)
+### [Use Microsoft Graph PowerShell](#tab/microsoft-graph-powershell)
+
+Use Microsoft Graph PowerShell to update the redirect URI on the agent identity blueprint.
 
 ```powershell
 Connect-MgGraph -Scopes "AgentIdentityBlueprint.ReadWrite.All" -TenantId <your-test-tenant>
@@ -86,14 +90,14 @@ Invoke-MgGraphRequest -Method PATCH `
 
 ## Configure user authorization
 
-Before the agent can act on behalf of a user, the user must consent to the required permissions. This consent step doesn't return a token. Instead, it records that the user has granted the agent permission to act on their behalf. Token acquisition happens in a [later step](#authenticate-the-user-and-request-a-token).
-
-To prompt a user for consent, construct an authorization URL and redirect the user to it. The agent can present this URL in different ways, for example, as a link in a chat message.
+Before the agent can act on behalf of a user, the user must consent to the required permissions. The user consent request doesn't return a token. Instead, it records that the user granted the agent permission to act on their behalf. Token acquisition happens in [Authenticate the user and request a token](#authenticate-the-user-and-request-a-token).
 
 > [!IMPORTANT]
 > Use the **agent identity** client ID in the `client_id` parameter, not the agent identity blueprint ID.
 
-```http
+To prompt a user for consent, construct an authorization URL and redirect the user to it. The agent can present this URL in different ways, for example, as a link in a chat message.
+
+```text
 https://login.microsoftonline.com/contoso.onmicrosoft.com/oauth2/v2.0/authorize?
   client_id=<agent-identity-id>
   &response_type=none
@@ -103,37 +107,37 @@ https://login.microsoftonline.com/contoso.onmicrosoft.com/oauth2/v2.0/authorize?
   &state=xyz123
 ```
 
-When the user opens this URL, Microsoft Entra ID prompts them to sign in and grant consent to the permissions specified in the `scope` parameter. After consent is granted, the user is redirected to the specified redirect URI.
+When the user opens this URL, Microsoft Entra ID prompts them to sign in and grant consent. After consent, the user is sent back to the redirect URI.
 
-The key parameters in the consent URL are:
+The key parameters in the user consent authorization URL are:
 
 - `client_id`: The agent identity client ID (not the agent identity blueprint client ID).
-- `response_type`: Set to `none` because this request records consent only. Token acquisition uses `response_type=code` in a [separate request](#authenticate-the-user-and-request-a-token).
-- `redirect_uri`: Must match exactly what you configured in the previous step.
+- `response_type`: Set to `none` because this request records consent only. Token acquisition uses `response_type=code` in [Authenticate the user and request a token](#authenticate-the-user-and-request-a-token).
+- `redirect_uri`: Must match exactly the redirect URI configured on the agent identity blueprint.
 - `scope`: Specify the delegated permissions you need (for example, `User.Read`).
 - `state`: Optional parameter for maintaining state between the request and callback.
 
 For more information on OAuth authorization concepts, see [Permissions and consent in the Microsoft identity platform](/entra/identity-platform/permissions-consent-overview).
 
 ## Configure admin authorization
 
-Agents can also request authorization from a Microsoft Entra ID administrator, who can grant authorization to the agent for all users in their tenant. Application permissions require admin authorization because individual users can't consent to them.
+An administrator in Microsoft Entra ID can grant consent to the agent for all users in the tenant. Use admin consent when you need application permissions, because individual users can't consent to them.
 
-To grant admin consent, construct the authorization URL that prompts the administrator. Use the agent identity ID in the following request.
+To grant tenant-wide admin consent, direct an administrator to the following URL. Use the agent identity ID in the `client_id` parameter.
 
-```http
+```text
 https://login.microsoftonline.com/contoso.onmicrosoft.com/v2.0/adminconsent
 ?client_id=<agent-identity-id>
 &scope=User.Read
 &redirect_uri=https://entra.microsoft.com/TokenAuthorize
 &state=xyz123
 ```
 
-After the administrator grants consent, the permissions are applied tenant-wide and users in that tenant don't need to individually consent to those permissions.
+After the administrator grants consent, the permissions apply to the whole tenant. Users don't need to consent again.
 
 ## Authenticate the user and request a token
 
-After authorization is configured, the client app (such as a frontend or mobile app) initiates an OAuth 2.0 authorization code request to obtain a token where the audience is the agent identity blueprint. In this step, `client_id` refers to the client app's own registered application ID, not the agent identity or agent identity blueprint ID.
+After authorization is configured, the client app (such as a frontend or mobile app) starts an OAuth 2.0 authorization code request. The token audience is the agent identity blueprint. In the authorization code request, `client_id` refers to the client app's own registered application ID, not the agent identity or agent identity blueprint ID.
 
 1. Redirect the user to the Microsoft Entra ID authorization endpoint with the following parameters:
 
@@ -146,7 +150,7 @@ After authorization is configured, the client app (such as a frontend or mobile
     &state=abc123
     ```
 
-1. After the user signs in, your app receives an authorization code at the redirect URI. Exchange it for an access token:
+1. After the user signs in, your app receives an authorization code at the redirect URI. Exchange the authorization code for an access token:
 
     ```http
     POST https://login.microsoftonline.com/<my-test-tenant>/oauth2/v2.0/token
@@ -166,7 +170,7 @@ After authorization is configured, the client app (such as a frontend or mobile
 
 ## Validate the access token
 
-The agent, typically exposed via a web API, must validate the access token. Always use an approved library to perform token validation. Never implement your own token validation code.
+The web API must validate the incoming access token before the agent can act. Always use an approved library to validate tokens. Don't write your own token validation code.
 
 1. Install the `Microsoft.Identity.Web` NuGet package:
 
@@ -214,7 +218,7 @@ For more information about Microsoft.Identity.Web, see [Microsoft.Identity.Web d
 
 ## Validate user claims
 
-After you validate the access token, the agent can identify the user and perform authorization checks. This example API route extracts user claims from the access token and returns them in the API response:
+After access token validation, the agent can identify the user and perform authorization checks. The following example API route extracts user claims from the access token and returns them in the API response:
 
 ```csharp
 app.MapGet("/hello-agent", (HttpContext httpContext) =>
@@ -238,7 +242,7 @@ After an interactive agent validates the user's token, it can request access tok
 - Exchange it for a new access token for a downstream API like Microsoft Graph.
 - Use that new token to access protected resources on behalf of the original user.
 
-### [Microsoft Identity Web](#tab/identity-web-tokens)
+### [Use Microsoft Identity Web](#tab/identity-web-tokens)
 
 The `Microsoft.Identity.Web` library simplifies the OBO implementation by handling token exchange automatically, so you don't have to manually implement the flow by following the protocol.
 
@@ -274,7 +278,7 @@ The `Microsoft.Identity.Web` library simplifies the OBO implementation by handli
     app.Run();
     ```
 
-1. In the agent API, exchange the incoming access token for a new access token for the agent identity. `Microsoft.Identity.Web` validates the incoming access token and handles the on-behalf-of token exchange:
+1. In the agent API, exchange the incoming user access token for a new access token for the agent identity. `Microsoft.Identity.Web` validates the incoming access token and handles the on-behalf-of token exchange:
 
     ```csharp
     app.MapGet("/agent-obo-user", async (HttpContext httpContext) =>
@@ -291,7 +295,7 @@ The `Microsoft.Identity.Web` library simplifies the OBO implementation by handli
     .RequireAuthorization();
     ```
 
-### [Microsoft Graph SDK](#tab/graph-sdk-tokens)
+### [Use Microsoft Graph SDK](#tab/graph-sdk-tokens)
 
 If you're using the Microsoft Graph SDK, you can authenticate to Microsoft Graph using the `GraphServiceClient`.
 
@@ -351,6 +355,8 @@ Under the hood, the OBO flow involves two token exchanges: first, the agent iden
 
 ## Related content
 
+Learn more about agent tokens and related APIs:
+
 - [Token claims reference](agent-token-claims.md)
 - [On-behalf-of flow in agents](agent-on-behalf-of-oauth-flow.md)
 - [Call Microsoft Graph API](call-api-microsoft-graph.md)

docs/id-governance/entitlement-management-access-package-assignments.md

@@ -113,7 +113,7 @@ In some cases, you might want to directly assign specific identities to an acces
 > [!NOTE]
 > Access package assignment managers will no longer be able to bypass approval settings if the policy requires approval. This means identities can't be directly assigned to the package without necessary approval(s) from the designated approver(s). In the case that you need to bypass approval, we recommend creating a second policy on the access package that does not require approval and is scoped only to identities who need access.
 
-## Directly assign any identity (Preview)
+## Directly assign any identity
 
 Entitlement management also allows you to directly assign external identities to an access package to make collaborating with partners easier. To do this, the access package must have a policy that allows identities not yet in your directory to request access.
 
@@ -130,7 +130,7 @@ Entitlement management also allows you to directly assign external identities to
 
 1. In the **Select policy** list, select a policy that allows that is set to **For users not in your directory**
 
-1. Select **External user (Preview)**. You're able to specify which users you want to assign to this access package.
+1. Select **External user**. You're able to specify which users you want to assign to this access package.
     ![Assignments - Add any user to access package](./media/entitlement-management-access-package-assignments/assignments-add-any-user.png)
 
 1. Enter the identity **Name** (optional) and the identity **Email address** (required).