Single sign-on

Each tenant — the group of people who work in a boundary — can sign in through its own identity provider instead of with a Stackship password. Single sign-on is set up per tenant by a platform administrator: it needs rbac/idpBindings/admin at the platform root, which Platform Owner and Platform Contributor hold.

Before you start

• Single sign-on needs Keycloak Organizations turned on for the platform. When they are off, a tenant's page shows Organizations are not enabled, shows no domains or providers, and refuses every change. Installations set up by the installer have them on.
• The platform manages identity providers in its own identity provider at https://auth.example.com. If saving answers that it may not, a realm administrator has to grant the platform's RBAC service the realm-management roles manage-realm, view-identity-providers and manage-identity-providers.

Choose the tenant

Open Settings → Platform Settings and the Single sign-on tab. Tenants are listed by the boundaries they contain and the start of their tenant ID. Choose the tenant to configure. Only tenants that own a boundary you can see are listed; every boundary starts as a tenant of its own.

Add a domain

Under Domains, enter an e-mail domain that belongs to the tenant, for example example.com, in Add domain, and choose Add. The change is saved at once.

The platform does not check that the tenant owns the domain: every domain added here is stored as verified. A domain that already belongs to another tenant is refused.

Add an identity provider

1. Register the platform as an application in your identity provider. The address it returns users to is https://auth.example.com/realms/stackship/broker/<alias>/endpoint, where <alias> is the alias you choose in step 4. For SAML, the service provider metadata is at the same address followed by /descriptor.
2. Under Identity providers, choose Add identity provider.
3. Choose the Type:
   • OIDC — enter the provider's Discovery URL (its .well-known/openid-configuration address, https:// only), and the Client ID and Client secret of the application you registered. The platform asks the provider for the openid, email and profile scopes.
   • SAML — enter the provider's Metadata URL (https:// only).
4. Enter a Display name — what users see on the sign-in page — and an Alias: 2 to 63 lowercase letters, digits and hyphens, not starting with a hyphen. The alias cannot be changed later, and no other tenant may use it.
5. Optionally pick one of the tenant's domains under Domain and turn on Redirect when email matches — see Send users straight to their provider.
6. Choose Add. The platform reads the provider's configuration from the discovery or metadata URL, so that address must be reachable from the platform.

The client secret is stored in the identity provider and never shown again.

Send users straight to their provider

An identity provider mapped to a domain, with Redirect when email matches on, takes everyone who enters an e-mail address on that domain at sign-in straight to that provider. Redirect needs a domain.

People who sign in through a provider become members of the tenant, but get no role: assign roles, or invite them, as for anyone else — see Assign a role.

Change or remove a provider

Choose a provider to edit its Display name, Client secret (leave it blank to keep the stored one), whether it is Enabled, its Domain and redirect. The type, alias, discovery or metadata URL and client ID cannot be changed; to change them, delete the provider and add it again. Deleting asks you to confirm Delete identity provider?.

What boundary members see

A boundary's Overview shows its tenant's domains and identity providers, read-only, to everyone who can read the boundary's members.