Merge pull request #20666 from afscrome/aadadminconsent

Microsoft authentication doc clarifications

docs/auth/microsoft/provider.md

@@ -8,21 +8,36 @@ description: Adding Microsoft Azure as an authentication provider in Backstage
 The Backstage `core-plugin-api` package comes with a Microsoft authentication
 provider that can authenticate users using Azure OAuth.
 
-## Create an App Registration on Azure
+## Configure App Registration on Azure
 
-To support Azure authentication, you must create an App Registration:
+Depending on how locked down your company is, you may need a directory administrator to do some or all of these instructions.
 
-1. Log in to the [Azure Portal](https://portal.azure.com/)
-2. Create an
-   [Active Directory Tenant](https://portal.azure.com/#blade/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/Overview),
-   if one does not yet exist
-3. Navigate to
-   [Azure Active Directory > App Registrations](https://portal.azure.com/#blade/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/RegisteredApps)
-4. Register an application
-   - Name: Backstage (or your custom app name)
-   - Redirect URI: Web >
-     `http://localhost:7007/api/auth/microsoft/handler/frame`
-5. Navigate to **Certificates & secrets > New client secret** to create a secret
+Go to [Azure Portal > App registrations](https://portal.azure.com/#view/Microsoft_AAD_RegisteredApps/ApplicationsListBlade) and find your existing app registration, or create a new one.
+If you have an existing App Registration for Backstage, use that rather than create a new one.
+
+On your app registration's overview page, add a new `Web` platform configuration, with the configuration:
+
+- **Redirect URI**: `https://your-backstage.com/api/auth/microsoft/handler/frame` (for local dev, typically `http://localhost:7007/api/auth/microsoft/handler/frame`)
+- **Front-channel logout Url**: blank
+- **Implicit grant and hybrid flows**: All unchecked
+
+On the **API permissions** tab, click on `Add Permission`, then add the following `Delegated` permission for the `Microsoft Graph` API.
+
+- `email`
+- `offline_access`
+- `openid`
+- `profile`
+- `User.Read`
+
+Your company may require you to grant [admin consent](https://learn.microsoft.com/en-us/azure/active-directory/manage-apps/user-admin-consent-overview) for these permissions.
+Even if your company doesn't require admin consent, you may wish to do so as it means users don't need to individually consent the first time they access backstage.
+To grant admin consent, a directory admin will need to come to this page and click on the **Grant admin consent for COMPANY NAME** button.
+
+![App Registration Permissions](permissions.png)
+
+If you're using an existing app registration, and backstage already has a client secret, you can re-use that.
+If not, go to the **Certificates & Secrets** page, then the **Client secrets** tab and create a new client secret.
+Make a note of this value as you'll need it in the next section.
 
 ## Configuration
 
@@ -35,9 +50,9 @@ auth:
   providers:
     microsoft:
       development:
-        clientId: ${AUTH_MICROSOFT_CLIENT_ID}
-        clientSecret: ${AUTH_MICROSOFT_CLIENT_SECRET}
-        tenantId: ${AUTH_MICROSOFT_TENANT_ID}
+        clientId: ${AZURE_CLIENT_ID}
+        clientSecret: ${AZURE_CLIENT_SECRET}
+        tenantId: ${AZURE_TENANT_ID}
         domainHint: ${AZURE_TENANT_ID}
 ```
 
@@ -51,6 +66,12 @@ The Microsoft provider is a structure with three mandatory configuration keys:
   When specified, this reduces login friction for users with accounts in multiple tenants by automatically filtering away accounts from other tenants.
   For more details, see [Home Realm Discovery](https://learn.microsoft.com/en-us/azure/active-directory/manage-apps/home-realm-discovery-policy)
 
+## Adding the provider to the Backstage frontend
+
+To add the provider to the frontend, add the `microsoftAuthApiRef` reference and
+`SignInPage` component as shown in
+[Adding the provider to the sign-in page](../index.md#adding-the-provider-to-the-sign-in-page).
+
 ## Outbound Network Access
 
 If your environment has restrictions on outgoing access (e.g. through
@@ -63,9 +84,3 @@ hosts:
   in [this source
   code](https://github.com/seanfisher/passport-microsoft/blob/0456aa9bce05579c18e77f51330176eb26373658/lib/strategy.js#L93-L95)).
   If this host is unreachable, users may see an `Authentication failed, failed to fetch user profile` error when they attempt to log in.
-
-## Adding the provider to the Backstage frontend
-
-To add the provider to the frontend, add the `microsoftAuthApiRef` reference and
-`SignInPage` component as shown in
-[Adding the provider to the sign-in page](../index.md#adding-the-provider-to-the-sign-in-page).