feat: Update documentation for external authentication setup and deployment process

imsaadawais · imsaadawais · commit 7caab7aa3a1e · 2026-07-02T17:21:53.000-07:00
diff --git a/docs/WikiContentDocumentationUpdatePlan.md b/docs/WikiContentDocumentationUpdatePlan.md
diff --git a/src/BlazorOrchestrator.Web/manifests/containerApp.tmpl.yaml b/src/BlazorOrchestrator.Web/manifests/containerApp.tmpl.yaml
@@ -0,0 +1,25 @@
+api: resources/2024-03-01
+location: {{ .Env.AZURE_LOCATION }}
+identity:
+  type: UserAssigned
+  userAssignedIdentities:
+    ? "{{ .Env.AZURE_CONTAINER_REGISTRY_MANAGED_IDENTITY_ID }}"
+    : {}
+properties:
+  configuration:
+    ingress:
+      external: true
+      targetPort: {{ targetPortOrDefault 8080 }}
+      transport: auto
+      allowInsecure: false
+      stickySessionsMode: sticky
+    registries:
+      - server: "{{ .Env.AZURE_CONTAINER_REGISTRY_ENDPOINT }}"
+        identity: "{{ .Env.AZURE_CONTAINER_REGISTRY_MANAGED_IDENTITY_ID }}"
+  template:
+    containers:
+      - image: {{ .Image }}
+        name: webapp
+        env:
+          - name: AZURE_CLIENT_ID
+            value: "{{ .Env.MANAGED_IDENTITY_CLIENT_ID }}"
diff --git a/wiki-content/Deployment.md b/wiki-content/Deployment.md
@@ -165,11 +165,81 @@ You can scale agents horizontally by deploying multiple replicas or multiple Con
 - **Default pool**: 2 replicas monitoring the `default` queue
 - **Large job pool**: 1 replica monitoring `jobs-large-container` with more CPU/memory allocated
 
-### Upgrade
+### Updating a Deployed Instance
 
-After initial deployment, you can upgrade easily using *Visual Studio* by right-clicking on the `AppHost` project and selecting publish and following the wizard.
+After the initial deployment with `azd up`, use `azd deploy` for all subsequent updates. This rebuilds and redeploys all services without re-provisioning infrastructure.
 
-![alt text](images/upgrade-using-azure.png)
+From the AppHost directory, run:
+
+```bash
+azd deploy
+```
+
+This command:
+1. Builds all projects (Web, Scheduler, Agent)
+2. Containerizes the services
+3. Pushes updated images to Azure Container Registry
+4. Deploys updated containers to Azure Container Apps
+
+**When to use each command:**
+
+| Command | Use When |
+|---------|----------|
+| `azd up` | First-time deployment (provisions infrastructure + deploys) |
+| `azd deploy` | Updating an existing deployment with code or configuration changes |
+| `azd provision` | Updating only infrastructure (e.g., adding new Azure resources) |
+
+> **Note:** If you have changed the Aspire AppHost topology (added or removed services/resources in `Program.cs`), run `azd up` instead to ensure infrastructure is updated.
+
+**Deploying a single service:**
+
+To deploy only one service (e.g., after a change to only the web app):
+
+```bash
+azd deploy webapp
+```
+
+Service names match those defined in the AppHost: `webapp`, `scheduler`, `agent`.
+
+```mermaid
+flowchart TD
+    A["Code changes committed"] --> B{"First deployment?"}
+    B -- Yes --> C["azd auth login"]
+    C --> D["azd up"]
+    D --> E["Infrastructure provisioned and app deployed"]
+    B -- No --> F{"Infrastructure changes?"}
+    F -- Yes --> G["azd up"]
+    G --> E
+    F -- No --> H["azd deploy"]
+    H --> I["Updated containers deployed to existing infrastructure"]
+
+    style D fill:#0078d4,stroke:#005a9e,color:#fff
+    style G fill:#0078d4,stroke:#005a9e,color:#fff
+    style H fill:#107c10,stroke:#0b5e0b,color:#fff
+```
+
+> **Alternative: Visual Studio Publish**
+>
+> You can also publish from Visual Studio by right-clicking the AppHost project and selecting **Publish**. However, `azd deploy` is the recommended approach as it is scriptable, repeatable, and consistent with the initial deployment workflow.
+>
+> ![alt text](images/upgrade-using-azure.png)
+
+### External Authentication Redirect URIs
+
+When deploying to Azure Container Apps, external authentication redirect URIs must use the Container App's fully qualified domain name (FQDN):
+
+| Provider | Redirect URI Pattern |
+|----------|---------------------|
+| Microsoft | `https://<container-app-fqdn>/signin-microsoft` |
+| Google | `https://<container-app-fqdn>/signin-google` |
+
+The FQDN is assigned by Azure Container Apps after deployment. Retrieve it from the Azure Portal or via:
+
+```bash
+az containerapp show --name <webapp-name> --resource-group <rg-name> --query properties.configuration.ingress.fqdn -o tsv
+```
+
+If using a custom domain, use that domain in the redirect URIs instead. Update the redirect URIs in your Azure Entra ID app registration and/or Google Cloud Console credentials to match.
 
 ### Podman deployment
 
diff --git a/wiki-content/Features.md b/wiki-content/Features.md
@@ -108,6 +108,19 @@ You can enable webhook triggers on a per-job basis. Each webhook-enabled job rec
 
 ---
 
+## External Authentication (Microsoft & Google)
+
+Blazor Data Orchestrator supports optional external authentication via **Microsoft** (Azure Entra ID) and **Google** (OAuth 2.0) identity providers. External logins are configured entirely through the Admin UI — no changes to `appsettings.json` are needed.
+
+- **Microsoft authentication** — Register an application in Azure Entra ID, then enter the Client ID and Client Secret in the Administration > Authentication tab.
+- **Google authentication** — Create OAuth 2.0 credentials in the Google Cloud Console, then enter the Client ID and Client Secret in the Administration > Authentication tab.
+- **Account linking only** — External logins link to existing user accounts. They do not auto-create new accounts.
+- **Settings stored in Azure Table Storage** — Authentication configuration is persisted alongside other application settings, not in configuration files.
+
+> **Important:** After enabling or disabling an authentication provider, you must **restart the application** for the change to take effect. See the [Installation](https://github.com/Blazor-Data-Orchestrator/BlazorDataOrchestrator/wiki/Installation) guide for details.
+
+---
+
 ## Environment-Specific Configuration
 
 Jobs support per-environment configuration files that are loaded at execution time based on the job's `JobEnvironment` setting.
@@ -169,7 +182,15 @@ The repository includes full Azure Developer CLI (`azd`) integration. A single c
 azd up
 ```
 
-This takes you from `git clone` to a fully deployed Azure Container Apps environment with no manual infrastructure setup. See the [Deployment](https://github.com/Blazor-Data-Orchestrator/BlazorDataOrchestrator/wiki/Deployment) guide for details.
+This takes you from `git clone` to a fully deployed Azure Container Apps environment with no manual infrastructure setup.
+
+For subsequent updates after the initial deployment, use `azd deploy` to rebuild and redeploy all services without re-provisioning infrastructure:
+
+```bash
+azd deploy
+```
+
+See the [Deployment](https://github.com/Blazor-Data-Orchestrator/BlazorDataOrchestrator/wiki/Deployment) guide for details.
 
 ---
 
diff --git a/wiki-content/Frequently-Asked-Questions.md b/wiki-content/Frequently-Asked-Questions.md
@@ -34,6 +34,14 @@ No. Aspire automatically starts an **Azurite** container (Azure Storage emulator
 
 Run `azd up` from the repository root. This single command provisions all required Azure resources (Azure SQL, Storage Account, Container Registry, Container Apps Environment), builds and containerizes all services, and deploys them to Azure Container Apps. See the [Deployment](https://github.com/Blazor-Data-Orchestrator/BlazorDataOrchestrator/wiki/Deployment) guide for details.
 
+### How do I update my deployed instance after making code changes?
+
+Run `azd deploy` from the AppHost directory. This rebuilds all services, pushes updated container images, and deploys them to Azure Container Apps without re-provisioning infrastructure. Use `azd up` only for the initial deployment or when the AppHost topology has changed (e.g., added or removed services/resources in `Program.cs`).
+
+### Can I deploy just one service instead of all three?
+
+Yes. Run `azd deploy <service-name>` where the service name is `webapp`, `scheduler`, or `agent`. This deploys only the specified service.
+
 ---
 
 ## Installation
@@ -124,6 +132,30 @@ Deploy multiple Agent instances or replicas. Each agent monitors a specific queu
 
 ---
 
+## Authentication
+
+### How do I set up Microsoft authentication?
+
+Register an application in Azure Entra ID (formerly Azure AD) with a redirect URI of `https://<your-app-url>/signin-microsoft`, create a client secret, then enter the Client ID and Client Secret in **Administration** > **Authentication** in the web UI. Restart the application after saving. See the [Installation](https://github.com/Blazor-Data-Orchestrator/BlazorDataOrchestrator/wiki/Installation) guide for a full walkthrough.
+
+### How do I set up Google authentication?
+
+Create OAuth 2.0 credentials in the Google Cloud Console with a redirect URI of `https://<your-app-url>/signin-google`, then enter the Client ID and Client Secret in **Administration** > **Authentication** in the web UI. Restart the application after saving. See the [Installation](https://github.com/Blazor-Data-Orchestrator/BlazorDataOrchestrator/wiki/Installation) guide for a full walkthrough.
+
+### I configured Microsoft/Google authentication but the login buttons do not appear
+
+After changing any authentication settings in the Admin UI, you must **restart the application**. Authentication middleware is initialized at startup, and changes are not picked up at runtime. For local development, stop and re-run `aspire run`. For Azure, restart the Container App or redeploy with `azd deploy`.
+
+### Do external logins create new user accounts automatically?
+
+No. External logins only link to **existing** user accounts. A user must already be created in the system (via the Install Wizard or by an administrator) before they can sign in with Microsoft or Google.
+
+### Where are the authentication settings stored?
+
+Authentication settings (Client ID, Client Secret, Enabled flags) are stored in **Azure Table Storage**, not in `appsettings.json`. They are managed exclusively through the Administration > Authentication tab in the web UI.
+
+---
+
 ## Troubleshooting
 
 ### Where are job logs stored?
diff --git a/wiki-content/Home.md b/wiki-content/Home.md
@@ -36,6 +36,7 @@ Go from `git clone` to a fully operational job automation system in minutes:
 2. **Clone & restore** — `git clone https://github.com/Blazor-Data-Orchestrator/BlazorDataOrchestrator.git && cd BlazorDataOrchestrator && dotnet workload restore`
 3. **Run locally** — `aspire run` — Aspire starts SQL Server, Azurite, and all application services automatically. Complete the Install Wizard on first launch.
 4. **Deploy to Azure** — `azd up` — Provisions Azure SQL, Storage, Container Registry, and Container Apps, then builds and deploys all services in a single command.
+5. **Update a deployed instance** — `azd deploy` — Rebuilds and redeploys all services without re-provisioning infrastructure.
 
 See the [Installation](https://github.com/Blazor-Data-Orchestrator/BlazorDataOrchestrator/wiki/Installation) guide for detailed local setup and the [Deployment](https://github.com/Blazor-Data-Orchestrator/BlazorDataOrchestrator/wiki/Deployment) guide for Azure deployment.
 
diff --git a/wiki-content/Installation.md b/wiki-content/Installation.md
@@ -87,6 +87,55 @@ After the Install Wizard completes:
 
 ---
 
+## 6. Configure External Authentication (Optional)
+
+Blazor Data Orchestrator supports optional sign-in via **Microsoft** (Azure Entra ID) and **Google** (OAuth 2.0). These providers are configured entirely through the Admin UI — no changes to configuration files are needed.
+
+### Microsoft Authentication
+
+1. Navigate to the [Azure Portal](https://portal.azure.com) and go to **Microsoft Entra ID** > **App registrations** > **New registration**.
+2. Set the application name (e.g., `BlazorDataOrchestrator`).
+3. Set **Supported account types** to the appropriate scope:
+   - *Single tenant* — only users in your Azure AD directory
+   - *Multitenant* — users from any Azure AD directory
+   - *Multitenant + personal Microsoft accounts* — broadest scope
+4. Set the **Redirect URI**:
+   - Type: **Web**
+   - URI: `https://<your-app-url>/signin-microsoft`
+   - For local development: `https://localhost:<port>/signin-microsoft`
+5. Go to **Certificates & secrets** > **Client secrets** > **New client secret**. Copy the **Value** immediately (it is only shown once).
+6. Go to the app registration **Overview** page and copy the **Application (client) ID**.
+7. In Blazor Data Orchestrator, navigate to **Administration** > **Authentication**.
+8. Enable **Microsoft Authentication**, paste the **Client ID** and **Client Secret**, and click **Save**.
+9. **Restart the application** (see warning below).
+
+### Google Authentication
+
+1. Navigate to [Google Cloud Console](https://console.cloud.google.com/) and create or select a project.
+2. Go to **APIs & Services** > **Credentials** > **Create Credentials** > **OAuth client ID**.
+3. If prompted, configure the **OAuth consent screen** — set the app name, support email, and add scopes: `openid`, `email`, `profile`.
+4. Set **Application type** to **Web application**.
+5. Add **Authorized redirect URIs**:
+   - `https://<your-app-url>/signin-google`
+   - For local development: `https://localhost:<port>/signin-google`
+6. Copy the **Client ID** and **Client Secret** from the credentials page.
+7. In Blazor Data Orchestrator, navigate to **Administration** > **Authentication**.
+8. Enable **Google Authentication**, paste the **Client ID** and **Client Secret**, and click **Save**.
+9. **Restart the application** (see warning below).
+
+> **⚠️ Warning: Application Restart Required**
+>
+> After enabling, disabling, or changing the Client ID / Client Secret for any external authentication provider (Microsoft or Google), you **must restart the application** for the changes to take effect.
+>
+> - **Local development:** Stop and re-run `aspire run`
+> - **Azure Container Apps:** Restart the Container App via the Azure Portal, Azure CLI, or redeploy using `azd deploy`
+>
+> The Login page will not show or hide provider buttons until the restart is complete.
+
+> **Note:** External logins only **link to existing user accounts**. They do not auto-create new accounts. The user must already exist in the system before they can sign in with an external provider.
+
+---
+
 ## Configuration Files
 
 Blazor Data Orchestrator uses standard .NET configuration files. In development, Aspire injects connection strings automatically, so you typically do not need to edit these files.
diff --git a/wiki-content/Operation.md b/wiki-content/Operation.md
@@ -179,6 +179,38 @@ Navigate to the **Administration** page via the navigation link on the home page
 | **API Key** | Enter the API key supplied by the AI provider |
 | **Model** | Choose the model to use |
 
+### External Authentication Providers
+
+Blazor Data Orchestrator supports optional external authentication via **Microsoft** (Azure Entra ID) and **Google** (OAuth 2.0). These providers are managed from the **Administration** > **Authentication** tab.
+
+#### Authentication Settings Reference
+
+| Setting | Storage Key | Description |
+|---------|-------------|-------------|
+| Microsoft Enabled | `Authentication:Microsoft:Enabled` | Toggles the Microsoft login button on the Login page |
+| Microsoft Client ID | `Authentication:Microsoft:ClientId` | Application (client) ID from Azure Entra ID |
+| Microsoft Client Secret | `Authentication:Microsoft:ClientSecret` | Client secret value from Azure Entra ID |
+| Google Enabled | `Authentication:Google:Enabled` | Toggles the Google login button on the Login page |
+| Google Client ID | `Authentication:Google:ClientId` | OAuth 2.0 Client ID from Google Cloud Console |
+| Google Client Secret | `Authentication:Google:ClientSecret` | OAuth 2.0 Client Secret from Google Cloud Console |
+
+> **Important:** These settings are stored in Azure Table Storage, not in `appsettings.json`. They are managed exclusively through the Admin UI.
+
+#### Account Linking
+
+External logins only **link to existing user accounts**. They do not auto-create new accounts. A user must already exist in the system (created via the Install Wizard or by an administrator) before they can sign in with Microsoft or Google.
+
+> **⚠️ Warning: Application Restart Required**
+>
+> After enabling, disabling, or changing the Client ID / Client Secret for any external authentication provider, you **must restart the application** for the changes to take effect.
+>
+> - **Local development:** Stop and re-run `aspire run`
+> - **Azure Container Apps:** Restart the Container App via the Azure Portal, Azure CLI, or redeploy using `azd deploy`
+>
+> Authentication middleware is initialized at application startup. The `ExternalAuthOptionsStore` injects credentials via `IPostConfigureOptions`, but enabling or disabling a provider requires the authentication pipeline to be fully re-initialized — which only happens on restart. The Login page will not show or hide provider buttons until the restart is complete.
+
+For setup instructions including Azure Portal and Google Cloud Console walkthroughs, see the [Installation](https://github.com/Blazor-Data-Orchestrator/BlazorDataOrchestrator/wiki/Installation) guide.
+
 ---
 
 ## Agent Behavior
