Cheat notes · Module 05 · The portal and its catalog

Sign in with GitHub

A five-minute review for when you have done this module and want it back in your head. Open the full module for the steps and the lab, or the full text to print.

The idea

Sign-in turns a GitHub login into a catalog User, and the User into groups. The resolver is the lock: no matching User entity, no sign-in. The catalog is the source of who you are.

Remember

Auth provider: a backend module that talks to an identity provider, configured under auth.providers.<name>.<environment> (auth.environment picks which).
Sign-in resolver: maps the provider identity to a User entity. usernameMatchingUserEntityName looks for a User named like the GitHub username.
Ownership entities: the user plus the groups they are a member of, put in the token. "Owned" filters and permissions read them.
OAuth callback on port 7007: http://localhost:7007/api/auth/github/handler/frame. The backend finishes the flow.
Swap the sign-in page with a frontend module: createFrontendModule({ pluginId: 'app', extensions: [SignInPageBlueprint.make(...)] }), added to features in App.tsx.
A door, not a lock: with the allow-all permission policy every signed-in user can still do everything.

Pitfalls

Renaming a User in org.yaml to a "nicer" name: the next sign-in fails with unable to resolve user identity. Import users with an org provider and review org.yaml with CODEOWNERS.
Debugging OAuth first when login breaks. Most login problems are catalog problems: a missing, renamed or unimported User.
Forgetting to restart: the portal reads new environment variables only at start.

Commands

`backend.add(import('@backstage/plugin-auth-backend-module-github-provider'));`	Add the GitHub provider to the backend
`curl -s -H "Authorization: Bearer $PORTAL_API_TOKEN" "localhost:7007/api/catalog/entities?filter=kind=user" \| jq -r '.[].metadata.name'`	The User names sign-in can resolve to

The provider and its resolver

auth:
  environment: development
  providers:
    github:
      development:
        clientId: ${AUTH_GITHUB_CLIENT_ID}
        clientSecret: ${AUTH_GITHUB_CLIENT_SECRET}
        signIn:
          resolvers:
            - resolver: usernameMatchingUserEntityName

Test yourself

Answer in your head first, then open the answer.

What does the sign-in resolver decide?

Which catalog User a provider identity becomes, and so whether the person may sign in at all.

Why is the OAuth callback URL on port 7007?

The auth backend plugin finishes the OAuth flow, and the backend listens on 7007.

How did you replace the sign-in page?

With a frontend module that overrides the app plugin's sign-in page extension.

Where module 05 leaves you: The portal only lets in people who have a User entity. You sign in with GitHub and the portal knows you are in platform and team-checkout.