docs/auth: update oauth2-proxy docs

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

docs/auth/oauth2-proxy/provider.md

@@ -20,63 +20,39 @@ The provider configuration can be added to your `app-config.yaml` under the root
 
 ```yaml
 auth:
-  environment: development
   providers:
     oauth2proxy: {}
 ```
 
-Right now no configuration options are supported. To make use of the provider,
-make sure that your `oauth2-proxy` is configured correctly and provides a custom
-`X-OAUTH2-PROXY-ID-TOKEN` header. To do so, enable the
-`--set-authorization-header=true` of your `oauth2-proxy` and forward the
-`Authorization` header as `X-OAUTH2-PROXY-ID-TOKEN`. For more details check the
-[configuration docs](https://oauth2-proxy.github.io/oauth2-proxy/configuration).
+Right now no configuration options are supported, but the empty object is needed
+to enable the provider in the auth backend.
 
-_Example for kubernetes ingress:_
+To use the `oauth2proxy` provider you must also configure it with a sign-in resolver.
+For more information about the sign-in process in general, see the
+[Sign-in Identities and Resolvers](../identity-resolver.md) documentation.
 
-```bash
-# forward the authorization header from the auth request in the X-OAUTH2-PROXY-ID-TOKEN header
-auth_request_set $name_upstream_authorization $upstream_http_authorization;
-proxy_set_header X-OAUTH2-PROXY-ID-TOKEN $name_upstream_authorization;
-```
+For the `oauth2proxy` provider, the sign-in result is quite different than other providers.
+Because it's a proxy provider that can be configured to forward information through
+arbitrary headers, the auth result simply just gives you access to the HTTP headers
+of the incoming request. Using these you can either extract the information directly,
+or grab ID or access tokens to look up additional information and/or validate the request.
 
-## Adding the provider to the Backstage backend
-
-When using `oauth2proxy` auth you can configure it as described
-[here](https://backstage.io/docs/auth/identity-resolver).
-
-- use the following code below to introduce changes to
-  `packages/backend/plugin/auth.ts`:
+A simple sign-in resolver might for example look like this:
 
 ```ts
-  providerFactories: {
-    oauth2proxy: createOauth2ProxyProvider<{
-      id: string;
-      email: string;
-    }>({
-      authHandler: async input => {
-        const { email } = input.fullProfile;
-
-        return {
-          profile: {
-            email,
-          },
-        };
-      },
-      signIn: {
-        resolver: async (signInInfo, ctx) => {
-          const { preferred_username: id } = signInInfo.result.fullProfile;
-          const sub = `user:default/${id}`;
-
-          const token = await ctx.tokenIssuer.issueToken({
-            claims: { sub, ent: [`group:default/optional-user-group`] },
-          });
-
-          return { id, token };
-        },
-      },
-    }),
-  }
+providers.oauth2Proxy.create({
+  signIn: {
+    async resolver({ result }, ctx) {
+      const name = result.getHeader('x-forwarded-user');
+      if (!name) {
+        throw new Error('Request did not contain a user')
+      }
+      return ctx.signInWithCatalogUser({
+        entityRef: { name },
+      });
+    },
+  },
+}),
 ```
 
 ## Adding the provider to the Backstage frontend