Update Aspire related docs (#279)

- Add missing dependencies - Add missing steps - Add more details about Entra apps - Add some screenshots to help
microsoft · Dec 11, 2024 · c3e36b7 · c3e36b7
1 parent 7c8801c
commit c3e36b7
Show file tree

Hide file tree

Showing 2 changed files with 85 additions and 41 deletions.
diff --git a/aspire-orchestrator/README.md b/aspire-orchestrator/README.md
@@ -1,54 +1,89 @@
-# .NET Aspire Integratiuon
+# .NET Aspire Integration
 
 ## Run Prerequisites
 
-- [dotnet (8 or greater)](https://dotnet.microsoft.com/en-us/download)
+- [dotnet (8 or greater)](https://dotnet.microsoft.com/download)
+- [Python 3.8 or greater](https://www.python.org/downloads)
+- [NodeJs v18.12 or greater](https://nodejs.org/en/download)
 
 ## Deployment Prerequisites
 
-- [Azure Developer CLI](https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/install-azd?tabs=winget-windows%2Cbrew-mac%2Cscript-linux)
-- [dotnet (9 or greater)](https://dotnet.microsoft.com/en-us/download)
-- [Python 3.8 or greater](https://www.python.org/downloads/)
-- [NodeJs v18.12 or greater](https://nodejs.org/en/download/)
+- [Azure Developer CLI](https://learn.microsoft.com/azure/developer/azure-developer-cli/install-azd)
+- [Docker for Desktop](https://docs.docker.com/get-started/introduction/get-docker-desktop)
+- [dotnet (9 or greater)](https://dotnet.microsoft.com/download)
+- [Python 3.8 or greater](https://www.python.org/downloads)
+- [NodeJs v18.12 or greater](https://nodejs.org/en/download)
 
 ## Run with .NET Aspire
 
-1. Make sure you have accepted the [dotnet trust dev certificate](https://learn.microsoft.com/en-us/aspnet/core/security/enforcing-ssl?view=aspnetcore-9.0&tabs=visual-studio%2Clinux-sles#trust-the-aspnet-core-https-development-certificate)
-```bash
-dotnet dev-certs https --trust
-```
+1.  Make sure your workstation trusts
+    [ASP.NET Core HTTPS development certificate](https://learn.microsoft.com/en-us/aspnet/core/security/enforcing-ssl?#trust-the-aspnet-core-https-development-certificate)
 
-2. Clone the repository
+        dotnet dev-certs https --trust
 
-```bash
-make
-cd aspire-orchestrator
-cd Aspire.AppHost
-dotnet run
-```
+2.  Clone the repository
+
+        make
+        cd aspire-orchestrator
+        cd Aspire.AppHost
+        dotnet run
 
 ## Deployment Steps with azd
 
-1. Clone the repository
-2. In the root folder, run
-```bash
-make
-```
-3. [Configure the app registration and configure workbenchapp and workbench service](../docs/CUSTOM_APP_REGISTRATION.md). Set the values in the `aspire-orchestrator/aspire-orchestrator/aspire-orchestrator/aspire-orchestrator/appsettings.json` file
-```json
-{
-    "EntraID": {
-        "ClientId": "<CLIENT_ID>",
-        "Authority": "https://login.microsoftonline.com/<TENANT_ID>"
-    }
-}
-```
-4. Authenticate with Azure Developer CLI
-```bash
-azd login
-```
-5. Create the infrastructure and deploy the application
-```bash
-azd up
-```
-6. Update the App Registration with the correct workbenchapp redirect URI
+1.  Clone the repository
+
+2.  [Configure the Entra app registration](../docs/CUSTOM_APP_REGISTRATION.md).
+    Copy the Entra **Application Id** and **Tenant Id** into
+    `aspire-orchestrator/Aspire.AppHost/appsettings.json` file.
+
+    If your Entra App allows both organizational and personal accounts
+    use `common` as Tenant Id, e.g. setting
+    `"Authority": "https://login.microsoftonline.com/common"`. For other special
+    authority values refer to https://learn.microsoft.com/en-us/entra/identity-platform/v2-protocols-oidc
+
+        {
+          "EntraID": {
+            "ClientId": "<CLIENT_ID>",
+            "Authority": "https://login.microsoftonline.com/<TENANT_ID>"
+          }
+        }
+
+3.  In the root folder of the repository, run
+
+        make
+
+4.  Authenticate with Azure Developer CLI
+
+        azd login
+
+5.  Generate the Azure config files required in the next step
+
+        azd init --from-code --environment semanticworkbench
+
+6.  Create Azure resources and deploy the application
+
+        azd up
+
+    When asked for "**authority**", enter the same value set in appsettings.json.
+
+    When asked for "**clientId**", enter the same value set in appsettings.json.
+
+    These values are stored as Environment Variables and can be modified in Azure
+    Portal if needed.
+
+    The deployment will take a few minutes to complete, taking care also of
+    creating and deploying the required docker images.
+
+7.  After the deployment is complete, a few URLs will be printed, in particular
+    the Aspire Dashboard URL and Semantic Workbench App URL.
+
+    Copy the `service workbenchapp` endpoint value for the next step:
+    | ![Image](https://github.com/user-attachments/assets/0aae7518-bfa6-4f76-962a-df3d152e0155) |
+    |:--:|
+
+8.  Update the [Entra App Registration](https://portal.azure.com/#view/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/~/RegisteredApps),
+    adding the URL from the previous step as one of the SPA Redirection URIs:
+    | ![Image](https://github.com/user-attachments/assets/e709ee12-a3ef-4be3-9f2d-46d33c929f42) |
+    |:-:|
+
+9.  Open your browser and navigate to the same URL.
diff --git a/docs/CUSTOM_APP_REGISTRATION.md b/docs/CUSTOM_APP_REGISTRATION.md
@@ -16,12 +16,21 @@ App registration is a free service, but you may need to provide a credit card fo
 
 - Navigate to the [Azure portal > App registrations](https://portal.azure.com/#view/Microsoft_AAD_RegisteredApps/ApplicationsListBlade)
   - Click on `New registration` and fill in the details
+    | ![image](https://github.com/user-attachments/assets/c9c8bb37-4ce5-40a9-a975-f0bf8fb08bbe) |
+    |:-:|
   - Name: `Semantic Workbench` (or any name you prefer)
   - Supported account types: `Accounts in any organizational directory and personal Microsoft accounts`
+    | ![image](https://github.com/user-attachments/assets/703f8611-369d-43cf-b9b9-199f1c1e0e03) |
+    |:-:|
   - Redirect URI: `Single-page application (SPA)` & `https://<YOUR_HOST>`
     - Example (if using [Codespaces](../.devcontainer/README.md)): `https://<YOUR_CODESPACE_HOST>-4000.app.github.dev`
+    - If you don't have a website deployed yet, enter `https://localhost:5001`, you can configure this later.
+    - Note: the same Entra App can be reused for multiple websites, and multiple URLs can be added.
+      | ![Image](https://github.com/user-attachments/assets/e709ee12-a3ef-4be3-9f2d-46d33c929f42) |
+      |:-:|
   - Click on `Register`
-- View the `Overview` page for the newly registered app and copy the `Application (client) ID` for the next steps
+- View the `Overview` page for the newly registered app and copy the `Application (client) ID` for the next steps.
+- You can return to the list of your Entra apps from [here](https://portal.azure.com/#view/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/~/RegisteredApps).
 
 ## Update your app and service files with the new app registration details