SAML 2.0
SAML 2.0 is an enterprise-grade XML-based standard for Single Sign-On. Use it to integrate with corporate identity providers such as Okta, OneLogin, Microsoft Entra ID (Azure AD), PingFederate, and other SAML 2.0-compliant services.
How It Works
SP-Initiated SSO (Default)
- A user clicks Sign in with {Provider Name} on the login page.
- MaestroHub generates a SAML AuthnRequest and redirects the user to the identity provider's SSO URL.
- The user authenticates at the identity provider.
- The identity provider sends a SAML Response (containing an assertion with user attributes) back to MaestroHub's Assertion Consumer Service (ACS) URL.
- MaestroHub validates the assertion signature and conditions, extracts user attributes, and creates or links a local user account.
- The user is logged in.
IdP-Initiated SSO (Optional)
When enabled, users can start the login flow directly from the identity provider's portal without first visiting MaestroHub. The identity provider sends an unsolicited SAML Response to MaestroHub, which validates and processes it the same way.
Configuration Reference
IdP Metadata Configuration
The simplest way to configure a SAML provider is to supply the identity provider's metadata. MaestroHub auto-extracts all required IdP settings from it.
| Field | Type | Required | Description |
|---|---|---|---|
| IdP Metadata URL | URL | Conditional | URL to fetch the IdP metadata XML automatically. Recommended — keeps configuration up to date when the IdP rotates certificates. |
| Raw Metadata XML | Textarea | Conditional | Paste the raw IdP metadata XML if a URL is not available. Alternative to the URL. |
You must provide one of: the IdP Metadata URL, the Raw Metadata XML, or the manual IdP settings below. If metadata is provided, the manual fields are auto-populated from it.
Manual IdP Settings
Use these fields if you don't have a metadata URL or XML. All three are required when configuring manually.
| Field | Type | Required | Description |
|---|---|---|---|
| IdP Entity ID | Text | Conditional | The identity provider's unique entity identifier. Found in the IdP's SAML metadata or configuration page. |
| IdP SSO URL | URL | Conditional | The identity provider's Single Sign-On endpoint where AuthnRequests are sent. |
| IdP X.509 Certificate | Textarea (PEM) | Conditional | The identity provider's signing certificate in PEM format (including -----BEGIN CERTIFICATE----- and -----END CERTIFICATE----- markers). Used to verify SAML assertion signatures. |
| IdP Single Logout URL | URL | No | The identity provider's Single Logout endpoint. Leave empty if SLO is not supported. |
Service Provider (SP) Settings
These values identify your MaestroHub instance to the identity provider.
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
| SP Entity ID | Text | Yes | — | Your application's SAML entity identifier. Typically your application URL (e.g., https://your-domain.com/saml/metadata). Must match what you configure in the identity provider. |
| ACS URL | URL | Yes | Auto-generated | Assertion Consumer Service URL — the endpoint where the IdP posts the SAML response. Format: https://your-backend-url/auth/saml/providers/your-slug/callback. Auto-populated from the provider slug. Configure this exact URL in your identity provider. |
Advanced Settings
Signature and Digest
| Field | Type | Default | Description |
|---|---|---|---|
| Signature Method | Select | RSA-SHA256 | Algorithm for signing SAML requests. Options: RSA-SHA1, RSA-SHA256, RSA-SHA512. |
| Digest Method | Select | SHA256 | Algorithm for message digests. Options: SHA1, SHA256, SHA512. |
| Name ID Format | Text | urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress | Requested format for the NameID element. Common values: emailAddress, persistent, transient. |
Security
| Field | Type | Default | Description |
|---|---|---|---|
| Sign Requests | Switch | Off | Sign SAML AuthnRequests sent to the IdP. Requires SP certificate and private key below. |
| Require Signed Assertions | Switch | On | Require the IdP to sign SAML assertions. Recommended for security. |
| Require Signed Response | Switch | Off | Require the IdP to sign the entire SAML response (not just the assertion). |
| Allow Unencrypted | Switch | Off | Allow unencrypted SAML assertions. When disabled, assertions must be signed. |
SP Certificate and Private Key
Required only when Sign Requests is enabled.
| Field | Type | Description |
|---|---|---|
| SP Certificate | Textarea (PEM) | Your service provider's X.509 certificate in PEM format. Used by the IdP to verify signed requests. |
| SP Private Key | Textarea (PEM) | Your service provider's private key in PEM format. Used to sign AuthnRequests. |
Session and Authentication
These settings are configured via defaults and are available in the backend configuration:
| Setting | Default | Description |
|---|---|---|
| Session Duration | 3600 seconds | How long a SAML session remains valid. |
| Allow IdP-Initiated SSO | Off | Accept unsolicited SAML responses from the identity provider. |
| Force Re-authentication | Off | Include ForceAuthn="true" in AuthnRequests, requiring the user to re-authenticate even if they have an active IdP session. |
| AuthnRequest Binding | HTTP-Redirect | How AuthnRequests are sent. Options: HTTP-Redirect, HTTP-POST. |
Attribute Mapping
Map SAML assertion attributes to MaestroHub user fields.
| Field | Placeholder | Description |
|---|---|---|
| Email Attribute | email | Attribute containing the user's email address |
| First Name Attribute | firstName | Attribute containing the user's first name |
| Last Name Attribute | lastName | Attribute containing the user's last name |
| Display Name Attribute | displayName | Attribute containing the full display name |
| Groups Attribute | groups | Attribute containing group memberships (used for role mapping) |
The attribute names must exactly match the attribute names in your IdP's SAML assertions. Check your IdP's attribute mapping or SAML response viewer to find the correct names. Common variations include http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress for Microsoft Entra ID.
Role Mapping
Optionally map SAML group attributes to MaestroHub roles.
| Field | Type | Default | Description |
|---|---|---|---|
| Enable Role Mapping | Switch | Off | Activate role mapping for this provider. |
| Role Claim | Text | — | The SAML attribute name containing group memberships (e.g., http://schemas.xmlsoap.org/claims/groups). |
| Default Role | Select | Member | Role assigned when no mapping matches. |
| Strict Enrollment | Switch | Off | Block login if no specific mapping matches. |
| Mappings | Key → Value pairs | — | Map IdP group names to MaestroHub roles. |
Setup Guide
Step 1: Gather IdP Metadata
In your identity provider's admin console:
- Create a new SAML application.
- Copy the IdP Metadata URL (preferred) or download the metadata XML.
- Note the IdP Entity ID and SSO URL if configuring manually.
Step 2: Create the Provider in MaestroHub
- Go to Identity & Access → SSO Configuration.
- Click Add Provider → SAML 2.0.
- Fill in the provider name and slug.
- Enter the IdP Metadata URL (or paste the raw XML).
- Set the SP Entity ID — this must match what you configure in the identity provider.
- Verify the ACS URL and configure it in your identity provider's SAML settings.
Step 3: Configure the IdP
In your identity provider, configure:
- ACS URL (Assertion Consumer Service): Copy from the MaestroHub form.
- SP Entity ID (Audience): Copy from the MaestroHub form.
- Name ID Format:
emailAddress(default) or as required. - Attribute Statements: Map user attributes (email, first name, last name) to the attribute names configured in MaestroHub.
Step 4: Test and Enable
- Click Test Connection. MaestroHub fetches and validates the IdP metadata.
- Save the provider.
- The provider appears on the login page as a Sign in with {Name} button.
SP Metadata
After creating the provider, you can share MaestroHub's SP metadata with your identity provider. The SP metadata XML is available at:
GET /auth/saml/providers/{provider-id}/metadata
Some identity providers can import this URL directly to auto-configure the integration.
Single Logout (SLO)
MaestroHub supports SAML Single Logout when the IdP provides an SLO URL:
- The local session is invalidated.
- A SAML LogoutRequest is sent to the IdP's SLO endpoint.
- The IdP terminates its session and sends a LogoutResponse back.
- The user is redirected to the login page.
MaestroHub also handles IdP-initiated logout — when the user logs out from the identity provider's portal, the IdP sends a LogoutRequest to MaestroHub to terminate the local session.
Troubleshooting
| Problem | Solution |
|---|---|
| "Certificate errors" | Ensure the X.509 certificate is in PEM format with proper BEGIN CERTIFICATE and END CERTIFICATE markers. No extra whitespace or characters. |
| "Assertion expired" | Check clock synchronization between MaestroHub and the identity provider. SAML assertions have time-based validity windows. |
| "Audience mismatch" | The SP Entity ID in MaestroHub must exactly match the Audience Restriction configured in the IdP. |
| "Signature invalid" | The IdP may have rotated its signing certificate. Update the certificate in MaestroHub or re-import the metadata. |
| "Recipient mismatch" | The ACS URL in MaestroHub must exactly match the recipient URL the IdP sends in the assertion. |
| "Attribute mapping issues" | Verify attribute names match the SAML assertion exactly. Use your IdP's SAML response viewer or tracer to inspect the actual attribute names. |
| "Metadata fetch failed" | Confirm the IdP Metadata URL is accessible from the MaestroHub server. Check firewall rules and DNS resolution. |
| Users not getting correct roles | Verify the Groups Attribute matches the actual attribute name in the SAML assertion, and that the group names in Mappings match exactly. |