Azure AI Gateway Labs
Documentation Open portal
MCP & tools · Lab 33Emerging

Connect Microsoft 365 Copilot to MCP tools as the signed-in user

Let Microsoft 365 Copilot and Copilot Cowork call your MCP tools through Azure AI Gateway as the signed-in user. The gateway checks the user's role, then exchanges the user's token with Microsoft Entra ID on-behalf-of, so the backend sees the user and no secret leaves the gateway.

Advanced 1 h PortalCLIBicepTerraform Updated
Source Edit

What you'll do

  • Explain each token and app registration of the on-behalf-of chain from Microsoft 365 Copilot to an MCP backend
  • Deploy an Entra-protected MCP server on Azure Container Apps that accepts only tokens exchanged by the gateway
  • Register an MCP server with an on-behalf-of backend in the Azure CLI, with Bicep and azd, or with Terraform, and validate it in the AI Gateway portal
  • Prove that the backend sees the signed-in user, and that a token for the gateway doesn't work on the backend
  • Connect the MCP server to Microsoft 365 Copilot and call its tools as yourself in Copilot Cowork

Before you start

Tracks: Portal, Azure CLI, Bicep + azd, Terraform

An agent that acts for a person should reach your systems as that person, not as a shared service account. Your API then applies its own permissions to each user, and its logs show who asked. In this lab, Microsoft 365 Copilot and Copilot Cowork call MCP tools through Azure AI Gateway as the signed-in user. The gateway checks the user's role on the MCP server, then exchanges the user's token with Microsoft Entra ID on behalf of the user for a token that only your backend accepts. The gateway signs in with a managed identity, so no secret leaves it.

Note

This lab adapts ai-gateway-end-to-end by Kosta Petan. His repository has the Bicep templates, a Terraform branch, an architecture walkthrough with diagrams of each token, and the dummy-mcp server that this lab's MCP server is based on. Thanks, Kosta!

Before you begin

One-time setupThe Setup guide tasks that this lab uses. Mark each one done once, and the labs stop listing it.

Tip

On the Bicep + azd and Terraform tracks, azd up or terraform apply creates its own gateway, the backend, the app registrations, and the MCP server, so you can skip the variables below. You still need the permissions in this list.

  • Complete Federate MCP tools behind one endpoint and Go keyless with Microsoft Entra ID and RBAC. This lab adds an MCP server to your gateway and calls it with a Microsoft Entra token.
  • Permission to register applications in Microsoft Entra ID, and to grant tenant-wide consent to them, for example the Cloud Application Administrator role. The lab registers three apps and consents to their delegated scopes for everyone in the tenant.
  • Owner or User Access Administrator on the subscription. The lab assigns roles on the container registry and on the MCP server.
  • Permission to read, update, and retrieve the secrets of MCP servers on the gateway, for example Contributor on it. The first on-behalf-of setup retrieves secrets even when the backend stores none.
  • For the portal's Validate button, admin consent for the AI Gateway portal to read app registrations with the Microsoft Graph Application.Read.All permission. The portal asks for it with Authorize directory access.
  • A recent Bicep CLI, which az bicep upgrade installs. The templates register the apps with the Microsoft Graph Bicep extension.
  • jq, for the Bash commands.
  • For the Microsoft 365 steps, an admin who can add connectors in the Microsoft 365 admin center, and a user with a Microsoft 365 Copilot license and access to Copilot Cowork. Both must be in the Microsoft Entra tenant of your gateway's subscription.
  • Run the scripts from the lab's folder, ~/aigateway/labs/33-copilot-obo-mcp.
Note

On-behalf-of backends are an emerging capability of Azure AI Gateway. Labels and behavior can change; see the release note.

Set these variables once. The steps and the Verify section reuse them.

# Set your resource group and gateway, and the MCP server that you create in this lab
export RG="<resource-group>"
export GATEWAY="<gateway>"
export MCP_SERVER="obo-demo"                 # the MCP server you create in this lab
echo "📝 Gateway $GATEWAY in $RG, MCP server $MCP_SERVER"

# Read the gateway's resource ID and its runtime URL
export GATEWAY_ID="$(az aigateway show -g "$RG" -n "$GATEWAY" --query id -o tsv)"
export AI_GATEWAY_URL="https://$(az aigateway show -g "$RG" -n "$GATEWAY" --query properties.frontend.defaultHostname -o tsv)"
echo "🆔 Gateway ID: $GATEWAY_ID"
echo "🌐 Runtime URL: $AI_GATEWAY_URL"

This lab uses no API key: every call carries a Microsoft Entra token for the signed-in user.

How it works

An MCP backend with on-behalf-of authentication receives a token for the user who called the gateway, not for the gateway. The chain has three app registrations and one managed identity, which the lab names after a base name such as aigw-lab33-k3v7qz:

PieceWhat it isIts job
Connector app, <base>-copilot-connectorAn app registration with a client secretMicrosoft 365 Copilot signs the user in with it and gets a token for AI Gateway with the Data.All scope
Token exchange app, <base>-token-exchangeAn app registration with no secret, whose federated credential trusts the gateway identityThe gateway signs in as this app to exchange the user's token
Backend app, <base>-mcp-backendAn app registration that exposes the user_impersonation scopeThe audience of the token that the MCP server accepts
Gateway identity, id-<base>-gatewayA user-assigned managed identity on the gatewayProves to Microsoft Entra ID that the gateway is the token exchange app
MCP server, ca-<base>-mcpA Python MCP server on Azure Container Apps, behind Container Apps authenticationRuns the tools for the user in the token

A tool call goes through four tokens. You never handle any of them after the first:

#TokenAudienceScopeChecked by
1The user's token, which Microsoft 365 Copilot gets with the connector appAI GatewayData.AllAI Gateway, then the AI Gateway Tools User role on the MCP server
2A federation token, which AI Gateway gets on behalf of the userThe token exchange appFederationApp.AccessMicrosoft Entra ID: the token exchange app pre-authorizes AI Gateway for this scope
3An assertion from the gateway identityapi://AzureADTokenExchangeMicrosoft Entra ID: the federated credential on the token exchange app
4The backend token, which the token exchange app gets on behalf of the user, with the assertion as its credentialThe backend app's client IDuser_impersonationContainer Apps authentication, then the MCP server

Each token keeps the user's object ID (oid), so the backend sees the same person that signed in to Copilot. The gateway grants nothing by itself: the user needs the AI Gateway Tools User role on the MCP server, and the tenant-wide consent of the token exchange app to the backend's scope. Owner and Contributor don't include the Tools User role.

Review the MCP server

The MCP server is one Python file, infra/mcp-server/server.py, built with FastMCP. Its three read-only tools show who called them:

ToolReturns
whoamiThe claims of the token that the backend received: the user's name and object ID, the audience, the calling app, the scopes, and the token version
echo<your name> said: <message>
get_server_timeThe server's time in UTC

The token passes two checks before a tool runs:

CheckRuleResult when it fails
Container Apps authenticationA valid Microsoft Entra v2.0 token for the backend app, requested by the token exchange app. Only /healthz is openHTTP 401 before the container sees the call
server.pyThe same issuer, audience, and signature; the user_impersonation scope; and the calling app (azp) in ALLOWED_CLIENT_IDSHTTP 401, and a warning in the log
infra/mcp-server/server.pyGitHub
"""Demo MCP server that only answers calls made through Azure AI Gateway as the signed-in user.

Adapted for the Azure AI Gateway labs from https://github.com/kostapetan/ai-gateway-end-to-end by Kosta Petan.

The server accepts a Microsoft Entra ID v2 access token only when:
  * the tenant issued it (iss),
  * it was issued for this backend's app registration (aud is the backend's client ID),
  * it carries the backend's delegated scope (scp), and
  * the token exchange app requested it (azp), which is what the gateway uses for the on-behalf-of exchange.

So the tools are reachable only along one path: MCP client -> Azure AI Gateway -> on-behalf-of exchange -> here.
"""

from __future__ import annotations

import logging
import os
from datetime import datetime, timezone
from typing import Any

import uvicorn
from fastmcp import FastMCP
from fastmcp.server.auth.providers.jwt import JWTVerifier
from fastmcp.server.dependencies import get_access_token
from starlette.requests import Request
from starlette.responses import JSONResponse

logging.basicConfig(level=os.getenv("LOG_LEVEL", "INFO"))
log = logging.getLogger("obo-demo")

TENANT_ID = os.environ["AZURE_TENANT_ID"]
BACKEND_CLIENT_ID = os.environ["BACKEND_CLIENT_ID"]
REQUIRED_SCOPE = os.getenv("REQUIRED_SCOPE", "user_impersonation")
ALLOWED_CLIENT_IDS = {c.strip().lower() for c in os.getenv("ALLOWED_CLIENT_IDS", "").split(",") if c.strip()}
AUTHORITY = f"https://login.microsoftonline.com/{TENANT_ID}"


class OnBehalfOfVerifier(JWTVerifier):
    """Validates the token's signature, issuer, audience, and scope, then checks which app requested it."""

    async def verify_token(self, token: str):  # type: ignore[override]
        access_token = await super().verify_token(token)
        if access_token is None:
            return None
        claims = access_token.claims
        client_app = str(claims.get("azp", "")).lower()
        if ALLOWED_CLIENT_IDS and client_app not in ALLOWED_CLIENT_IDS:
            log.warning("Rejected a token that app %s requested: only the token exchange app may call", client_app)
            return None
        log.info("Call from user %s through app %s with scope %s", claims.get("oid"), client_app, claims.get("scp"))
        return access_token


mcp = FastMCP(
    name="obo-demo",
    instructions="Demo tools behind Azure AI Gateway. Call whoami to see the user that the gateway signed in as.",
    auth=OnBehalfOfVerifier(
        jwks_uri=f"{AUTHORITY}/discovery/v2.0/keys",
        issuer=f"{AUTHORITY}/v2.0",
        # A v2 access token's audience is the backend's client ID, not its api:// URI.
        audience=BACKEND_CLIENT_ID,
        required_scopes=[REQUIRED_SCOPE],
    ),
)

READ_ONLY = {"readOnlyHint": True, "openWorldHint": False}


@mcp.tool(annotations=READ_ONLY)
def whoami() -> dict[str, Any]:
    """Return who the backend sees as the caller, read from the access token that the gateway sent."""
    token = get_access_token()
    claims = token.claims if token else {}
    expires = claims.get("exp")
    return {
        "name": claims.get("name"),
        "username": claims.get("preferred_username") or claims.get("upn"),
        "object_id": claims.get("oid"),
        "tenant_id": claims.get("tid"),
        "audience": claims.get("aud"),
        "client_app_id": claims.get("azp"),
        "scopes": claims.get("scp"),
        "issuer": claims.get("iss"),
        "token_version": claims.get("ver"),
        "expires_utc": datetime.fromtimestamp(int(expires), tz=timezone.utc).isoformat() if expires else None,
    }


@mcp.tool(annotations=READ_ONLY)
def echo(message: str) -> str:
    """Return the message, prefixed with the caller's display name."""
    token = get_access_token()
    name = (token.claims.get("name") if token else None) or "Someone"
    return f"{name} said: {message}"


@mcp.tool(annotations=READ_ONLY)
def get_server_time() -> str:
    """Return the backend's current time in UTC (ISO 8601)."""
    return datetime.now(timezone.utc).isoformat()


@mcp.custom_route("/healthz", methods=["GET"])
async def healthz(_: Request) -> JSONResponse:
    return JSONResponse({"status": "ok"})


# Stateless JSON responses: no session affinity behind the gateway, and the app can scale out.
app = mcp.http_app(path="/mcp", stateless_http=True, json_response=True)

if __name__ == "__main__":
    uvicorn.run(app, host="0.0.0.0", port=int(os.getenv("PORT", "8000")), proxy_headers=True, forwarded_allow_ips="*")

On GitHub, open infra/mcp-server/server.py.

A v2.0 access token's audience is the backend app's client ID, not its api:// URI, so the server compares aud with BACKEND_CLIENT_ID. Each call logs Call from user <object ID> through app <client ID> with scope user_impersonation, which Verify reads.

Deploy the backend and register the MCP server

The AI Gateway portal doesn't create app registrations or container apps, so on the Portal track, follow the Azure CLI steps here, then check the on-behalf-of settings in the portal.

Choose your track
1

Deploy the backend

infra/backend.bicep creates the two managed identities, the three app registrations, and the MCP server on Azure Container Apps. An ACR Tasks run builds the server's image from this repository on GitHub, so you don't need Docker. It takes about four minutes.

# Move into the lab's folder, which holds the templates and the scripts
cd ~/aigateway/labs/33-copilot-obo-mcp &&
  echo "📂 Lab folder: $(pwd)"

# Name the backend's resource group, in the gateway's region
export BACKEND_RG="rg-aigw-lab33-backend"
export LOCATION="$(az aigateway show -g "$RG" -n "$GATEWAY" --query location -o tsv)"
echo "📝 Backend in $BACKEND_RG, in $LOCATION"

# Create the resource group
az group create -n "$BACKEND_RG" -l "$LOCATION" -o none &&
  echo "📦 Resource group $BACKEND_RG is ready in $LOCATION"

# Deploy the identities, the app registrations, and the MCP server
az deployment group create -g "$BACKEND_RG" -n lab33-backend -f infra/backend.bicep -o none &&
  echo "🚀 The backend is deployed to $BACKEND_RG"
2

Read the outputs

Read the IDs that the next steps need from the deployment's outputs, then call the backend without a token.

# Read the deployment's outputs
OUTPUTS="$(az deployment group show -g "$BACKEND_RG" -n lab33-backend --query properties.outputs -o json)"
export IDENTITY_ID="$(echo "$OUTPUTS" | jq -r .gatewayIdentityId.value)"
export IDENTITY_CLIENT_ID="$(echo "$OUTPUTS" | jq -r .gatewayIdentityClientId.value)"
export BACKEND_APP_ID="$(echo "$OUTPUTS" | jq -r .backendAppId.value)"
export BACKEND_SCOPE="$(echo "$OUTPUTS" | jq -r .backendScope.value)"
export TOKEN_EXCHANGE_APP_ID="$(echo "$OUTPUTS" | jq -r .tokenExchangeAppId.value)"
export CONNECTOR_APP_ID="$(echo "$OUTPUTS" | jq -r .connectorAppId.value)"
export BACKEND_URL="$(echo "$OUTPUTS" | jq -r .backendUrl.value)"
echo "🔐 Backend scope: $BACKEND_SCOPE"
echo "🌐 Backend URL: $BACKEND_URL"

# Call the backend without a token: Container Apps authentication answers 401 before the server runs
echo "🔐 Anonymous call to the backend: HTTP $(curl -s -o /dev/null -w '%{http_code}' -X POST "$BACKEND_URL" -H 'Content-Type: application/json' -d '{}')"

# Call the health probe, the only path open without a token
echo "✅ Health probe: HTTP $(curl -s -o /dev/null -w '%{http_code}' "${BACKEND_URL%/mcp}/healthz")"
Checkpoint

The backend scope looks like api://<backend app ID>/user_impersonation, the backend URL ends with .azurecontainerapps.io/mcp, the anonymous call prints HTTP 401, and the health probe prints HTTP 200.

3

Attach the gateway identity

The gateway signs in as the token exchange app with the user-assigned identity, so attach it to the gateway. The gateway keeps its system-assigned identity.

# Attach the user-assigned identity to the gateway
az aigateway identity assign -g "$RG" -n "$GATEWAY" --user-assigned "$IDENTITY_ID" -o none &&
  echo "👤 The gateway identity is attached to $GATEWAY"
4

Register the MCP server

Create the obo-demo MCP server with one backend. Its oauth2 authentication uses the tokenExchange grant with the entraOnBehalfOf profile: the gateway signs in as the token exchange app with the identity's client ID, and asks for the backend's scope. The az aigateway mcp create command has no dedicated flags for these settings, so pass the whole backend as JSON with --endpoints.

# Describe the backend: the MCP server's URL, and the on-behalf-of token exchange that calls it as the user
ENDPOINTS="$(jq -nc --arg url "$BACKEND_URL" --arg app "$TOKEN_EXCHANGE_APP_ID" \
  --arg identity "$IDENTITY_CLIENT_ID" --arg scope "$BACKEND_SCOPE" '[{
    kind: "mcp", namespace: "demo", required: true,
    mcp: {url: $url, transport: "streamableHttp"},
    authentication: {oauth2: {grantType: "tokenExchange", tokenExchange: {
      profile: "entraOnBehalfOf",
      federatedClientApplication: {applicationId: $app,
        appCredential: {type: "userAssignedManagedIdentity", clientId: $identity}},
      scopes: [$scope]}}}}]')"

# Register the MCP server with the MCP versions that the backend supports
az aigateway mcp create -g "$RG" --gateway-name "$GATEWAY" -n "$MCP_SERVER" --display-name "OBO demo" \
  --description "Demo MCP server on Azure Container Apps, called as the signed-in user with Microsoft Entra ID on-behalf-of." \
  --versions 2025-11-25 2025-06-18 2025-03-26 --endpoints "$ENDPOINTS" \
  --query "{name:name,mcpEndpoint:properties.gatewayEndpoints[0].url}" &&
  echo "🔌 MCP server $MCP_SERVER is ready"

The display name must be unique on the gateway: a second server named OBO demo fails with a 502.

5

Grant yourself the Tools User role

The gateway lets a user call the server's tools only with the AI Gateway Tools User role on it. Assign it to yourself. It can take several minutes to apply.

# Assign AI Gateway Tools User (dce03f8d-…) on the MCP server to yourself
az role assignment create --assignee-object-id "$(az ad signed-in-user show --query id -o tsv)" \
  --assignee-principal-type User --role "dce03f8d-857f-4e40-a90d-67770fa6ecd2" \
  --scope "$GATEWAY_ID/workspaces/default/toolServers/$MCP_SERVER" --output none &&
  echo "🔐 You have the AI Gateway Tools User role on the $MCP_SERVER MCP server"
Checkpoint

az aigateway mcp create printed the server's name and an mcpEndpoint that ends with /default/toolservers/obo-demo/mcp, and the role assignment printed its 🔐 line.

Check the on-behalf-of settings

Check that the gateway has both identities, and that the backend of the MCP server exchanges the user's token.

Choose your track
1

Open the MCP server

Open the AI Gateway portal and select your gateway from the gateway switcher. Select MCP serversOBO demo. The Overview tab lists the supported MCP versions 2025-11-25, 2025-06-18, 2025-03-26, and one backend of type MCP with the authentication OAuth 2.0 (on behalf of) and the namespace demo.

The Backends table shows how the gateway authenticates to each backend. Test in catalog opens the server in the catalog.
2

Validate the backend

  1. In the Backends table, on the backend's row, select More actions (⋯) › Edit. The Edit MCP backend panel shows Authentication OAuth 2.0 with the OAuth profile On behalf of, and the values that you deployed:

    FieldValue
    Token exchange application (client) IDThe token exchange app's client ID
    Managed identity for token exchangeid-<base>-gateway
    Backend API scope to requestapi://<backend app ID>/user_impersonation
    Namespacedemo
  2. Select Validate. If the portal asks, approve Authorize directory access, which lets it read your app registrations. The portal checks the token exchange app, its federated credential, and its consent to the backend's scope, then shows Directory checks successful. Runtime verification pending.

    Validate checks the directory. The first successful call with a user's token verifies the runtime flow.
  3. Select Cancel, so that you don't change the server.

The portal asks for full scopes, such as api://<backend app ID>/user_impersonation: one to ten scopes for the same resource, one per line. It rejects .default.

Call the tools as yourself

Before you connect Copilot, call the tools as yourself, first in the portal's catalog, then with a script that checks each link of the chain. If a call fails with 403, wait a few minutes for your role assignment to apply.

1

Test in the catalog

  1. In the AI Gateway portal, on the OBO demo server's Overview tab, select Test in catalog.
  2. Keep the method Microsoft Entra ID and the MCP version 2025-11-25, then select Connect. The panel lists the tools Echo, Get server time, and Whoami.
  3. Select WhoamiRun. The Output shows Success with your name and username, the scope user_impersonation, and the token version 2.0.
The backend saw you. A successful call verifies the runtime flow for your user, which listing the tools alone doesn't.
2

Run the test script

infra/call-obo-tool.sh (PowerShell 7: infra/call-obo-tool.ps1) calls the MCP server as the signed-in Azure CLI user. It gets a token for AI Gateway with az account get-access-token --scope https://ai.gateway.azure.com/Data.All, calls demo_whoami, and compares the user and audience that the backend saw with your token. Then it sends your token for the gateway straight to the backend. It never prints a token.

# Make the test script executable
chmod +x infra/call-obo-tool.sh &&
  echo "📄 infra/call-obo-tool.sh is executable"

# Call the MCP server as yourself, and check each link of the on-behalf-of chain
./infra/call-obo-tool.sh "$MCP_SERVER"
Checkpoint

demo_whoami returns your object ID, the backend app as the audience, and the token exchange app as the calling app. Your token for the gateway gets 401 on the backend.

Connect Microsoft 365 Copilot

Microsoft 365 Copilot reaches MCP servers through connectors. The connector signs each user in with OAuth 2.0 and the connector app, gets a token for AI Gateway, and sends it to the MCP endpoint. Register the OAuth client in the Teams Developer Portal, then add the connector in the Microsoft 365 admin center.

1

Create the connector's client secret

The connector app needs a client secret, which neither Bicep nor this lab's Terraform configuration creates, so that it never lands in a template or a state file. Create one that expires in seven days, and print the other values that the registration asks for.

# Read your tenant ID: the connector's sign-in endpoints use it
export TENANT_ID="$(az account show --query tenantId -o tsv)"
echo "🆔 Tenant ID: $TENANT_ID"

# Give the connector app a client secret that expires in 7 days, and keep it only in this shell
CONNECTOR_SECRET="$(az ad app credential reset --id "$CONNECTOR_APP_ID" --append --display-name "Microsoft 365 Copilot connector" --only-show-errors \
  --end-date "$(date -u -d '+7 days' +%F 2>/dev/null || date -u -v+7d +%F)" --query password -o tsv)"
echo "🔑 Client secret: in CONNECTOR_SECRET (${#CONNECTOR_SECRET} characters, not shown), expires in 7 days"

# Print the values of the OAuth client registration
echo "🔌 Base URL: $AI_GATEWAY_URL/default/toolservers/$MCP_SERVER/mcp"
echo "🆔 Client ID: $CONNECTOR_APP_ID"
echo "🌐 Authorization endpoint: https://login.microsoftonline.com/$TENANT_ID/oauth2/v2.0/authorize"
echo "🌐 Token and refresh endpoint: https://login.microsoftonline.com/$TENANT_ID/oauth2/v2.0/token"
2

Register the OAuth client

  1. Open the Teams Developer Portal and sign in as an admin of your tenant.

  2. Select ToolsOAuth client registrationRegister client, and fill in the form:

    FieldValue
    Registration nameAI Gateway OBO demo
    Base URLThe 🔌 Base URL that the previous step printed: your MCP endpoint
    Restrict usage by organizationMy organization only
    Restrict usage by Teams appAny Teams app (for testing and store validation only)
    Client IDThe 🆔 Client ID
    Client secretYour client secret. To copy it without printing it, run printf %s "$CONNECTOR_SECRET" | pbcopy on macOS, or Set-Clipboard $CONNECTOR_SECRET in PowerShell
    Authorization endpointThe 🌐 Authorization endpoint
    Token endpoint and Refresh endpointThe 🌐 Token and refresh endpoint
    Scopehttps://ai.gateway.azure.com/Data.All offline_access

    Turn on Enable PKCE.

    Any Teams app lets the connector use the registration. An existing Teams app binding doesn't work for MCP connectors.
  3. Select Save. The portal shows OAuth configuration "AI Gateway OBO demo" created successfully. Copy the OAuth client registration ID: the connector asks for it.

The scope asks Microsoft Entra ID for a token for AI Gateway, and offline_access for a refresh token, so users sign in once. The connector app already has tenant-wide consent to both, so users get no consent prompt.

3

Add the connector

  1. Open the Microsoft 365 admin center and allow pop-ups for it: the sign-in in step 3 opens one.

  2. Select CopilotConnectorsGalleryCreated by your org. On Create a new connector, select Add, then Connect to MCP serverAdd.

  3. Fill in the five steps of the form:

    1. Display name: AI Gateway OBO demo.
    2. Description: Demo MCP tools behind Azure AI Gateway. The gateway calls the backend as the signed-in user with Microsoft Entra ID on-behalf-of. Use it to ask who you are, echo a message, or get the server time. Copilot reads the description to decide when to use the tools.
    3. MCP endpoint URL: your MCP endpoint, the 🔌 Base URL.
    4. The developer details: Developer name Contoso, Website URL https://github.com/Azure/aigateway, Privacy policy URL https://privacy.microsoft.com/privacystatement, and Terms of use URL https://www.microsoft.com/legal/terms-of-use.
    5. Authentication type: OAuth 2.0. Paste the Reference ID, the OAuth client registration ID, then select Authorize and sign in. The button changes to Edit.
    Authorize signs you in through the gateway once, with the registration that you created.
  4. Check the Notice, then select Create. The Success page shows Created connection and Linking data source. Select Done.

    The connector can take up to 30 minutes to be ready.
4

Check the connection and its tools

  1. Select Your Connections. Within 30 minutes, the AI Gateway OBO demo row shows the state Ready.

    Ready means that Copilot users can install the connector's plugin.
  2. Select the connection, then ToolsSign in. The sign-in completes without a prompt and shows Sign in successful. Select View tools: the connector lists the three tools.

    The tools show as Write: the gateway doesn't pass the server's read-only annotations yet, so Copilot asks before each call.
Checkpoint

The connection AI Gateway OBO demo is Ready, and View tools lists three tools.

The gateway doesn't pass the tools' readOnlyHint annotations on to the connector yet, so Copilot treats them as Write tools and asks the user to approve each call.

Use the tools in Copilot Cowork

Copilot Cowork runs the connector's tools as the signed-in user. Sign in to Microsoft 365 Copilot as the user that has the Tools User role, you on this lab.

1

Install and connect the plugin

  1. Open Microsoft 365 Copilot and select Plugins. On the Cowork tab, search for OBO, then on AI Gateway OBO demo, select Install. Copilot shows Plugin installed. Connect your account below to get started.

    The connector appears as a plugin for everyone that its staged rollout includes.
  2. Turn on the plugin and select Connect. The connection shows Connected.

    Connect signs you in through the gateway once. Copilot refreshes the token after that.
2

Ask who the backend sees

  1. Select New, choose Cowork, and send this prompt:

    Text
    Using the AI Gateway OBO demo connector, call the whoami tool and tell me who the backend sees as the caller: name, object ID, token audience, and calling app.
  2. Cowork shows a Demo_whoami card with No parameters. Select Approve.

    Cowork asks before each call to a Write tool.
  3. Cowork answers with your name and object ID, the backend app as the token audience, and the token exchange app as the calling app.

    The same person who signed in to Copilot reached the backend, with a token that only the backend accepts.
Checkpoint

Cowork's answer shows your name and object ID, the same as demo_whoami returned to the test script.

Use Cowork for this lab. In Copilot Chat mode, the call waits for an approval that the chat doesn't show.

Verify

1

Read the backend's log

The MCP server logs one line for each call, with the user's object ID, the calling app, and the scope. The lines reach Log Analytics a few minutes after the calls.

# Find the Log Analytics workspace of the container app
WS="$(az monitor log-analytics workspace list -g "$BACKEND_RG" --query "[0].customerId" -o tsv)"

# Read the calls of the last hour: the user, the calling app, and the scope
echo "📊 Calls of the last hour:"
az monitor log-analytics query -w "$WS" -o tsv --analytics-query \
  "ContainerAppConsoleLogs_CL | where TimeGenerated > ago(1h) and Log_s has 'Call from user' | order by TimeGenerated asc | project Log_s"

The catalog, the test script, and Cowork each add lines with your object ID. The calling app is always the token exchange app: nothing else gets a token that the backend accepts.

2

Call the gateway with a token for another API

The gateway accepts only tokens for AI Gateway with the Data.All scope. Send it a token for Azure Resource Manager instead.

# Read the MCP endpoint of the server
MCP_ENDPOINT="$(az aigateway mcp show -g "$RG" --gateway-name "$GATEWAY" -n "$MCP_SERVER" --query "properties.gatewayEndpoints[0].url" -o tsv)"

# Call it with a token for Azure Resource Manager, then forget the token
ARM_TOKEN="$(az account get-access-token --query accessToken -o tsv)"
curl -s -w "\nHTTP %{http_code}\n" -X POST "$MCP_ENDPOINT" -H "Authorization: Bearer $ARM_TOKEN" \
  -H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
unset ARM_TOKEN
Checkpoint

The log shows your object ID with the token exchange app and the user_impersonation scope, and the token for Azure Resource Manager gets 401.

Go further

  • Call your own API. Replace the demo server with an API that already accepts Microsoft Entra tokens for its own scope. Grant the token exchange app consent to that scope, and put the scope in the backend's scopes. The API then applies its own permissions to each user.
  • Grant the role to a group. Assign AI Gateway Tools User on the MCP server to a Microsoft Entra group instead of single users, so that the group decides who can call the tools from Copilot.
  • Add controls to the calls. The user's identity also works with the gateway's tool controls: hide tools with allow and block lists, or check each call with agent hooks.
  • Deploy your own server. Fork the repository and point the image build at your branch: run azd env set MCP_SERVER_SOURCE "https://github.com/<you>/aigateway.git#<branch>:labs/33-copilot-obo-mcp/infra/mcp-server" and azd provision, or terraform plan -var mcp_server_source=<the same value> -out tfplan and terraform apply tfplan in the terraform folder.
  • Use the server from other MCP clients. Any client that sends a Microsoft Entra token for AI Gateway works, such as one that you configure with the token from az account get-access-token --scope https://ai.gateway.azure.com/Data.All. The gateway doesn't publish OAuth protected resource metadata yet, so clients that discover the sign-in from the server can't sign in on their own.
  • Rotate the connector's secret. It expires in seven days. Create a new one with the same command, update the Client secret of the OAuth client registration, and delete the old one with az ad app credential delete.

Clean up

Remove the connector from Microsoft 365 first, then the Azure resources.

1

Remove the connector from Microsoft 365

  1. In Microsoft 365 Copilot, select Plugins. On the Cowork tab, open AI Gateway OBO demo, select Disconnect, and turn off the plugin. Then select More actionsUninstall, and confirm.
  2. In the Microsoft 365 admin center, select CopilotConnectorsYour Connections. On the AI Gateway OBO demo row, select More ActionsView DetailsDelete, and confirm.
  3. In the Teams Developer Portal, select ToolsOAuth client registration. On the AI Gateway OBO demo row, select the actions menu › Delete, and confirm.
Choose your track
1

Delete the MCP server and the backend

In the AI Gateway portal, select MCP servers. On the OBO demo row, select More actions (⋯) › Delete, and confirm. Then delete the rest with the Azure CLI track's commands below, from the gateway identity on: the Azure CLI steps of Deploy the backend and register the MCP server created them.

Keep the gateway and the learn MCP server from lab 04: the next labs reuse them. azd down and terraform destroy don't touch them, because the Bicep + azd and Terraform tracks created their own gateways.

Next steps

Finished the lab?

Mark it complete to track your progress across paths. It's saved only in this browser.