paulasilvatech Backstage authentication
Configure authentication without confusing who the Backstage user is with which third-party APIs the application may call on that user's behalf.
When to invoke
- "Configure GitHub or Microsoft login in Backstage."
- "Fix an auth callback or sign-in resolver error."
- "Separate GitHub integration tokens from user sign-in."
- "Review whether guest auth is safe for this environment."
Identity boundaries
| Concern | Purpose |
|---|---|
| Sign-in provider | Establishes the Backstage user identity. |
| Sign-in resolver | Maps provider identity to a catalog user or approved identity. |
| Delegated access | Obtains provider credentials for user-authorized external API calls. |
| Technical integration | Lets catalog providers or backend modules access external systems. |
| Permission policy | Authorizes actions after identity is established. |
Procedure
- Detect repository mode, Backstage version, backend system, environment, and existing providers.
- Identify the desired sign-in identity and catalog user mapping.
- Identify delegated provider access and service integration credentials separately.
- Read current first-party auth documentation for the selected provider and target version.
- Configure the provider and backend module through supported APIs.
- Keep client secrets, private keys, and tokens in environment or approved secret storage.
- Validate base URLs, callback URLs, resolver behavior, session or token settings, and logout.
- Test successful login, denied or unmapped identity, expired credentials, and least-privilege permissions without logging secrets or tokens.
- Require approval before changing production sign-in identity or disabling authentication.
Built-in provider focus
- GitHub: use
@backstage/plugin-auth-backend-module-github-provider, configure the OAuth or GitHub App callback, and select a resolver such as username, email, or stable user ID mapping. - Microsoft Entra ID: use
@backstage/plugin-auth-backend-module-microsoft-provider, configure client ID, tenant ID, secret, redirect URI, required delegated scopes, and a stable resolver. - Keep GitHub App technical integration and Azure DevOps or Microsoft Graph technical credentials separate from either sign-in provider.
- Verify outbound access to provider identity endpoints and test admin-consent requirements.
Limits
- Guest auth is for explicitly approved development or trusted scenarios, not a silent production fallback.
- A provider's profile or email claim is not authorization.
- Do not invent resolver behavior when catalog ownership or identity mapping is unknown.
Output template
## Backstage authentication result
**Provider:** <provider>
**Environment:** <environment>
**Identity source:** <source>
**Resolver:** <resolver and mapping>
| Check | Expected | Result |
| --- | --- | --- |
### External secrets
- `<ENV_NAME>`: <purpose only>
Quality gate
- Sign-in, delegation, integration credentials, and permission policy are separated.
- Provider and resolver behavior matches current first-party guidance.
- Callback and base URLs match the environment.
- Secrets remain external and absent from logs.
- Positive and negative sign-in paths are validated.
- Production auth mutations are explicitly approved.