Authentication
Configure how end users sign into your workspace apps — Groundfloor IdP, external OIDC, SSO, roles, and branding.
Authentication (sidebar → Administer) configures workspace site auth — how end users sign into your deployed Shell or product apps. This is separate from signing into the Customer Portal itself.
Do not confuse this with Control Plane login or Members & Roles. Portal admins use the shared Groundfloor IdPlane realm and platform membership roles. Workspace site auth roles are app end-user roles only — they do not grant Customer Portal or /v1/* access.
Auth modes
| Mode | When to use |
|---|---|
| None | Internal tools or apps that do not need end-user login |
| Groundfloor | Groundfloor provisions a per-workspace IdPlane realm (users, roles, SSO, branding) |
| External | You bring your own OIDC issuer and client |
Platform architecture: Workspace site auth. Shell wiring: Auth modes.
Configure settings
Open Authentication
In the sidebar under Administer, click Authentication. Select the workspace in the top picker.
Choose a mode
On Settings, set mode to none, groundfloor, or external. For external mode, provide issuer URL and client details. Optionally set a Shell custom domain.
Save
Groundfloor mode provisions (or links) the workspace realm. Users, Roles, SSO, and Branding tabs become available once the realm is active.
Users and roles
With Groundfloor mode active:
- Users — invite, enable/disable, reset password, assign app roles, remove
- Roles — define role names and permission packs for your product (not Owner/Admin/Writer from Members & Roles)
- Invites require realm SMTP to be configured (see Branding / realm settings)
These roles live in the workspace realm. Platform membership remains under Members & Roles.
SSO brokers
Add OIDC or SAML identity brokers so end users can sign in with an external IdP while Groundfloor remains the workspace realm. Use Test login to verify the broker before rolling out.
Branding
Customize the login chrome (logo, colors, copy) and configure realm SMTP for invite and password emails.
Activity
The Activity tab shows authentication-related audit events for the workspace realm.
Troubleshooting
| Problem | Likely cause | What to do |
|---|---|---|
| Users / SSO tabs disabled | Mode is not Groundfloor, or realm not ready | Switch to Groundfloor and wait for provisioning |
| Invite email not sent | Realm SMTP missing | Configure SMTP under Branding / realm settings |
| External login fails | Wrong issuer or client | Re-check OIDC settings; use Test login for brokers |
Related API
GET/PUT /v1/workspaces/{id}/auth- Users, roles, permissions, SSO, and audit under
/v1/workspaces/{id}/auth/…
Related
- Members & Roles — portal account membership (not app end users)
- Shell authentication
- Developers — API tokens for Control Plane / Coderunner