WBSP
ProvidersWikiSign in
All pages

WBSP Single-Tenant & SSO Guidelines

These guidelines are normative for WBSP application projects. They describe how WBSP applications are tenanted and how users sign in across them. They complement wbsp-client-guidelines.md — see its Authentication section.

Authentication and shared sign-on implementation belongs to the Headless Auth Platform (HAP) project. Its guidelines are the source of truth and are expected to evolve — refer to them (via your platform operator, or the HAP section of this wiki); do not duplicate them here.

1. Single-tenant by preference

A core WBSP objective is that a user can run their own instance of an application rather than sharing a multi-tenanted, centrally-hosted SaaS. The WBSP preference is therefore single-tenanted: a deployment serves one user/organisation, with its own data and its own lifecycle.

  • Prefer single-tenant: design for one tenant per deployment, and do not assume many unrelated tenants share the same running instance or datastore.
  • Multi-tenant is acceptable when the user has specifically asked for it. It is not the default — do not choose it on your own — but when the user explicitly instructs a multi-tenanted design, that is a legitimate choice. Call the decision out explicitly and record it — in the project's direction memory, and as the tenant decision in DECISIONS.md and the Decisions: block of wbsp-status.md — so the rest of the build follows it. The build pipeline asks you this question directly at its Set project direction step and records your answer; it never decides tenancy on your behalf.

2. Single Sign-On across a user's apps

A user typically runs several WBSP apps together, and we do not want each app to ask them to sign in separately. The user signs in once and that identity is shared across their apps (Single Sign-On).

  • An app must not present an isolated, app-only login that re-prompts a user who already has a platform session.
  • Treat sign-in as a shared platform capability, accessed behind a replaceable adaptor (wbsp-client-guidelines.md → Authentication).

3. Production: one sign-on, shared credentials

A production deployment typically has a single place to sign on — a designated URL/app. The credentials/session established there are shared with the user's other apps, so the user is authenticated everywhere without re-entering credentials.

  • An app with no existing platform session sends the user to that single sign-on location, then resumes once a session exists.
  • Apps consume the shared identity; they do not own the primary login.

4. Development: reuse the WBSP website's login

During development, use the login functionality and credentials of wbsp-website, via the auth tenant wbsp. This gives developers the same "sign in once, shared everywhere" behaviour locally, without standing up a separate identity flow per app.

  • Point your app at the wbsp-website sign-on and the wbsp auth tenant.
  • For exactly how to wire this up (issuer/client registration, session reuse / silent SSO, just-in-time user provisioning, etc.), consult the Headless Auth Platform project — its guidelines are authoritative and may change, so follow them rather than any copy.

Summary

  • WBSP apps are single-tenant by preference — users run their own instance; multi-tenant is acceptable only when the user specifically asks for it.
  • Users sign in once; identity is shared across their apps (SSO).
  • Production: one sign-on URL/app; its session is shared with the user's apps.
  • Development: reuse wbsp-website login via the wbsp auth tenant.
  • The how lives in (and is owned by) the Headless Auth Platform project — refer to it; don't duplicate.