create-app,docs: use guest resolver as default sign-in resolver in new apps

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

.changeset/twenty-avocados-refuse.md

@@ -0,0 +1,5 @@
+---
+'@backstage/create-app': patch
+---
+
+Updated the auth backend setup in the template to include a guest sign-in resolver in order to make it quicker to get up and running with a basic sign-in setup. There is no need to update existing apps to match this change, but in case you want to use the guest sign-in resolver you can find it at https://backstage.io/docs/auth/identity-resolver#guest-sign-in-resolver

docs/auth/identity-resolver.md

@@ -12,6 +12,34 @@ If you want to use an auth provider to sign in users, you need to explicitly con
 it have sign-in enabled and also tell it how the external identities should
 be mapped to user identities within Backstage.
 
+## Guest Sign-In Resolver
+
+Backstage projects created with `npx @backstage/create-app` come configured with a
+sign-in resolver for GitHub guest access. This resolver makes all users share
+a single "guest" identity and is only intended as a minimum requirement to quickly
+get up and running. You can replace `github` for any of the other providers if you need.
+
+This resolver should not be used in production, as it uses a single shared identity,
+and has no restrictions on who is able to sign-in. Be sure to read through the rest
+of this page to understand the Backstage identity system once you need to install
+a resolver for your production environment.
+
+The guest resolver can be useful for testing purposes too, and it looks like this:
+
+```ts
+signIn: {
+  resolver(_, ctx) {
+    const userRef = 'user:default/guest'
+    return ctx.issueToken({
+      claims: {
+        sub: userRef,
+        ent: [userRef],
+      },
+    }),
+  },
+},
+```
+
 ## Backstage User Identity
 
 A user identity within Backstage is built up from two pieces of information, a

packages/create-app/templates/default-app/packages/backend/src/plugins/auth.ts

@@ -18,18 +18,36 @@ export default async function createPlugin(
     providerFactories: {
       ...defaultAuthProviderFactories,
 
-      // This overrides the default GitHub auth provider with a custom one.
-      // Since the options are empty it will behave just like the default
-      // provider, but if you uncomment the `signIn` section you will enable
-      // sign-in via GitHub. This particular configuration uses a resolver
-      // that matches the username to the user entity name. See the auth
-      // documentation for more details on how to enable and customize sign-in:
+      // This replaces the default GitHub auth provider with a customized one.
+      // The `signIn` option enables sign-in for this provider, using the
+      // identity resolution logic that's provided in the `resolver` callback.
+      //
+      // This particular resolver makes all users share a single "guest" identity.
+      // It should only be used for testing and trying out Backstage.
+      //
+      // If you want to use a production ready resolver you can switch to the
+      // the one that is commented out below, it looks up a user entity in the
+      // catalog using the GitHub username of the authenticated user.
+      // That resolver requires you to have user entities populated in the catalog,
+      // for example using https://backstage.io/docs/integrations/github/org
+      //
+      // There are other resolvers to choose from, and you can also create
+      // your own, see the auth documentation for more details:
       //
       //   https://backstage.io/docs/auth/identity-resolver
       github: providers.github.create({
-        // signIn: {
-        //   resolver: providers.github.resolvers.usernameMatchingUserEntityName(),
-        // },
+        signIn: {
+          resolver(_, ctx) {
+            const userRef = 'user:default/guest'; // Must be a full entity reference
+            return ctx.issueToken({
+              claims: {
+                sub: userRef, // The user's own identity
+                ent: [userRef], // A list of identities that the user claims ownership through
+              },
+            });
+          },
+          // resolver: providers.github.resolvers.usernameMatchingUserEntityName(),
+        },
       }),
     },
   });