Authentication

In this lesson, you’ll learn how to secure your Backstage instance by integrating with external identity providers. By default, Backstage allows guest access, but you can restrict sign-in to authorized users only.

Default Guest Access

Supported Identity Providers

Backstage natively supports multiple OAuth and SAML providers. After configuration, users will see additional Sign in buttons on the login page.

Authentication Workflow Overview

Below is a high-level OAuth 2.0 flow using GitHub as an example:

1. The user is already logged into GitHub (e.g., john) in their browser.
2. They visit Backstage and click Sign in with GitHub.
3. Backstage requests the GitHub username and receives john.
4. Backstage checks its catalog for a User entity named john.
5. If found, the login succeeds; otherwise, it fails.

When no matching entity exists, you’ll encounter:

Error: login failed, no user named john

Defining a Matching User Entity

To allow john to authenticate, add a User entity in your catalog with matching metadata:

apiVersion: backstage.io/v1alpha1
kind: User
metadata:
  name: john
spec:
  profile:
    displayName: John Doe
    email: [email protected]
    memberOf:
      - team-b
      - employees

Once imported, john can sign in with GitHub without errors.

Automating User Import

Maintaining user entities by hand doesn’t scale. Backstage can synchronize users from:

• GitHub organizations
• LDAP directories
• Enterprise identity platforms (Okta, Azure AD)

Automated import ensures that your catalog always includes up-to-date user entries before any login attempts occur.

Links and References

• Backstage Authentication Docs
• OAuth 2.0 Guide
• GitHub OAuth Apps