Single Sign-On
Let people sign in with the account they already have at your identity provider, over OIDC, SAML 2.0 or LDAP.
- Where
- Admin › Identity & Access › Single Sign-On
- Protocols
- OIDC · SAML 2.0 · LDAP
- Licence feature
- SSO
The Single Sign-On page (Admin → Identity & Access → Single Sign-On) is where you configure Single Sign-On providers for enterprise authentication. Users can authenticate through external identity providers instead of managing passwords locally.
SSO configuration requires the SSO feature to be enabled in your license. When SSO is not licensed:
- The Single Sign-On page shows a "Single Sign-On is not enabled" screen, and no providers can be created or managed.
- The login page does not display any SSO provider buttons, even if providers were previously configured.
- SSO authentication attempts are rejected by the backend with a
403status. - Existing provider configurations are preserved and become functional again if the SSO feature is re-enabled.
Supported Provider Types
MaestroHub supports three SSO protocols:
| Protocol | Best For | Details |
|---|---|---|
| OpenID Connect (OIDC) | Cloud identity providers: Google, Microsoft, Okta, Auth0 | OIDC Configuration Guide |
| SAML 2.0 | Enterprise identity providers: large organizations, corporate SSO | SAML Configuration Guide |
| LDAP / Active Directory | On-premise directory services: Active Directory, OpenLDAP | LDAP Configuration Guide |
Provider List
Go to Admin → Identity & Access → Single Sign-On to see all configured providers. The page is visible to users whose role can read SSO providers: System Administrator, Identity Administrator and Security Administrator. Identity providers are platform-wide, so only these platform roles manage them; a Workspace Administrator does not.
An account that holds a platform role (System Administrator, Identity Administrator, Security Administrator) does not sign in through single sign-on: the sign-in is refused with this account holds a platform administrator role, so it does not sign in through single sign-on, and the account is not linked to the provider. Whoever configures a provider decides who a sign-in through it is, so a provider must not be a way into an account more powerful than the people who manage providers. Platform administrators use their email and password (and the break-glass procedure if every password is lost). An account created by single sign-on has no password: set one (Users → the user's row menu → Reset password, see Resetting a user's password) before granting it a platform role, or the person can't sign in.
A provider's role mapping chooses the roles its first-time users get in the workspace they land in, Workspace Administrator included. Managing providers is therefore a powerful job: grant Identity Administrator only to people trusted with every workspace's sign-ups. Platform roles can't be mapped.
Five stat cards appear at the top:
| Card | Description |
|---|---|
| Total Providers | Total count with number of enabled providers |
| OIDC Providers | Count of OpenID Connect providers |
| SAML Providers | Count of SAML 2.0 providers |
| LDAP Providers | Count of LDAP/AD providers |
| System Status | Overall health indicator |
The table lists all providers with the following columns:
| Column | Description |
|---|---|
| Provider | Icon, name (clickable), and slug |
| Type | Badge showing OIDC, SAML, or LDAP |
| New users join | The workspace people signing in through the provider for the first time land in. Not chosen means none (see Where new users land); Workspace deleted · new users refused means its workspace was deleted. |
| Status | Enabled or Disabled |
| Created By | User who created the provider and when |
| Updated By | User who last modified the provider and when |
| Actions | Edit, Test Connection, Change where new users land, Delete |
Use the controls above the table to filter by type (OIDC, SAML, LDAP), status (Enabled, Disabled), or search by name. Sort by any column.
Where new users land
Identity providers are platform-wide: anyone with an account can sign in through any enabled provider. What a provider decides per workspace is only where people it creates land: the first time someone signs in through it, MaestroHub creates their account, makes them a member of the provider's landing workspace and grants their mapped roles there. People who already have an account are never moved or added anywhere by signing in.
You choose the landing workspace explicitly, from a list of workspaces, when you create the provider and later with Change where new users land in the provider's menu. It is never taken from the workspace the page is open in. The choices are:
- A workspace: new accounts join it and get their mapped roles there. A workspace that was deleted can't be chosen; if a provider's workspace is deleted later, its first-time sign-ins are refused until you choose another.
- No workspace: with one active workspace on the installation, new accounts join it; with several (or with none active), they are placed in none and see a "you're in no workspace" page until an identity administrator adds them (Users → Workspaces). Their mapped roles are not applied: mapped roles are granted only when the account is created, in the workspace it joins, so give the provider a landing workspace if its group mapping should take effect.
Editing a provider never changes where its new users land; only Change where new users land does.
Creating a Provider
- Click Add Provider.
- Select the provider type: OpenID Connect, SAML 2.0, or LDAP/Active Directory.
- Fill in the configuration form; see the individual provider guides linked above for field details. New users join starts on the workspace you are viewing; change it to another workspace or to none (see Where new users land).
- Use Test Connection to verify the configuration before saving.
- Click Create to save the provider.
Common Fields (All Providers)
Every provider shares these base fields:
| Field | Type | Required | Description |
|---|---|---|---|
| Provider Name | Text | Yes | Display name (min 2 characters). Shown to users on the login page. |
| Slug | Text | Yes | URL-friendly identifier. Auto-generated from the name. Lowercase letters, numbers, and hyphens only. Cannot be changed after creation. |
| Description | Textarea | No | Optional note about the provider's purpose or intended user group. |
| Priority | Number | No | Display order on the login page. Lower numbers appear first. Default: 0. |
| Enable Provider | Switch | No | Whether users can authenticate with this provider. Default: enabled. Only shown when editing. |
Testing a Provider
You can test provider connectivity in two ways:
From the configuration form:
- Fill in the required fields.
- Click Test Connection at the bottom of the form.
- The system verifies connectivity and displays a success or error message.
From the provider list:
- Click the actions menu on any provider row.
- Select Test Connection.
- The test runs against the saved configuration.
What each test does:
- OIDC: Fetches the OpenID Connect Discovery Document from the issuer URL.
- SAML: Fetches and validates the IdP metadata (URL or XML).
- LDAP: Connects to the LDAP server and performs a service account bind.
Managing Providers
Enable / Disable
Edit a provider and toggle the Enable Provider switch. Disabled providers remain fully configured but do not appear on the login page.
Delete
- Click the actions menu on the provider row and select Delete.
- Type the provider name to confirm.
- Click Delete Provider.
Deleting a provider is permanent. Users who previously authenticated with this provider will lose their SSO access. Consider disabling the provider first to test the impact.
Role Mapping
All three provider types support optional role mapping: automatically assigning MaestroHub roles to users based on their group memberships in the identity provider.
| Field | Description |
|---|---|
| Enable Role Mapping | Toggle to activate role mapping for this provider. |
| Role Claim | The claim or attribute that contains groups/roles. OIDC and SAML only, and required there when role mapping is on. LDAP has no Role Claim. |
| Default Role | Role assigned when no mapping matches. Default: Member. |
| Strict Enrollment | When enabled, users whose groups don't match any mapping are blocked from logging in. |
| Mappings | Key-value pairs mapping IdP group names to MaestroHub roles. System Administrator can't be a mapping target: it is granted under System Administrators. |
Role mapping behavior:
- The system reads the user's groups from the configured claim/attribute.
- Each group is checked against the mappings table.
- All matched roles are assigned to the user.
- If no mapping matches, the Default Role is assigned.
- If Strict Enrollment is enabled and no mapping matches, authentication is rejected.
For detailed field references, see the individual provider guides: