Federate SAML Apps

By the end of this guide, you will have a Maverics Orchestrator acting as a SAML Provider — federating authentication between your identity provider and SAML-based enterprise applications.

What Is SAML?

SAML (Security Assertion Markup Language) is an XML-based authentication protocol that has been the standard for enterprise single sign-on for over two decades. Many enterprise applications — especially older ones built before OIDC existed — only support SAML for federated authentication. SAML works by exchanging signed XML documents (called assertions) between an identity provider (IdP) and a service provider (SP) to prove a user’s identity. The Maverics Orchestrator can act as a SAML Provider, receiving assertions from your identity provider and translating them into authenticated sessions for your applications. This means your applications do not need to implement SAML directly — the Orchestrator handles the protocol complexity for them.

Prerequisites

A running Maverics Orchestrator — If you have not installed the Orchestrator yet, follow the Quick Start guide or see the installation reference.
An identity provider account — While this guide demonstrates a SAML connector, the Orchestrator can connect to your IdP over OIDC, SAML, or LDAP. Your IdP does not need to support SAML specifically. Common IdPs include Microsoft Entra ID, Okta, and PingFederate.
A target SAML application — An enterprise application that authenticates users via SAML assertions. Common examples include legacy portals, HR systems, and internal tools that were built for SAML-based SSO.

Configure SAML Federation

Create an Orchestrator Deployment

In the Maverics Console, all configuration lives within a Deployment — a managed Orchestrator instance with its own configuration, storage provider, and signing keys. Before you can create identity connectors and applications, you need a Deployment to hold them.

Console UI
Configuration

Log in to the Maverics Console.
Navigate to Deployments in the sidebar and click Create.
Enter a name for your deployment (e.g., SAML Federation).
Select a deployment provider. The Console supports several options:
- AWS S3, Azure Blob Storage, or Google Cloud Storage — customer-managed cloud storage for production.
- GitHub or GitLab — deploy bundles to a Git repository.
- Download Only — manual bundle download for air-gapped environments.
See Publishing Deployment Configs overview for provider setup details.
Click Create.

Your new deployment opens automatically. You can now configure identity connectors and applications within it.

When using direct configuration, no deployment setup is needed — configuration is defined directly in the maverics.yaml file and delivered to the Orchestrator via the -config flag or MAVERICS_CONFIG environment variable. See Installation for details on configuration delivery options.

Configure the SAML Provider

The SAML Provider must be enabled and configured at the deployment level before creating connectors or applications. This configures the Orchestrator to act as a SAML identity provider to your downstream applications — issuing signed SAML assertions after authenticating users through your upstream IdP connector.The SAML Provider requires signing credentials (a certificate and private key) that the Orchestrator uses to sign assertions. Your downstream applications validate these signatures to ensure assertions came from a trusted source.

Console UI
Configuration

In the Maverics Console, SAML Provider settings are configured through the Deployment Settings dialog.

Click the gear icon in the sidebar to open Deployment Settings.
Find the SAML Provider section and configure the provider-level settings.

The SAML Provider Deployment Settings fields (Issuer, endpoints, signing options, certificates, and Redis cache) are documented in the SAML Provider reference. Use the Console UI tab there for field-by-field details.The key settings to configure are the Issuer (your Orchestrator’s Entity ID) and the Signing Option (which parts of the SAML response to sign). Click Generate after entering the Issuer to auto-populate the Metadata, Single Sign-on, and Single Logout endpoint URLs.

If signing credentials (certificate and private key) are left blank, the Orchestrator auto-generates a self-signed certificate at startup. This certificate is ephemeral — it is regenerated on every restart, which means all previously issued assertions become unverifiable by service providers. For production, always configure explicit signing credentials. Use the <namespace.key> secret provider syntax to store certificates and private keys securely rather than in plaintext configuration.

Define the samlProvider section in your maverics.yaml file. This configures the Orchestrator’s SAML issuer identity and signing credentials.

maverics.yaml

samlProvider:
  issuer: https://your-orchestrator.example.com
  endpoints:
    metadata: https://your-orchestrator.example.com/saml/metadata
    singleSignOnService: https://your-orchestrator.example.com/saml/sso
    singleLogoutService: https://your-orchestrator.example.com/saml/slo
  signature:
    certificate: <saml.signingCert>
    privateKey: <saml.signingKey>

The signature.certificate and signature.privateKey use secret references — the Orchestrator retrieves these from your secret provider at runtime. The certificate is included in the SAML metadata so downstream applications can validate assertion signatures.See SAML Provider Reference for all available fields.

Connect your identity provider

Next, connect the Orchestrator to your identity provider as a SAML identity source. This tells the Orchestrator where to send users for authentication and how to validate the signed assertions it receives back.SAML supports two authentication flows, and it helps to understand the difference:

SP-initiated — The user visits your application first. The Orchestrator (acting as the Service Provider) redirects the user to the identity provider for authentication, and the IdP sends the user back with a SAML assertion. This is the most common flow.
IdP-initiated — The user logs into the identity provider first (through a portal or dashboard) and then navigates to the application. The IdP sends a SAML assertion directly to the Orchestrator without a prior authentication request.

The Orchestrator supports both flows. You will need your IdP’s SAML metadata URL (or metadata XML file), which contains the IdP’s signing certificate, SSO endpoint URLs, and entity ID.

Console UI
Configuration

Navigate to Identity Fabric in the sidebar and click Create.
Select your identity provider from the list. Choose a provider-specific SAML option (such as Okta (SAML) or Microsoft Entra ID (SAML)) or select Generic SAML for any SAML-compliant provider. OIDC and LDAP connector options are also available — this guide demonstrates the SAML connector path, but any connector type is valid here.
Fill in the connector form:

Field	Required	Description
Name	Yes	A friendly name for your identity provider (e.g., `my-saml-idp`).
Metadata URL	Yes	Your IdP’s SAML metadata URL (e.g., `https://your-idp.example.com/saml/metadata`). The Orchestrator fetches signing certificates and endpoints from this URL automatically.
Consumer Service (ACS) URL	Yes	The Assertion Consumer Service URL where your IdP sends SAML responses after authentication (e.g., `https://your-orchestrator.example.com/saml/acs`).
Entity ID	Yes	The unique identifier for the Service Provider (e.g., `https://your-orchestrator.example.com`).
Logout Callback URL	No	The URL for Single Logout (SLO) callback.
SP Certificate Path	No	Path to the Service Provider certificate for request signing.
SP Private Key Path	No	Path to the Service Provider private key for request signing.
NameID Format	No	The NameID format to use in SAML assertions (e.g., `emailAddress`, `persistent`).

The Enable IdP Initiated Login toggle allows authentication flows started by the identity provider. Enable this if your users will access the application from an IdP portal.

Click Save.

Define a SAML connector in the connectors section of your maverics.yaml file. The connector communicates with your identity provider over SAML 2.0.

maverics.yaml

connectors:
  - name: my-saml-idp
    type: saml
    samlMetadataURL: https://your-idp.example.com/saml/metadata
    samlConsumerServiceURL: https://your-orchestrator.example.com/saml/acs
    samlEntityID: https://your-orchestrator.example.com

The samlMetadataURL points to your identity provider’s SAML metadata endpoint. The Orchestrator fetches this automatically to retrieve the IdP’s signing certificate, SSO endpoint, and entity ID.If your IdP does not publish a metadata URL, you can provide the metadata as a local file using samlMetadataFile instead.

Most identity providers publish a SAML metadata URL that the Orchestrator can fetch automatically. This is easier than manually entering certificates and endpoints — the metadata contains everything the Orchestrator needs to establish the trust relationship.

Protocol translation: This guide shows a SAML connector, but the Orchestrator can connect to your IdP using any supported protocol — OIDC, SAML, or LDAP. The Orchestrator’s mode (SAML Provider) determines what protocol your application speaks. The connector determines what protocol your IdP speaks. These are independent — you can connect an OIDC-only IdP and the Orchestrator will translate to SAML for your application. See the Identity Fabric overview for all connector types.

Register your application as a SAML relying party (service provider) in the apps section. This tells the Orchestrator which application to issue SAML assertions for, where to send the assertions, and which identity connector to use for authentication.

Console UI
Configuration

In the Console, you create the SAML application and connect it to your identity provider in a single flow. The connector you select becomes the application’s authentication source.

Navigate to Applications in the sidebar and click Create.
Select SAML-based.
Fill in the application form:

Field	Required	Description
Name	Yes	A friendly name for your application (e.g., `my-saml-app`).
Upload Icon	No	Upload an image for your application (JPEG, PNG, or SVG, up to 2MB).
Default Entity ID	Yes	The entity ID identifying the service provider. Click the Entity ID button to add additional entity IDs.
Default URL (ACS)	Yes	The default Assertion Consumer Service URL. Click the URL button to add additional ACS URLs.
Logout URL	No	The URL where SAML logout responses are sent.
Unauthorized Page	No	Redirect URL for unauthorized users.
Duration	No	The duration in seconds for which responses are valid. Defaults to 300 seconds.
Name ID Format	No	The NameID format for the SAML assertion. The specific NameID attribute mapping is configured on the application’s Protocol & Assertion Settings card.
Signing Options	No	Select Use deployment settings (default), Sign Response Only, Sign Response & Assertion, or Sign Assertion Only.
Certificate File (Request Verification)	No	Upload a PEM certificate to verify signed incoming requests from the SP.
Login URL (IDP Initiated Login)	No	Endpoint for IdP-initiated login flow.
Relay State URL (IDP Initiated Login)	No	Landing page URL after IdP-initiated authentication.

Click Save.
On the application settings page, find the Resources card and click Edit. Click Add Resource, select the SAML connector you created earlier, and click Save. A connector must be added as a resource before it can be selected as an authentication source.
Find the Access Control card and click Edit.
From the Select an authentication source dropdown, select your identity provider. To add more than one source, click Add identity provider.
Click Save.

For any fields that accept certificates or private keys (such as SP Certificate for request verification), use secret provider references to avoid storing sensitive material in plaintext.

Define a SAML application in the apps section. The entityIDs and consumerServiceURLs identify your application in the SAML trust, and authentication.idps binds the connector from the first step.

maverics.yaml

apps:
  - name: my-saml-app
    type: saml
    entityIDs:
      - identifier: https://your-app.example.com
        default: true
    consumerServiceURLs:
      - url: https://your-app.example.com/saml/acs
        default: true
    logoutServiceURL: https://your-app.example.com/saml/logout
    duration: 300
    requestVerification:
      skipVerification: true
    authentication:
      idps:
        - my-saml-idp

The entityIDs array identifies your application in the SAML trust relationship. The consumerServiceURLs specify where the Orchestrator sends the SAML assertion after authentication. The duration sets the assertion validity period in seconds.Set requestVerification.skipVerification to true if your application does not sign its SAML authentication requests. For applications that do sign requests, provide the application’s certificate instead:

requestVerification:
  certificate: <app.samlSigningCert>

Configure assertion attributes

Configure the nameID and claimsMapping to control which identity attributes appear in the SAML assertions your application receives. The nameID is the primary user identifier in the assertion, and claimsMapping adds additional attributes.

Console UI
Configuration

Open the application you created in the previous step.
Find the Attribute Mappings card and click Edit.
Add a claim mapping for each attribute your application needs:

Field	Description
Claim Name	The attribute name that will appear in the SAML assertion (e.g., `email`, `firstName`).
Claim Source	Select the identity provider connector to pull the attribute from.
Value Mapping	The attribute name from the identity provider (e.g., `email`, `given_name`).

Click the Claim button to add additional rows for each claim you need to map.

For example, to pass the user’s email, first name, and last name, add three claim rows:

email from your IdP’s email
firstName from your IdP’s given_name
lastName from your IdP’s family_name

Click Save.

Configure the NameID:The NameID is configured separately, on the Protocol & Assertion Settings card.

Find the Protocol & Assertion Settings card and click Edit.
Under NameID, set the Dynamic NameID Source to the identity provider connector that provides the NameID value, and set the Dynamic NameID Attribute to the attribute to use as the primary subject identifier (e.g., email).
Click Save.

Add nameID and claimsMapping to your SAML application definition. The nameID.attrMapping references an attribute from your IdP connector using the format connectorName.attributeName.

maverics.yaml

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

The nameID.format specifies the NameID format the application expects. Common formats include emailAddress, persistent, and unspecified. The attrMapping value references the connector attribute to use as the NameID value.The claimsMapping keys (email, firstName, lastName) become attribute names in the SAML assertion. The values reference attributes from your IdP connector.See SAML Provider Reference for all available fields, including IdP-initiated login, per-app signature settings, and advanced assertion configuration.

See the SAML Provider reference for the complete list of configurable attributes, name formats, and assertion settings.

Publish your configuration

After configuring your deployment, identity connector, application, and assertion attributes in the Console, you need to publish the configuration so the Orchestrator receives it and applies your changes.

Console UI
Configuration

At the bottom of the deployment Settings page, click Publish Preview in the sticky footer bar.
In the Deployment Manager dialog, review the configuration diff to verify your changes.
Optionally add a revision note describing what changed (e.g., “Initial SAML federation setup”).
Click Publish to deploy the configuration bundle to your storage provider.
The Orchestrator detects the new bundle on its next poll cycle and applies the configuration automatically.

See Publishing Deployment Configs overview for details on the publishing lifecycle, revision history, and bundle verification.

When using direct configuration, configuration is delivered directly to the Orchestrator via the -config flag or MAVERICS_CONFIG environment variable. No publishing step is needed — restart the Orchestrator to apply configuration changes.

Verify federation

With your SAML identity source configured, your application registered as a relying party, and attribute mapping in place, you are ready to test the federated authentication flow.Start (or restart) the Orchestrator and verify it is healthy:

maverics -config /etc/maverics/config.yaml
curl -s https://localhost:9443/status | jq .

Now test the SAML flow by visiting your application’s URL:

Visit the application URL — The Orchestrator redirects you to your identity provider’s login page (SP-initiated flow)
Authenticate — Log in with valid credentials at your IdP
Verify redirect — After authentication, you should land on your application with a valid session
Check attributes — If your application has a profile or debug page, verify that the SAML attributes match your mapping configuration

To test the IdP-initiated flow, log into your identity provider’s portal and click the application tile. You should be redirected to your application with a valid session — no separate login required.

Success! Your Maverics Orchestrator is federating SAML authentication between your identity provider and your enterprise application. Users authenticate through your IdP, the Orchestrator translates the SAML assertion, and your application receives the attributes it expects — all without modifying the application.

Troubleshooting

Certificate mismatch or signature validation error

SAML assertions are cryptographically signed, and the Orchestrator validates these signatures using the certificate from your IdP’s metadata. If the certificate has been rotated (updated) on the IdP side but the Orchestrator still has the old certificate, validation fails. Re-fetch the IdP’s metadata or manually update the signing certificate in your Orchestrator configuration. If you are using a metadata URL, the Orchestrator can pick up certificate changes automatically on the next metadata refresh.

Assertion Consumer Service URL mismatch

Your identity provider rejects the SAML request because the ACS URL (Assertion Consumer Service URL) does not match what is registered. This is the URL where the IdP sends the SAML response after authentication. Verify that the ACS URL configured in the Orchestrator exactly matches the one registered in your IdP — including protocol, domain, port, and path. This is similar to the redirect URI mismatch issue in OIDC.

Clock skew causes assertion rejection

SAML assertions include timestamps that the Orchestrator validates to prevent replay attacks. If the clocks on your IdP server and the Orchestrator’s host are not synchronized, the Orchestrator may reject valid assertions because they appear to be from the future or already expired. Ensure both systems use NTP (Network Time Protocol) to keep their clocks synchronized. Most SAML implementations allow a small clock skew tolerance (typically 1-2 minutes) — check your Orchestrator configuration for a skew tolerance setting.

What’s Next

Migrate Between Identity Providers

Move users from one identity provider to another with zero downtime and no application changes

SAML Provider Reference

Explore the complete SAML Provider configuration — assertions, attributes, signing, and advanced settings

Getting Started

Authentication

AI Identity

Identity Continuity

Operations

Security

What Is SAML?

Prerequisites

Configure SAML Federation

Troubleshooting

What’s Next

Migrate Between Identity Providers

SAML Provider Reference

​What Is SAML?

​Prerequisites

​Configure SAML Federation

​Troubleshooting

​What’s Next

Migrate Between Identity Providers

SAML Provider Reference

What Is SAML?

Prerequisites

Configure SAML Federation

Troubleshooting

What’s Next