message: docs/auth: update oauth2-proxy docs
diff: @@ -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;
  -```
  -
  -## 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).
  +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.
  -- 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,
  - },
  - };
  - },
  +providers.oauth2Proxy.create({
  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`] },
  + 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 },
  });
  -
  - return { id, token };
  },
  },
  }),
  - }
  ```
  ## Adding the provider to the Backstage frontend
  