From 31e8cbcfa8a32eee62ecabed5ddbed741c58c56c Mon Sep 17 00:00:00 2001
From: Patrik Oldsberg <poldsberg@gmail.com>
Date: Mon, 2 May 2022 18:07:07 +0200
Subject: [PATCH] docs/auth: add proxied sign-in page selection

Signed-off-by: Patrik Oldsberg <poldsberg@gmail.com>
---
 docs/auth/index.md | 50 +++++++++++++++++++++++++++++++++++++++-------
 1 file changed, 43 insertions(+), 7 deletions(-)

diff --git a/docs/auth/index.md b/docs/auth/index.md
index cb79873360..32b9a12b39 100644
--- a/docs/auth/index.md
+++ b/docs/auth/index.md
@@ -139,15 +139,51 @@ All the sign-in page needs to do is to call the `/refresh` endpoint of the auth
 to get the existing session, which is exactly what the `ProxiedSignInPage` does. The only
 thing you need to do to configure the `ProxiedSignInPage` is to pass the ID of the provider like this:
 
-```diff
- const app = createApp({
-   apis,
-+  components: {
-+    SignInPage: props => <ProxiedSignInPage {...props} provider="awsalb" />,
-+  },
-   bindRoutes({ bind }) {
+```tsx
+const app = createApp({
+  ...,
+  components: {
+    SignInPage: props => <ProxiedSignInPage {...props} provider="awsalb" />,
+  },
+});
 ```
 
+A downside of this method is that it can be cumbersome to set up for local development.
+As a workaround for this, it's possible to dynamically select the sign-in page based on
+what environment the app is running in, and then use a different sign-in method for local
+development, if one is needed at all. Depending on the exact setup, one might choose to
+select the sign-in method based on the `process.env.NODE_ENV` environment variable,
+by checking the `hostname` of the current location, or by accessing the configuration API
+to read a configuration value. For example:
+
+```tsx
+const app = createApp({
+  ...,
+  components: {
+    SignInPage: props => {
+      const configApi = useApi(configApiRef);
+      if (configApi.getString('auth.environment') === 'development') {
+        return (
+          <SignInPage
+            {...props}
+            provider={{
+              id: 'google-auth-provider',
+              title: 'Google',
+              message: 'Sign In using Google',
+              apiRef: googleAuthApiRef,
+            }}
+          />
+        );
+      }
+      return <ProxiedSignInPage {...props} provider="gcpiap" />;
+    },
+  },
+});
+```
+
+When using multiple auth providers like this, it's important that you configure the different
+sign-in resolvers so that they resolve to the same identity regardless of the method used.
+
 ## For Plugin Developers
 
 The Backstage frontend core APIs provide a set of Utility APIs for plugin developers