SAML Provider

The SAML Provider mode configures the Maverics Orchestrator as a SAML 2.0 identity provider. It handles SAML assertion generation, attribute mapping, and protocol translation — allowing you to federate enterprise applications that depend on SAML while connecting to modern or legacy upstream identity providers.

Console terminology: In the Maverics Console, the combination of applications, policies, headers, and connector bindings is managed through User Flows. In YAML, these elements are configured directly within each app’s configuration block under apps[].policies[].

When to use this mode

SAML Provider — Choose this mode for applications that only support SAML 2.0. Best for enterprise apps with rigid SAML requirements.
OIDC Provider — Choose this mode for modern applications that can consume OpenID Connect tokens natively.
HTTP Proxy — Choose this mode for applications that cannot handle SAML directly or where you cannot modify authentication code.
LDAP Provider — Choose this mode for applications that require an LDAP directory for authentication.
AI Identity Gateway — Choose this mode for securing AI agent-to-tool communication via MCP.

Use Cases

SAML federation for enterprise apps — Provide SAML 2.0 assertions to enterprise applications like Salesforce, ServiceNow, and Workday that require SAML-based single sign-on.
Protocol translation (OIDC-to-SAML) — Bridge modern OIDC identity providers to legacy SAML-dependent applications without modifying either side.
IdP migration for SAML-dependent apps — Migrate SAML service providers from one identity provider to another with zero downtime and no SP reconfiguration.
Attribute mapping and enrichment — Enrich SAML assertions with attributes sourced from multiple directories, databases, and APIs beyond what the upstream IdP provides.

How It Works

The SAML Provider authentication flow follows these steps:

SP-initiated request — A user accesses a SAML service provider. The SP generates a SAML AuthnRequest and redirects the user to the Orchestrator’s SSO endpoint.
Upstream authentication — The Orchestrator routes the user to the configured upstream identity provider for authentication. The upstream IdP can use any protocol (OIDC, SAML, LDAP) — the Orchestrator handles protocol translation.
Attribute enrichment — After authentication, the Orchestrator loads additional attributes from configured attribute providers and merges them with the authenticated identity.
Assertion generation — The Orchestrator generates a signed SAML assertion containing the NameID and mapped claims from the authenticated identity and enriched attributes.
SP receives assertion — The SAML response (containing the signed assertion) is POSTed to the SP’s assertion consumer service URL. The SP validates the signature and establishes a session.
IdP-initiated flow (optional) — Users can also start from the Orchestrator’s IdP-initiated login URL, which generates an assertion and sends it directly to the SP without an AuthnRequest.

Key Concepts

Provider vs Apps

The samlProvider block configures IdP-wide settings (issuer, SSO/SLO endpoints, signing material) shared across all SAML apps. Each apps[] entry with type: saml registers a specific service provider with its own entity ID, ACS URL, NameID format, and claims mapping.

Protocol Translation

The Orchestrator can translate between protocols — an upstream OIDC identity provider can feed a downstream SAML service provider, or vice versa. The service provider only sees SAML; the identity provider only sees OIDC. This makes IdP migration possible without changing SP configurations.

Assertion Signing

By default, both the SAML assertion and the SAML response are signed using the provider’s signing material. Individual apps can override signing behavior (e.g., disable assertion signing for SPs that don’t verify it) or use per-app signing keys.

NameID and Claims

The NameID identifies the authenticated subject in the SAML assertion. Claims mapping uses the same connector.attribute format as OIDC, translating connector attributes into SAML assertion attributes.

Request Verification

When service providers sign their AuthnRequest messages, the Orchestrator verifies the signature using the SP’s certificate. This can be skipped for SPs that don’t sign requests.

Interface

Console UI
Configuration

In the Maverics Console, SAML Provider settings are configured in the Deployment Settings dialog under the SAML Provider section.Issuer and Endpoints

Field	Required	Description
Issuer	Yes	Unique SAML IdP identifier (Entity ID). Typically the base URL of the Orchestrator.
Generate	—	Button that auto-generates endpoint URLs from the Issuer.
Metadata	No	SAML metadata endpoint URL (auto-generated from Issuer).
Single Sign-on	Yes	SSO endpoint URL for receiving AuthnRequest messages (auto-generated).
Single Logout	Yes	SLO endpoint URL (auto-generated).

Signing

Field	Required	Description
Signing Option	Yes	Dropdown to select what is signed. Options include “Response and Assertion” (default), “Response Only”, “Assertion Only”.
x509 Certificate	Yes	The X.509 certificate used for signing SAML assertions and responses.
RSA256 Private Key	Yes	The RSA private key for signing. Can be overridden per-app.
Edit	—	Button to edit the private and public key pair.

Additional Settings

Field	Required	Description
Redis Cache	No	Dropdown to select a configured Redis cache for SAML request data and provider state storage. Defaults to in-memory if not set.

The Console UI provides a subset of the full YAML configuration. Per-app signature overrides, assertion encryption settings, and advanced request verification options are configured at the app level and are only available in YAML. See the Configuration tab for the complete reference.

The following example configures the Orchestrator as a SAML 2.0 identity provider with one SAML service provider application. The samlProvider block defines the IdP-wide settings (issuer, endpoints, signing), while each saml app defines a service provider registration.

samlProvider:
  issuer: https://auth.example.com
  cache: redis-cache
  endpoints:
    metadata: https://auth.example.com/saml/metadata
    singleSignOnService: https://auth.example.com/saml/sso
    singleLogoutService: https://auth.example.com/saml/slo
  signature:
    certificate: <saml_signing_cert>
    privateKey: <saml_signing_key>

apps:
  - name: my-saml-app
    type: saml
    entityIDs:
      - identifier: https://sp.example.com
        default: true
    consumerServiceURLs:
      - url: https://sp.example.com/acs
        default: true
    logoutServiceURL: https://sp.example.com/logout
    duration: 300
    nameID:
      format: urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress
      attrMapping: upstream-idp.email
    requestVerification:
      skipVerification: true
    authentication:
      idps:
        - upstream-idp
    claimsMapping:
      email: upstream-idp.email
      firstName: upstream-idp.given_name
      lastName: upstream-idp.family_name
    idpInitiatedLogin:
      loginURL: https://auth.example.com/saml/sso/my-saml-app
      relayStateURL: https://sp.example.com/

Configuration Reference

samlProvider

The samlProvider top-level key configures the Orchestrator as a SAML 2.0 identity provider. This block defines the IdP issuer, SAML endpoints, signing material, and cache. All saml type apps require samlProvider to be configured.

Key	Type	Required	Default	Description
`issuer`	string	Yes	—	SAML EntityID for the identity provider. Typically the base URL of the Orchestrator (e.g., `https://auth.example.com`).
`endpoints.metadata`	string	Yes	—	URL where the IdP publishes SAML metadata XML.
`endpoints.singleSignOnService`	string	Yes	—	URL for the SAML SSO endpoint that receives `AuthnRequest` messages.
`endpoints.singleLogoutService`	string	Yes	—	URL for the SAML Single Logout endpoint.
`signature.certificate`	string	Conditional	—	PEM-encoded X.509 certificate for signing SAML assertions and responses. Inline value. Mutually exclusive with `certificateFile`.
`signature.certificateFile`	string	Conditional	—	File path to the X.509 certificate. Mutually exclusive with `certificate`.
`signature.privateKey`	string	Conditional	—	PEM-encoded private key for signing. Inline value. Mutually exclusive with `privateKeyFile`.
`signature.privateKeyFile`	string	Conditional	—	File path to the private key. Mutually exclusive with `privateKey`.
`signature.disableSignedAssertion`	boolean	No	`false`	When `true`, SAML assertions are not signed. See Signed and Unsigned Assertions.
`signature.disableSignedResponse`	boolean	No	`false`	When `true`, SAML responses are not signed. See Signed and Unsigned Assertions.
`cache`	string	No	—	Name of a configured cache (Redis or cluster) for SAML request data and provider state storage. References a `caches[]` entry by name.

Signing material must be provided as either inline values (certificate + privateKey) or file paths (certificateFile + privateKeyFile). Use secret references (e.g., <saml_signing_cert>) for inline values to avoid storing credentials in config files.

SAML App Type (`apps[].type: saml`)

Each SAML service provider is registered as an app with type: saml. The app defines the SP entity ID, assertion consumer service URL, NameID format, authentication policy, and claims mapping.

The Apps and Routes page documents key fields for SAML apps in context with other app types. This section provides the complete field reference.

Core Fields

Key	Type	Required	Default	Description
`name`	string	Yes	—	Unique name for the SAML app.
`type`	string	Yes	—	Must be `saml`.
`entityIDs`	array	Yes	—	Service provider entity IDs. Each entry has `identifier` (string) and `default` (boolean). At least one entry with `default: true` is required.
`consumerServiceURLs`	array	Yes	—	Assertion Consumer Service URLs. Each entry has `url` (string) and `default` (boolean). At least one entry with `default: true` is required.
`logoutServiceURL`	string	No	—	SP logout service URL for single logout.
`duration`	integer	No	`3600`	Assertion lifetime in seconds.

NameID Configuration

Key	Type	Required	Default	Description
`nameID.format`	string	No	—	SAML NameID format URN (e.g., `urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress`).
`nameID.attrMapping`	string	No	—	Connector attribute to use as the NameID value (e.g., `upstream-idp.email`). Uses `connector.attribute` format.

Authentication

Key	Type	Required	Default	Description
`authentication.idps`	array	Conditional	—	List of identity provider connector names for user authentication. Cannot be combined with `isAuthenticatedSE`/`authenticateSE`.
`authentication.isAuthenticatedSE`	object	Conditional	—	Service Extension for custom authentication checks. Must be defined together with `authenticateSE`.
`authentication.authenticateSE`	object	Conditional	—	Service Extension for custom authentication flows. Must be defined together with `isAuthenticatedSE`.

Authorization

Key	Type	Required	Default	Description
`authorization.allowAll`	boolean	No	—	When `true`, all authenticated users are authorized.
`authorization.rules`	array	No	—	Authorization rules using `and`/`or` conditions with `equals`, `notEquals`, `contains`, `notContains` operators. See Apps and Routes for the full rules reference.
`authorization.rulesAggregationMethod`	string	No	`"and"`	How top-level rules are combined: `"and"` (all must match) or `"or"` (any may match).
`authorization.isAuthorizedSE`	object	No	—	Service Extension for custom authorization logic.

Claims and Attributes

Key	Type	Required	Default	Description
`claimsMapping`	object	No	—	Maps SAML assertion attribute names to connector attribute values. Keys are assertion attribute names; values use `connector.attribute` format (e.g., `email: upstream-idp.email`).
`buildClaimsSE`	object	No	—	Service Extension for custom SAML assertion claims. When defined, replaces `claimsMapping`.
`attrProviders`	array	No	—	Additional attribute providers for post-authentication attribute loading. Each entry has `connector` (string) and `usernameMapping` (string in `{{ connector.attribute }}` format).
`loadAttrsSE`	object	No	—	Service Extension for custom attribute loading logic.

Request Verification

Key	Type	Required	Default	Description
`requestVerification.certificate`	string	Conditional	—	PEM-encoded SP certificate for verifying signed `AuthnRequest` messages. Required when `skipVerification` is `false` or not set.
`requestVerification.skipVerification`	boolean	No	`false`	When `true`, skip signature verification of incoming `AuthnRequest` messages. Use when the SP does not sign its requests.

Per-App Signature Override

Individual SAML apps can override the provider-level signing configuration. When a per-app signature block is defined, it takes precedence over samlProvider.signature for that specific app.

Key	Type	Required	Default	Description
`signature.certificate`	string	Conditional	—	PEM-encoded X.509 certificate for this app’s assertions.
`signature.certificateFile`	string	Conditional	—	File path to the certificate.
`signature.privateKey`	string	Conditional	—	PEM-encoded private key for this app’s signing.
`signature.privateKeyFile`	string	Conditional	—	File path to the private key.
`signature.disableSignedAssertion`	boolean	No	`false`	Disable assertion signing for this specific app.
`signature.disableSignedResponse`	boolean	No	`false`	Disable response signing for this specific app.

Deprecated Fields

The following fields are deprecated. Migrate to the replacement fields listed below.

audience — Use entityIDs instead
consumerServiceURL — Use consumerServiceURLs instead
nameIDFormat — Use nameID.format instead

Signed and Unsigned Assertions

By default, the SAML Provider signs both the SAML assertion and the SAML response using the signing material configured in samlProvider.signature. Some service providers require unsigned assertions or unsigned responses depending on their verification capabilities. Controlling signature behavior at the provider level:

Console UI
Configuration

Provider-level signature overrides (disableSignedAssertion, disableSignedResponse) are configured via YAML only. The Console UI manages the primary signing option (Response and Assertion, Response Only, Assertion Only) in the Deployment Settings dialog (see the Interface section above). To override the default signing flags directly, use the Configuration tab.

samlProvider:
  signature:
    certificate: <saml_signing_cert>
    privateKey: <saml_signing_key>
    # Signed assertion + signed response (default)
    disableSignedAssertion: false
    disableSignedResponse: false

Controlling signature behavior per app: Individual apps can override the provider defaults. For example, if the provider signs both but a specific SP needs unsigned assertions:

Console UI
Configuration

Per-app signature overrides are configured via YAML only. The Console UI manages provider-level signing options in the Deployment Settings dialog (see the Interface section above). To override signing behavior for a specific service provider, use the Configuration tab.

apps:
  - name: unsigned-assertion-app
    type: saml
    signature:
      disableSignedAssertion: true
    # ... other fields

Request verification from the SP side: When a service provider signs its AuthnRequest messages, the Orchestrator verifies the signature using the SP’s certificate. If the SP does not sign requests, set skipVerification: true:

Console UI
Configuration

Request verification settings (SP certificate and skip verification) are configured per-app via YAML only. The Console UI manages provider-level SAML settings in the Deployment Settings dialog (see the Interface section above). See the Configuration tab for the full reference.

apps:
  # SP that sends signed AuthnRequests
  - name: saml-signed
    type: saml
    requestVerification:
      certificate: <sp_signing_cert>
    # ...

  # SP that does not sign AuthnRequests
  - name: saml-unverified
    type: saml
    requestVerification:
      skipVerification: true
    # ...

IdP-initiated login allows users to start a SAML flow from the identity provider rather than from the service provider. When configured, the Orchestrator exposes a login URL that generates a SAML response and sends it directly to the SP’s assertion consumer service.

Key	Type	Required	Default	Description
`idpInitiatedLogin.loginURL`	string	Yes	—	URL that triggers the IdP-initiated flow. Users or portals navigate to this URL to start the login.
`idpInitiatedLogin.relayStateURL`	string	No	—	URL included as the SAML `RelayState` parameter. The SP redirects the user here after consuming the assertion.
`idpInitiatedLogin.buildRelayStateSE`	object	No	—	Service Extension for dynamically building the relay state value.

Example:

Console UI
Configuration

IdP-initiated login URLs and relay state are configured per-app via YAML only. The Console UI manages provider-level SAML settings in the Deployment Settings dialog (see the Interface section above). See the Configuration tab for the full reference.

apps:
  - name: portal-app
    type: saml
    idpInitiatedLogin:
      loginURL: https://auth.example.com/saml/sso/portal-app
      relayStateURL: https://portal.example.com/
    # ...

When a user navigates to https://auth.example.com/saml/sso/portal-app, the Orchestrator authenticates them (if not already authenticated), builds a SAML assertion, and POSTs it to the app’s assertion consumer service URL with the relay state set to https://portal.example.com/.

Assertion Encryption

SAML assertion encryption protects assertion content during transit by encrypting the assertion XML before embedding it in the SAML response. The SP decrypts the assertion using its private key.

Key	Type	Required	Default	Description
`encryption.keyEncryptMethod`	string	Yes	—	XML encryption method for encrypting the symmetric key (e.g., `http://www.w3.org/2001/04/xmlenc#rsa-oaep-mgf1p`).
`encryption.dataEncryptMethod`	string	Yes	—	XML encryption method for encrypting the assertion data (e.g., `http://www.w3.org/2001/04/xmlenc#aes256-cbc`).
`encryption.digestMethod`	string	No	—	Digest method for key encryption (e.g., `http://www.w3.org/2001/04/xmlenc#sha256`).
`encryption.certificate`	string	Yes	—	PEM-encoded SP certificate (public key) used to encrypt the assertion. The SP holds the corresponding private key for decryption.

Example:

Console UI
Configuration

Assertion encryption settings (key encryption method, data encryption method, SP encryption certificate) are configured per-app via YAML only. The Console UI manages provider-level SAML settings in the Deployment Settings dialog (see the Interface section above). See the Configuration tab for the full reference.

apps:
  - name: encrypted-app
    type: saml
    encryption:
      keyEncryptMethod: "http://www.w3.org/2001/04/xmlenc#rsa-oaep-mgf1p"
      dataEncryptMethod: "http://www.w3.org/2001/04/xmlenc#aes256-cbc"
      digestMethod: "http://www.w3.org/2001/04/xmlenc#sha256"
      certificate: <sp_encryption_cert>
    # ...

The SAML Provider mode works with all Identity Fabric connectors. The Orchestrator translates between any upstream IdP protocol and SAML assertions for your applications. These are the most commonly used pairings:

Azure AD

Microsoft Entra ID for enterprise SSO

Okta

Okta SSO consolidation

Custom SAML

Any SAML 2.0-compliant provider

Custom OIDC

Any OIDC provider (protocol translated to SAML)

Continuity

IdP failover and migration

See the connector compatibility matrix for all supported pairings and the Identity Fabric overview for the full connector list. The SAML Provider also pairs with:

Secret Providers — Store signing certificates and encryption keys securely

Troubleshooting

Assertion signature validation fails at the SP

Symptoms: The SP rejects the SAML response with “invalid signature”, “signature verification failed”, or “unable to validate assertion”.Causes:

The signing certificate configured in the Orchestrator (samlProvider.signature.certificate) does not match the certificate the SP has on file.
The signing certificate has expired.
A signing algorithm mismatch between the Orchestrator and the SP’s expected algorithm.

Resolution:

Export the samlProvider.signature.certificate and provide it to the SP via metadata exchange or manual upload.
Verify the certificate is not expired by checking its Not After date.
If using per-app signature overrides, ensure the app-level certificate is the one provided to the SP.

NameID format mismatch

Symptoms: The SP accepts the assertion but cannot identify the user, or rejects the assertion with “invalid NameID format” or “unrecognized subject”.Causes:

The nameID.format does not match what the SP expects (e.g., the SP expects emailAddress but the Orchestrator sends unspecified).
The nameID.attrMapping references an attribute that is empty or not returned by the upstream IdP.

Resolution:

Check the SP’s metadata or documentation for the required NameID format.
Set nameID.format to the matching URN (e.g., urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress).
Verify that nameID.attrMapping points to an attribute that is populated for all users (e.g., upstream-idp.email).

Claims/attributes missing from assertion

Symptoms: The SP receives the assertion but expected attributes (e.g., email, groups, department) are empty or absent.Causes:

The claimsMapping references a wrong connector name or an attribute that does not exist on the upstream identity.
Attribute providers (attrProviders) are not configured, so enrichment attributes are not loaded.
The upstream IdP does not return the expected claims in its response.

Resolution:

Verify that connector names in claimsMapping match the connectors[].name values exactly.
If enrichment is needed, confirm attrProviders entries are configured with the correct connector names and usernameMapping.
Test the upstream IdP directly to confirm it returns the expected attributes.

SP-initiated login fails with "unable to verify request"

Symptoms: The login flow fails immediately after the SP redirect, with an error about request verification or signature validation.Causes:

The SP signs its AuthnRequest, but the Orchestrator does not have the SP’s signing certificate for verification.
The SP’s certificate in requestVerification.certificate is expired or does not match the key the SP uses.

Resolution:

If the SP signs its AuthnRequests, provide the SP’s signing certificate in requestVerification.certificate.
If the SP does not sign requests, set requestVerification.skipVerification: true.
If the SP recently rotated its signing key, update the certificate in the app configuration.

IdP-initiated login returns "unknown service provider"

Symptoms: Navigating to the IdP-initiated login URL returns an error about an unknown or unregistered service provider.Causes:

The idpInitiatedLogin.loginURL path does not match any configured app.
The app’s entityIDs are missing or do not match what the SP expects.

Resolution:

Verify the login URL matches the configured app name in the URL path (e.g., /saml/sso/my-app for an app named my-app).
Confirm that entityIDs contains at least one entry with default: true.
Check that the consumerServiceURLs are correctly configured for the target SP.

Assertion encryption fails

Symptoms: The SP cannot decrypt the assertion, reporting errors like “unable to decrypt”, “decryption failed”, or “invalid key”.Causes:

The encryption.certificate is not the SP’s encryption certificate (it might be the signing cert instead).
An algorithm mismatch — keyEncryptMethod or dataEncryptMethod does not match the SP’s supported algorithms.

Resolution:

Verify that encryption.certificate is the SP’s public encryption certificate (not its signing certificate — these are often different).
Confirm that keyEncryptMethod and dataEncryptMethod match the algorithms the SP supports (check SP metadata or documentation).
If the SP specifies a digestMethod, ensure it is also set in the app configuration.

OIDC Provider

Configure the Orchestrator as an OpenID Connect authorization server

Identity Fabric

Connect upstream identity providers to the Orchestrator

Architecture and Concepts

Understand how modes fit into the Orchestrator architecture

HTTP Proxy

Protect applications without code modification using reverse proxy mode

Console Administration

Orchestration

Use Cases

How It Works

Key Concepts

Provider vs Apps

Protocol Translation

Assertion Signing

NameID and Claims

Request Verification

Interface

Configuration Reference

samlProvider

SAML App Type (`apps[].type: saml`)

Core Fields

NameID Configuration

Authentication

Authorization

Claims and Attributes

Request Verification

Per-App Signature Override

Deprecated Fields

Signed and Unsigned Assertions

Assertion Encryption

Azure AD

Okta

Custom SAML

Custom OIDC

Continuity

Troubleshooting

OIDC Provider

Identity Fabric

Architecture and Concepts

HTTP Proxy

Console Administration

Orchestration

​Use Cases

​How It Works

​Key Concepts

​Provider vs Apps

​Protocol Translation

​Assertion Signing

​NameID and Claims

​Request Verification

​Interface

​Configuration Reference

​samlProvider

​SAML App Type (apps[].type: saml)

​Core Fields

​NameID Configuration

​Authentication

​Authorization

​Claims and Attributes

​Request Verification

​Per-App Signature Override

​Deprecated Fields

​Signed and Unsigned Assertions

​IdP-Initiated Login

​Assertion Encryption

​Related Integrations

Azure AD

Okta

Custom SAML

Custom OIDC

Continuity

​Troubleshooting

​Related Pages

OIDC Provider

Identity Fabric

Architecture and Concepts

HTTP Proxy

Use Cases

How It Works

Key Concepts

Provider vs Apps

Protocol Translation

Assertion Signing

NameID and Claims

Request Verification

Interface

Configuration Reference

samlProvider

SAML App Type (`apps[].type: saml`)

Core Fields

NameID Configuration

Authentication

Authorization

Claims and Attributes

Request Verification

Per-App Signature Override

Deprecated Fields

Signed and Unsigned Assertions

IdP-Initiated Login

Assertion Encryption

Related Integrations

Troubleshooting

Related Pages