Merge pull request #18323 from afscrome/easyauthdocs

Improve Easy Auth Docs

docs/auth/index.md

@@ -143,8 +143,11 @@ const app = createApp({
 
 Some auth providers are so-called "proxy" providers, meaning they're meant to be used
 behind an authentication proxy. Examples of these are
-[AWS ALB](https://github.com/backstage/backstage/blob/master/contrib/docs/tutorials/aws-alb-aad-oidc-auth.md), [Cloudflare Access](./cloudflare/access.md),
-[GCP IAP](./google/gcp-iap-auth.md), and [OAuth2 Proxy](./oauth2-proxy/provider.md).
+[Amazon Application Load Balancer](https://github.com/backstage/backstage/blob/master/contrib/docs/tutorials/aws-alb-aad-oidc-auth.md),
+[Azure EasyAuth](./microsoft/azure-easyauth.md),
+[Cloudflare Access](./cloudflare/access.md),
+[Google Identity-Aware Proxy](./google/gcp-iap-auth.md)
+and [OAuth2 Proxy](./oauth2-proxy/provider.md).
 
 When using a proxy provider, you'll end up wanting to use a different sign-in page, as
 there is no need for further user interaction once you've signed in towards the proxy.

docs/auth/microsoft/azure-easyauth.md

@@ -11,6 +11,14 @@ The Backstage `core-plugin-api` package comes with a Microsoft authentication pr
 
 Add the following into your `app-config.yaml` or `app-config.production.yaml` file
 
+```yaml
+auth:
+  environment: development
+  providers:
+    azure-easyauth:
+      development: {}
+```
+
 Add a `providerFactories` entry to the router in
 `packages/backend/src/plugins/auth.ts`.
 
@@ -59,8 +67,10 @@ sign-in mechanism to poll that endpoint through the IAP, on the user's behalf.
 
 ## Frontend Changes
 
-It is recommended to use the `ProxiedSignInPage` for this provider, which is
-installed in `packages/app/src/App.tsx` like this:
+To use this component, you'll need to configure the app's `SignInPage`.
+It is recommended to use the `ProxiedSignInPage` for this provider when running in Azure, However for local development (or any other scenario running outside of Azure), you'll want to set up something different.
+For the closest experience to Easy Auth, you could set up the `microsoft` provider locally, but that will requires setting up App Registrations & secrets which may be locked down by your organisation, in which case it may be easier to use guest login locally.
+See [Sign-In with Proxy Providers](../index.md#sign-in-with-proxy-providers) for more details.
 
 ```tsx title="packages/app/src/App.tsx"
 /* highlight-add-next-line */
@@ -69,17 +79,26 @@ import { ProxiedSignInPage } from '@backstage/core-components';
 const app = createApp({
   /* highlight-add-start */
   components: {
-    SignInPage: props => (
-      <ProxiedSignInPage {...props} provider="azure-easyauth" />
-    ),
+    SignInPage: props => {
+      const configApi = useApi(configApiRef);
+      if (configApi.getString('auth.environment') !== 'development')
+        return <ProxiedSignInPage {...props} provider="azure-easyauth" />;
+      }
+      return (
+        <SignInPage
+          {...props}
+          providers={['guest', 'custom']}
+          title="Select a sign-in method"
+          align="center"
+        />
+      );
+    },
   },
   /* highlight-add-end */
   // ..
 });
 ```
 
-See the [Sign-In with Proxy Providers](../index.md#sign-in-with-proxy-providers) section for more information.
-
 ## Azure Configuration
 
 How to configure azure depends on the service you're enable AAD auth on the app service.