paulasilvatech Backstage Authentication Conventions
These instructions apply to Backstage authentication and identity wiring. They are authoritative for provider separation, resolver mapping, callbacks, secret handling, and auth-to-permission boundaries in matched files; deployment security policy and current provider documentation win on conflict.
Identity and Provider Boundaries
- Choose one normal sign-in identity even when several providers offer delegated access.
- Map provider identities to catalog users through explicit resolvers.
- Keep GitHub or Microsoft technical integration credentials separate from user sign-in.
- Use the auth and HTTP auth services for backend credentials and request authentication.
- Enforce authorization through the permission framework after authentication.
GitHub and Microsoft Entra ID
- GitHub callbacks end at
/api/auth/github/handler/frame. - Microsoft callbacks end at
/api/auth/microsoft/handler/frame. - Use the GitHub provider module or Microsoft provider module matching the target version.
- Store client secret, tenant ID, and provider credentials in environment or secret storage.
- Request only required delegated scopes and document admin-consent requirements.
Conventions
| Rule | Rationale |
|---|---|
| Test unmapped and denied identities. | Happy-path login does not prove resolver safety. |
| Keep guest access environment-gated. | Development convenience must not leak into production. |
| Protect backend and frontend exposure independently. | A sign-in page alone does not protect the frontend bundle. |
Do / Do Not
| Do | Do not |
|---|---|
| Validate callback, logout, session, and resolver behavior. | Guess catalog identity mappings. |
| Keep secrets external and redacted. | Commit OAuth or Entra credentials. |
| Apply permissions after identity. | Treat profile claims as authorization. |
Checklist Before Opening a PR
- Sign-in and delegated provider access are separate.
- Resolver choice and catalog identity mapping are tested.
- Callback URLs and environment selection match deployment.
- Provider secrets and scopes are least-privilege and external.
- Guest, unmapped, expired, and denied paths are covered.
- Production identity changes received approval.