Merge pull request #717 from microsoft/dev

chore: Dev to Main

Author: Prajwal-Microsoft

docs/ConfigureAppAuthentication.md

@@ -15,6 +15,55 @@ This document provides step-by-step instructions to configure Azure App Registra
 
 - Access to **Microsoft Entra ID**
 - Necessary permissions to create and manage **App Registrations**
+- Azure CLI (`az`) signed in to the deployment subscription (for the automated script)
+
+## Automated configuration (recommended)
+
+Authentication is configured by a standalone script,
+[`infra/scripts/configure_app_authentication`](../infra/scripts/configure_app_authentication.ps1),
+which you run as a **manual post-deployment step** (it is intentionally not run
+during `azd up` provisioning, to avoid deployment failures). Run it immediately
+after the post-deployment schema-registration step. The script performs every
+step in this document without the manual portal clicks: it creates (or reuses)
+the API and Web app registrations, exposes the `user_impersonation` scope,
+enables Container Apps authentication (the **API is set to return HTTP 401** for
+unauthenticated callers — fail closed), allows the Web client on the API, and
+updates the Web container environment variables.
+
+Run it from the project root:
+
+```powershell
+# PowerShell (Windows)
+.\infra\scripts\configure_app_authentication.ps1
+```
+
+```bash
+# Bash (Linux/macOS/WSL)
+bash infra/scripts/configure_app_authentication.sh
+```
+
+To reuse existing app registrations instead of creating new ones, pass their
+client ids:
+
+```powershell
+.\infra\scripts\configure_app_authentication.ps1 -ApiClientId <guid> -WebClientId <guid>
+```
+
+> **Permissions:** Creating app registrations and granting admin consent
+> requires the **Application Administrator** role (or equivalent). If the script
+> cannot grant admin consent automatically it prints a warning; a tenant
+> administrator must then consent to the API permission for the Web app. See the
+> admin-consent note in [Step 2](#step-2-configure-application-registration---web-application).
+
+> **Web interactive login:** The script configures the Web app's identity
+> provider. If your tenant requires a client secret for the browser sign-in
+> (authorization-code) flow, add one with
+> `az containerapp auth microsoft update --name <web-app> --resource-group <rg> --client-secret <value>`,
+> or complete Step 1 for the Web app through the portal. The **API** protection
+> (HTTP 401 for unauthenticated callers) does not require a secret.
+
+The remaining sections describe the equivalent **manual portal steps**, kept as
+a fallback for environments where the script cannot be run.
 
 ## Step 1: Add Authentication Provider
 

docs/DeploymentGuide.md

@@ -331,6 +331,12 @@ azd up
      .\infra\scripts\post_deployment.ps1
      ```
 
+   > **Note:** Run this schema-registration step **before** configuring
+   > authentication (next step). At this point the API is still open, so no token
+   > is required. If you re-run it **after** enabling authentication, the script
+   > authenticates automatically using the deploying user's token — just ensure
+   > you are signed in with `az login`.
+
 ### 5.2 Schema Registration (Automatic)
 
  > Want to customize the schemas for your own documents? [Learn more about adding your own schemas here.](./CustomizeSchemaData.md)
@@ -391,20 +397,50 @@ Schema registration process completed.
   ✅ Schema registration complete.
 ```
 
-### 5.2 Configure Authentication (Required)
+### 5.3 Configure Authentication (Required Manual Step)
+
+**This step is mandatory.** Until it is completed the API has external ingress
+and is reachable without authentication, so run it immediately after the
+post-deployment script. Authentication is configured by a standalone script.
+
+Run the configuration script from the project root:
+
+- For Bash (Linux/macOS/WSL):
+
+  ```bash
+  bash infra/scripts/configure_app_authentication.sh
+  ```
+
+- For PowerShell (Windows):
+
+  ```powershell
+  .\infra\scripts\configure_app_authentication.ps1
+  ```
+
+This enables Microsoft Entra ID (Easy Auth) on the API and Web container apps and
+sets the **API to return HTTP 401** for unauthenticated callers (fail closed).
+To reuse existing app registrations, pass their client ids
+(`-ApiClientId` / `-WebClientId` in PowerShell). For details, options, the
+admin-consent requirement, and the manual portal fallback, see
+[App Authentication Configuration](./ConfigureAppAuthentication.md).
 
-**This step is mandatory for application access:**
+> **Note:** Allow up to 10 minutes for authentication changes to take effect.
+> Creating app registrations and granting admin consent requires the
+> **Application Administrator** role; if admin consent cannot be granted
+> automatically, a tenant administrator must consent to the API permission for
+> the Web app.
 
-1. Follow [App Authentication Configuration](./ConfigureAppAuthentication.md).
-2. Wait up to 10 minutes for authentication changes to take effect.
+> **Troubleshooting:** If the script fails with an authentication error (e.g.
+> `InteractionRequired` / `TokenCreatedWithOutdatedPolicies`), run `az logout`
+> then `az login` to refresh your token and re-run the script.
 
-### 5.3 Verify Deployment
+### 5.4 Verify Deployment
 
 1. Access your application using the **Web App Endpoint** from the deployment output.
 2. Confirm the application loads successfully.
 3. Verify you can sign in with your authenticated account.
 
-### 5.4 Test the Application
+### 5.5 Test the Application
 
 **Quick Test Steps:**
 1. **Download Samples**: Get sample files from the [samples directory](../src/ContentProcessorAPI/samples) — use the `claim_date_of_loss/` or `claim_hail/` folders for auto claim documents.