Merge pull request #11217 from backstage/rugvip/proxydocs

docs: add section describing ProxiedSignInPage

docs/auth/google/gcp-iap-auth.md

@@ -90,23 +90,8 @@ sign-in mechanism to poll that endpoint through the IAP, on the user's behalf.
 
 ## Frontend Changes
 
-All Backstage apps need a `SignInPage` to be configured. Its purpose is to
-establish who the user is and what their identifying credentials are, blocking
-rendering the rest of the UI until that's complete, and then keeping those
-credentials fresh.
-
-When using IAP Proxy authentication, the Backstage UI will only be loaded once
-the user has already successfully completely authenticated themselves with the
-IAP and has an active session, so we don't want to make the user have to go
-through a _second_ layer of authentication flows after that.
-
-As such, we want to not display a sign-in page visually at all. Instead, we will
-pick a `SignInPage` implementation component which knows how to silently make
-requests to the backend provider we configured above, and just trusting its
-output to properly represent the current user. Luckily, Backstage comes with a
-component for this purpose out of the box.
-
-Update your `createApp` call in `packages/app/src/App.tsx`, as follows.
+It is recommended to use the `ProxiedSignInPage` for this provider, which is
+installed in `packages/app/src/App.tsx` like this:
 
 ```diff
 +import { ProxiedSignInPage } from '@backstage/core-components';
@@ -116,5 +101,4 @@ Update your `createApp` call in `packages/app/src/App.tsx`, as follows.
 +    SignInPage: props => <ProxiedSignInPage {...props} provider="gcp-iap" />,
 ```
 
-After this, your app should be ready to leverage the Identity-Aware Proxy for
-authentication!
+See the [Sign-In with Proxy Providers](../index.md#sign-in-with-proxy-providers) section for more information.

docs/auth/index.md

@@ -127,6 +127,64 @@ allows allowing guest access:
    bindRoutes({ bind }) {
 ```
 
+## Sign-In with Proxy Providers
+
+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),
+[GCP IAP](./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.
+All the sign-in page needs to do is to call the `/refresh` endpoint of the auth providers
+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:
+
+```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

docs/auth/oauth2-proxy/provider.md

@@ -57,25 +57,15 @@ providers.oauth2Proxy.create({
 
 ## Adding the provider to the Backstage frontend
 
-All Backstage apps need a `SignInPage` to be configured. Its purpose is to
-establish who the user is and what their identifying credentials are, blocking
-rendering the rest of the UI until that's complete, and then keeping those
-credentials fresh.
-
-When using the OAuth2-Proxy, the Backstage UI can only be accessed after the
-user has already been authenticated at the proxy. Instead of showing the user
-another login page when accessing Backstage, it will handle the login in the
-background. Backstage provides for this case the `ProxiedSignInPage` component
-which has no UI.
-
-Update your `createApp` call in `packages/app/src/App.tsx`, as follows.
+It is recommended to use the `ProxiedSignInPage` for this provider, which is
+installed in `packages/app/src/App.tsx` like this:
 
 ```diff
 +import { ProxiedSignInPage } from '@backstage/core-components';
+
  const app = createApp({
    components: {
 +    SignInPage: props => <ProxiedSignInPage {...props} provider="oauth2proxy" />,
 ```
 
-After this, your app should be ready to leverage the OAuth2-Proxy for
-authentication!
+See the [Sign-In with Proxy Providers](../index.md#sign-in-with-proxy-providers) section for more information.