docs: add section describing ProxiedSignInPage

Signed-off-by: Patrik Oldsberg <poldsberg@gmail.com>

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

@@ -91,23 +91,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';
@@ -117,5 +102,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

@@ -126,6 +126,28 @@ 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:
+
+```diff
+ const app = createApp({
+   apis,
++  components: {
++    SignInPage: props => <ProxiedSignInPage {...props} provider="awsalb" />,
++  },
+   bindRoutes({ bind }) {
+```
+
 ## For Plugin Developers
 
 The Backstage frontend core APIs provide a set of Utility APIs for plugin developers

docs/auth/oauth2-proxy/provider.md

@@ -81,25 +81,15 @@ When using `oauth2proxy` auth you can configure it as described
 
 ## 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.