Microsoft authentication doc clafications

* Add API Permissions to the app registration setup
* Encouraged re-use of an existing app registration over creating a new one.
* Moved the `Adding the provider to the Backstage front end` higher up so it's not so easily missed

Updated the microsoft authentication document to include details on adding API Permissions.
At more relaxed companies, these permissiosn will be silently added to this list the first time they're requested, however in more locked down companies, a directory admin will need to consent to these permissions before users can use them.

Also slighlty reworked the docs to encourate re-using any existing app registration.  This includes renaming the `AUTH_MICROSOFT_*` variables to match the `AZURE_*` ones used throughout other azure integrations.

Signed-off-by: Alex Crome <afscrome@users.noreply.github.com>

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**: `http://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_ID}
+        tenantId: ${AZURE_TENANT_ID}
 ```
 
 The Microsoft provider is a structure with three configuration keys:
@@ -46,6 +61,12 @@ The Microsoft provider is a structure with three configuration keys:
 - `clientSecret`: Secret, found on App Registration > Certificates & secrets
 - `tenantId`: Directory (tenant) ID, found on App Registration > Overview
 
+## 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
@@ -58,9 +79,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).