From 8c8d36b967fcf15b6fa1d9deb05ab03ce7732592 Mon Sep 17 00:00:00 2001
From: Vincenzo Scamporlino <vincenzos@spotify.com>
Date: Fri, 10 May 2024 20:02:03 +0200
Subject: [PATCH] docs: improve github auth providers

Signed-off-by: Vincenzo Scamporlino <vincenzos@spotify.com>
---
 docs/auth/github/provider.md | 16 +++++++++++-----
 1 file changed, 11 insertions(+), 5 deletions(-)

diff --git a/docs/auth/github/provider.md b/docs/auth/github/provider.md
index 2c3aaeaf7d..4accc7841b 100644
--- a/docs/auth/github/provider.md
+++ b/docs/auth/github/provider.md
@@ -43,13 +43,12 @@ auth:
         # enterpriseInstanceUrl: ${AUTH_GITHUB_ENTERPRISE_INSTANCE_URL}
         signIn:
           resolvers:
-            # typically you would pick one of these
-            - resolver: emailMatchingUserEntityProfileEmail
-            - resolver: emailLocalPartMatchingUserEntityName
+            # Matches the GitHub username with the Backstage user entity name.
+            # See https://backstage.io/docs/auth/github/provider#resolvers for more resolvers.
             - resolver: usernameMatchingUserEntityName
 ```
 
-The GitHub provider is a structure with three configuration keys:
+The GitHub provider is a structure with five configuration keys:
 
 - `clientId`: The client ID that you generated on GitHub, e.g.
   `b59241722e3c3b4816e2`
@@ -60,6 +59,9 @@ The GitHub provider is a structure with three configuration keys:
   initiating an OAuth flow, e.g.
   `https://your-intermediate-service.com/handler`. Only needed if Backstage is
   not the immediate receiver (e.g. one OAuth app for many backstage instances).
+- `signIn`: The configuration for the sign-in process, including the **resolvers**
+  that should be used to match the user from the auth provider with the user
+  entity in the Backstage catalog (typically a single resolver is sufficient).
 
 ### Resolvers
 
@@ -69,7 +71,11 @@ This provider includes several resolvers out of the box that you can use:
 - `emailLocalPartMatchingUserEntityName`: Matches the [local part](https://en.wikipedia.org/wiki/Email_address#Local-part) of the email address from the auth provider with the User entity that has a matching `name`. If no match is found it will throw a `NotFoundError`.
 - `usernameMatchingUserEntityName`: Matches the username from the auth provider with the User entity that has a matching `name`. If no match is found it will throw a `NotFoundError`.
 
-> Note: The resolvers will be tried in order, but will only be skipped if they throw a `NotFoundError`.
+:::note
+
+The resolvers will be tried in order, but will only be skipped if they throw a `NotFoundError`.
+
+:::
 
 If these resolvers do not fit your needs you can build a custom resolver, this is covered in the [Building Custom Resolvers](../identity-resolver.md#building-custom-resolvers) section of the Sign-in Identities and Resolvers documentation.