Add SSO through the existing Keycloak instance #32

Open
opened 2026-11-08 15:11:03 +00:00 by martin · 0 comments
Owner

Summary

Enable single sign-on to Backstage through the user's existing Keycloak instance, replacing guest access in the hosted environment with authenticated user identities.

Context

  • Repository guidance describes Backstage 1.55 with guest authentication for local development.
  • #30 already requires an identity provider and mapping sign-in to catalog users before secure hosted deployment. This issue delivers the Keycloak SSO portion rather than duplicating the broader deployment work.
  • The Keycloak realm, issuer URL, client settings, and intended Backstage URLs have not been specified here; confirm the existing instance and environment-specific values during implementation.

Scope

  • Integrate Keycloak using an OpenID Connect authentication provider compatible with the repository's Backstage backend and frontend systems.
  • Define the required Keycloak client configuration, allowed callback URLs, and requested claims/scopes for the intended environments.
  • Map authenticated Keycloak identities to the intended Backstage catalog users using a documented, deterministic sign-in rule. Reject identities that cannot be safely matched.
  • Disable guest sign-in in the hosted environment and keep any local-development guest mode explicitly separate.
  • Supply any required client secret through the existing deployment secret-management approach, keeping it backend-side and out of source control and logs.
  • Test and document sign-in, session handling, sign-out, and troubleshooting.

Out of scope

  • Deploying a new Keycloak instance or replacing the existing one.
  • Implementing the entire hosted deployment or a complete authorization policy for catalog data and scaffolder actions; those remain covered by #30 or separately scoped work. SSO alone does not establish authorization.

Acceptance criteria

  • An authorized user can sign in to Backstage through the existing Keycloak instance and receives the expected Backstage catalog identity.
  • The realm/issuer, client configuration, exact callback URLs, and identity-mapping rule are documented without exposing credentials.
  • Invalid or unmapped identities are rejected, and hosted guest sign-in cannot bypass authentication.
  • Any required client secret is provided securely to the backend and is absent from committed files, browser-delivered configuration, and logs.
  • Hosted authentication uses encrypted transport and redirects only to the intended Backstage URLs.
  • Sign-in failures, session expiry, and sign-out are tested; the distinction between ending a Backstage session and ending the Keycloak SSO session is documented.
  • Relevant frontend/backend tests and repository validation checks pass; automated tests do not require production credentials.

Dependencies

  • Prerequisite for #30's authenticated hosted deployment: supplies its Keycloak identity-provider and sign-in integration. Broader authorization and deployment requirements remain in #30.
## Summary Enable single sign-on to Backstage through the user's existing Keycloak instance, replacing guest access in the hosted environment with authenticated user identities. ## Context - Repository guidance describes Backstage 1.55 with guest authentication for local development. - #30 already requires an identity provider and mapping sign-in to catalog users before secure hosted deployment. This issue delivers the Keycloak SSO portion rather than duplicating the broader deployment work. - The Keycloak realm, issuer URL, client settings, and intended Backstage URLs have not been specified here; confirm the existing instance and environment-specific values during implementation. ## Scope - Integrate Keycloak using an OpenID Connect authentication provider compatible with the repository's Backstage backend and frontend systems. - Define the required Keycloak client configuration, allowed callback URLs, and requested claims/scopes for the intended environments. - Map authenticated Keycloak identities to the intended Backstage catalog users using a documented, deterministic sign-in rule. Reject identities that cannot be safely matched. - Disable guest sign-in in the hosted environment and keep any local-development guest mode explicitly separate. - Supply any required client secret through the existing deployment secret-management approach, keeping it backend-side and out of source control and logs. - Test and document sign-in, session handling, sign-out, and troubleshooting. ## Out of scope - Deploying a new Keycloak instance or replacing the existing one. - Implementing the entire hosted deployment or a complete authorization policy for catalog data and scaffolder actions; those remain covered by #30 or separately scoped work. SSO alone does not establish authorization. ## Acceptance criteria - [ ] An authorized user can sign in to Backstage through the existing Keycloak instance and receives the expected Backstage catalog identity. - [ ] The realm/issuer, client configuration, exact callback URLs, and identity-mapping rule are documented without exposing credentials. - [ ] Invalid or unmapped identities are rejected, and hosted guest sign-in cannot bypass authentication. - [ ] Any required client secret is provided securely to the backend and is absent from committed files, browser-delivered configuration, and logs. - [ ] Hosted authentication uses encrypted transport and redirects only to the intended Backstage URLs. - [ ] Sign-in failures, session expiry, and sign-out are tested; the distinction between ending a Backstage session and ending the Keycloak SSO session is documented. - [ ] Relevant frontend/backend tests and repository validation checks pass; automated tests do not require production credentials. ## Dependencies - Prerequisite for #30's authenticated hosted deployment: supplies its Keycloak identity-provider and sign-in integration. Broader authorization and deployment requirements remain in #30.
Sign in to join this conversation.
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Reference
Personal/backstage#32
No description provided.