Add OBO auth documentation: consent, code walkthrough, troubleshooting

- Update intro to mention hello_tool_with_auth and OBO flow
- Add Step 4 (consent) and Step 5 (connect) to deploy instructions
- Add 'Calling Microsoft Graph with OBO' code walkthrough section
- Add 'Consent authoring' section explaining user vs admin consent
- Expand troubleshooting with OBO-specific errors and solutions

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: lilyjma

src/FunctionsMcpTool/README.md

@@ -1,6 +1,6 @@
 # FunctionsMcpTool — Remote MCP Server on Azure Functions (Python)
 
-This project is a Python Azure Function app that exposes multiple MCP (Model Context Protocol) tools as a remote MCP server. It includes tools for snippets, QR code generation, structured metadata, batch operations, and more.
+This project is a Python Azure Function app that exposes multiple MCP (Model Context Protocol) tools as a remote MCP server. It includes tools for snippets, QR code generation, badges, structured metadata, batch operations, and a **hello with auth** tool that demonstrates the On-Behalf-Of (OBO) flow to call Microsoft Graph as the signed-in user.
 
 > **Note:** MCP resources are in the [FunctionsMcpResources](../FunctionsMcpResources/) project, and prompts are in the [FunctionsMcpPrompts](../FunctionsMcpPrompts/) project.
 
@@ -120,7 +120,7 @@ This also becomes the resource group name.
 
 ### Step 3: Provision and deploy
 
-By default, OAuth-based authentication is enabled using the [built-in MCP auth feature](https://learn.microsoft.com/azure/app-service/configure-authentication-mcp?toc=/azure/azure-functions/toc.json&bc=/azure/azure-functions/breadcrumb/toc.json) with Microsoft Entra as the identity provider.
+This project requires OAuth-based authentication through the [built-in MCP auth feature](https://learn.microsoft.com/azure/app-service/configure-authentication-mcp?toc=/azure/azure-functions/toc.json&bc=/azure/azure-functions/breadcrumb/toc.json) with Microsoft Entra as the identity provider, and it is enabled by default. Do not disable authentication for this project.
 
 Configure VS Code as an allowed client application for Microsoft Entra:
 
@@ -140,11 +140,25 @@ Deploy the project. When prompted, pick your subscription and an Azure region.
 azd up
 ```
 
-### Step 4: Connect to the remote MCP server
+### Step 4: Consent to the application
 
-Open **`.vscode/mcp.json`** and click **Start** above **`remote-mcp-function`**. You'll be prompted for `functionapp-name` — find it in your `azd` command output or the `.azure/<env>/.env` file. Since authentication is enabled, you'll also be prompted to sign in with Microsoft.
+The `hello_tool_with_auth` tool requires consent for delegated permission to access Microsoft Graph. For testing, you can grant consent just for yourself by logging into the application in a browser. See [Consent authoring](#consent-authoring) for how you would handle this for production scenarios.
 
-> **Tip:** Click **More... → Show Output** above the server name to see request/response details.
+Navigate to the `/.auth/login/aad` endpoint of your deployed function app. For example, if your function app is at `https://my-mcp-function-app.azurewebsites.net`, navigate to:
+
+```
+https://my-mcp-function-app.azurewebsites.net/.auth/login/aad
+```
+
+Sign in with your Azure subscription email and accept the permissions prompt. This completes the consent flow for you.
+
+### Step 5: Connect to the remote MCP server
+
+Open **`.vscode/mcp.json`** and click **Start** above **`remote-mcp-function`**. You'll be prompted for `functionapp-name` — find it in your `azd` command output or the `.azure/<env>/.env` file. You'll also be prompted to authenticate with Microsoft — click **Allow** and sign in.
+
+> **Tip:** A successful connection shows the number of tools the server exposes. Click **More... → Show Output** above the server name to see request/response details.
+
+> If you run into issues, see the [Troubleshooting](#troubleshooting) section below.
 
 ### Redeploy and clean up
 
@@ -190,11 +204,85 @@ def generate_qr_code(text: str) -> ImageContent:
     )
 ```
 
+### Calling Microsoft Graph with the On-Behalf-Of flow (`hello_tool_with_auth`)
+
+The `hello_tool_with_auth` tool (in [`hello_tool_with_auth.py`](hello_tool_with_auth.py)) demonstrates how to call a downstream API (Microsoft Graph) **as the signed-in user** using the On-Behalf-Of (OBO) flow.
+
+**Local development** falls back to your local developer identity (Azure CLI, azd, etc.):
+
+```python
+if is_local:
+    credential = ChainedTokenCredential(
+        AzureCliCredential(),
+        AzureDeveloperCliCredential(),
+    )
+else:
+    credential = _build_obo_credential(context)
+```
+
+**In production**, the `_build_obo_credential` function exchanges the user's auth token for a Microsoft Graph token using three pieces of information:
+
+1. **The user's bearer token** — extracted from the `X-MS-TOKEN-AAD-ACCESS-TOKEN` header (or `Authorization` fallback)
+2. **The user's tenant ID** — decoded from the `X-MS-CLIENT-PRINCIPAL` header
+3. **A client assertion** — obtained from a managed identity with a federated credential, proving the app's identity without a client secret
+
+```python
+def _build_obo_credential(context):
+    # Extract headers from MCP context
+    headers = context.get("HttpTransport", {}).get("Headers", {})
+
+    user_token = headers.get("X-MS-TOKEN-AAD-ACCESS-TOKEN", "")
+    tenant_id = ...  # decoded from X-MS-CLIENT-PRINCIPAL
+
+    managed_identity = ManagedIdentityCredential(client_id=federated_mi_client_id)
+
+    def client_assertion_func():
+        return managed_identity.get_token("api://AzureADTokenExchange/.default").token
+
+    return OnBehalfOfCredential(
+        tenant_id=tenant_id,
+        client_id=client_id,
+        client_assertion_func=client_assertion_func,
+        user_assertion=user_token,
+    )
+```
+
+The resulting credential is then used to call Microsoft Graph `/me` and greet the user by name:
+
+```python
+token = credential.get_token("https://graph.microsoft.com/.default")
+async with aiohttp.ClientSession() as session:
+    async with session.get(
+        "https://graph.microsoft.com/v1.0/me",
+        headers={"Authorization": f"Bearer {token.token}"},
+    ) as resp:
+        me = await resp.json()
+        return f"Hello, {me['displayName']} ({me['mail']})!"
+```
+
+## Consent authoring
+
+In the steps described for this example, you consented to the application by signing into it in a browser. This allowed the application to request delegated permissions to the Microsoft Graph. There are two main ways that consent can be handled:
+
+- **User consent** — This is the approach used in the example above. Each user signs into the application and consents to the permissions requested. They can only do this for themselves, unless they are a tenant administrator with the ability to consent on behalf of others. In this sample, user consent is appropriate because it allows you to quickly test things without impacting other users. However, the way user consent is authored in this sample does not reflect how you would typically do it in a production scenario. This is described in more detail below.
+
+- **Admin consent** — A tenant administrator can consent to the application on behalf of all users when they sign in and review the permissions. Once this is done, individual users can sign in without needing to consent themselves. This approach is more scalable and ensures that all users can access the application without running into consent issues. For the purposes of a sample, admin consent is not appropriate, but it is a great choice for production scenarios.
+
+The user consent approach for this sample is a separate login because the sample uses Visual Studio Code as the client. Although Visual Studio Code is pre-authorized to our application, that only creates consent for the user to call the MCP server. It doesn't create consent for the MCP server to call the Microsoft Graph on behalf of the user. When we log into the application directly, we request Microsoft Graph permissions as part of a combined consent experience.
+
+The main difference is that because Visual Studio Code is using a single sign-on flow, it only requests a token for the MCP server. It does not present an opportunity for the user to interactively consent to any permissions needed for or by the MCP server. If you built a client that used an interactive login of some kind, you could have it all handled entirely by that client. It would not be necessary to have a separate browser login.
+
+See [Overview of permissions and consent in the Microsoft identity platform](https://learn.microsoft.com/en-us/entra/identity-platform/permissions-consent-overview) for additional information on how Entra ID handles consent.
+
 ## Troubleshooting
 
 | Problem | Solution |
 |---------|----------|
 | Connection refused locally | Ensure Azurite is running (`docker run -p 10000:10000 ...`) |
 | API version not supported by Azurite | Add `--skipApiVersionCheck` flag to the Azurite command, or pull the latest image |
+| `hello_tool_with_auth` fails locally | Ensure you're signed in with `az login` or `azd auth login` |
+| OBO errors in production | Verify that consent has been granted (see Step 4) and that the Entra app registration is configured correctly |
+| `An error occurred invoking 'hello_tool_with_auth'` right after `azd up` | Restart the function app: `az functionapp restart -g <resource-group> -n <function-app-name>`. The OBO flow signs a client assertion with the user-assigned managed identity via a federated identity credential (FIC). Right after provisioning, the auth runtime can hold a stale signing credential while the FIC propagates in Entra. Check **Application Insights > Logs** for `AADSTS50013: Assertion failed signature validation` to confirm. |
+| Generic "An error occurred invoking" with no details | Check **Application Insights > Logs** and query `exceptions \| where timestamp > ago(1h) \| project timestamp, outerMessage, innermostMessage` to find the actual error. |
 | `AttributeError: 'FunctionApp' object has no attribute 'mcp_resource_trigger'` | Python 3.13 is required. Verify with `python3 --version`. |
 | `azd up` provision succeeded but deploy failed | Transient error — run `azd deploy` again |