diff --git a/docs/getting-started/configuration.md b/docs/getting-started/configuration.md index 7c7fa4d98f..286c6cff1e 100644 --- a/docs/getting-started/configuration.md +++ b/docs/getting-started/configuration.md @@ -189,79 +189,7 @@ components: { }, ``` -### Add sign-in resolver in the backend - -The Auth backend plugin is responsible for assigning a [Backstage User Identity](../auth/identity-resolver.md#backstage-user-identity) when a user signs in. The Backstage User Identity is fundamentally a JSON Web Token which consists of two parts. The `sub` part is your identity and that identifies your user for any purpose within the Backstage ecosystem. It can for example be used as a primary key in a per-user settings backend, or any other similar purpose. The ent is what relates to ownership (the list of entity refs through which you claim ownership). This is achieved by writing a [Sign In Resolver](../auth/identity-resolver.md#sign-in-resolvers) which takes care of assigning the right identity to the user and even reject SignIn attempts from unrecognized email domains. - -> Since [v1.1.0](https://github.com/backstage/backstage/releases/tag/v1.1.0-next.3), you must provide an [explicit sign-in resolver](../auth/identity-resolver.md). - -For now, let's create a simple Sign In Resolver which uses the first part of the user's email address to assign a Backstage User Identity. - -Replace your `packages/backend/src/plugin/auth.ts` file with the following. - -> NOTE: Please update `acme.org` below with your actual company domain to allow login requests from email address with that domain. - -```tsx -import { - createRouter, - providers, - defaultAuthProviderFactories, -} from '@backstage/plugin-auth-backend'; -import { Router } from 'express'; -import { PluginEnvironment } from '../types'; -import { - DEFAULT_NAMESPACE, - stringifyEntityRef, -} from '@backstage/catalog-model'; - -export default async function createPlugin( - env: PluginEnvironment, -): Promise { - return await createRouter({ - logger: env.logger, - config: env.config, - database: env.database, - discovery: env.discovery, - tokenManager: env.tokenManager, - providerFactories: { - ...defaultAuthProviderFactories, - github: providers.github.create({ - signIn: { - resolver: async ({ profile }, ctx) => { - if (!profile.email) { - throw new Error( - 'Login failed, user profile does not contain an email', - ); - } - // Split the email into the local part and the domain. - const [localPart, domain] = profile.email.split('@'); - - // Next we verify the email domain. It is recommended to include this - // kind of check if you don't look up the user in an external service. - if (domain !== 'acme.org') { - throw new Error('Login failed, user email domain check failed'); - } - - // By using `stringifyEntityRef` we ensure that the reference is formatted correctly - const userEntityRef = stringifyEntityRef({ - kind: 'User', - name: localPart, - namespace: DEFAULT_NAMESPACE, - }); - - return ctx.issueToken({ - claims: { - sub: userEntityRef, - ent: [userEntityRef], - }, - }); - }, - }, - }), - }, - }); -} -``` +> Note: The default Backstage app comes with a guest Sign In Resolver. 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 read more about how [Sign In Resolvers](../auth/identity-resolver.md#sign-in-resolvers) play a role in creating a [Backstage User Identity](../auth/identity-resolver.md#backstage-user-identity) for logged in users. Restart Backstage from the terminal, by stopping it with `Control-C`, and starting it with `yarn dev` . You should be welcomed by a login prompt!