> ## Documentation Index
> Fetch the complete documentation index at: https://docs.strata.io/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/guides/getting-started/quick-start) or see the [installation reference](/reference/orchestrator/installation).
* **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](/reference/orchestrator/identity-fabric/azure-ad), [Okta](/reference/orchestrator/identity-fabric/okta), and [PingFederate](/reference/orchestrator/identity-fabric/pingone).
* **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

<Steps>
  <Step title="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.

    <Tabs>
      <Tab title="Console UI">
        1. Log in to the [Maverics Console](https://maverics.strata.io).
        2. Navigate to **Deployments** in the sidebar and click **Create**.
        3. Enter a name for your deployment (e.g., `SAML Federation`).
        4. Select a deployment provider. The Console supports several options:

           * **Evaluation** -- Strata-managed storage, no infrastructure needed. Best for getting started.
           * **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](/reference/console/config-publishing#deployment-providers) for provider setup details.
        5. Click **Create**.

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

      <Tab title="Configuration">
        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](/reference/orchestrator/installation) for details on configuration delivery options.
      </Tab>
    </Tabs>
  </Step>

  <Step title="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.

    <Tabs>
      <Tab title="Console UI">
        In the Maverics Console, SAML Provider settings are configured through the **Deployment Settings** dialog.

        1. Click the **gear icon** in the sidebar to open **Deployment Settings**.
        2. 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](/reference/modes/saml-provider#setup). 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.

        <Warning>
          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](/guides/security/secrets-management) syntax to store certificates and private keys securely rather than in plaintext configuration.
        </Warning>
      </Tab>

      <Tab title="Configuration">
        Define the `samlProvider` section in your `maverics.yaml` file. This configures the Orchestrator's SAML issuer identity and signing credentials.

        ```yaml maverics.yaml theme={null}
        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](/reference/orchestrator/configuration/secret-providers) at runtime. The certificate is included in the SAML metadata so downstream applications can validate assertion signatures.

        See [SAML Provider Reference](/reference/modes/saml-provider) for all available fields.
      </Tab>
    </Tabs>
  </Step>

  <Step title="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.

    <Tabs>
      <Tab title="Console UI">
        1. Navigate to **Identity Fabric** in the sidebar and click **Create**.
        2. 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.
        3. 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.

        4. Click **Save**.
      </Tab>

      <Tab title="Configuration">
        Define a SAML connector in the `connectors` section of your `maverics.yaml` file. The connector communicates with your identity provider over SAML 2.0.

        ```yaml maverics.yaml theme={null}
        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.
      </Tab>
    </Tabs>

    <Tip>
      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.
    </Tip>

    <Note>
      **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](/reference/orchestrator/identity-fabric) for all connector types.
    </Note>
  </Step>

  <Step title="Register your SAML application">
    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.

    <Tabs>
      <Tab title="Console UI">
        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.

        1. Navigate to **Applications** in the sidebar and click **Create**.
        2. Select **SAML-based**.
        3. 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.                                                                                                       |

        4. Click **Save**.
        5. 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.
        6. Find the **Access Control** card and click **Edit**.
        7. From the **Select an authentication source** dropdown, select your identity provider. To add more than one source, click **Add identity provider**.
        8. Click **Save**.

        <Tip>
          For any fields that accept certificates or private keys (such as SP Certificate for request verification), use [secret provider](/guides/security/secrets-management) references to avoid storing sensitive material in plaintext.
        </Tip>
      </Tab>

      <Tab title="Configuration">
        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.

        ```yaml maverics.yaml theme={null}
        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:

        ```yaml theme={null}
        requestVerification:
          certificate: <app.samlSigningCert>
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step title="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.

    <Tabs>
      <Tab title="Console UI">
        1. Open the application you created in the previous step.
        2. Find the **Attribute Mappings** card and click **Edit**.
        3. 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`).            |

        4. 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`

        5. Click **Save**.

        **Configure the NameID:**

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

        6. Find the **Protocol & Assertion Settings** card and click **Edit**.
        7. 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`).
        8. Click **Save**.
      </Tab>

      <Tab title="Configuration">
        Add `nameID` and `claimsMapping` to your SAML application definition. The `nameID.attrMapping` references an attribute from your IdP connector using the format `connectorName.attributeName`.

        ```yaml maverics.yaml theme={null}
        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](/reference/modes/saml-provider) for all available fields, including IdP-initiated login, per-app signature settings, and advanced assertion configuration.
      </Tab>
    </Tabs>

    <Tip>
      See the [SAML Provider reference](/reference/modes/saml-provider) for the complete list of configurable attributes, name formats, and assertion settings.
    </Tip>
  </Step>

  <Step title="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.

    <Tabs>
      <Tab title="Console UI">
        1. At the bottom of the deployment Settings page, click **Publish Preview** in the sticky footer bar.
        2. In the Deployment Manager dialog, review the configuration diff to verify your changes.
        3. Optionally add a revision note describing what changed (e.g., "Initial SAML federation setup").
        4. Click **Publish** to deploy the configuration bundle to your storage provider.
        5. The Orchestrator detects the new bundle on its next poll cycle and applies the configuration automatically.

        See [Publishing Deployment Configs overview](/reference/console/config-publishing) for details on the publishing lifecycle, revision history, and bundle verification.
      </Tab>

      <Tab title="Configuration">
        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.
      </Tab>
    </Tabs>
  </Step>

  <Step title="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:

    ```bash theme={null}
    maverics -config /etc/maverics/config.yaml
    curl -s https://localhost:9443/status | jq .
    ```

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

    1. **Visit the application URL** -- The Orchestrator redirects you to your identity provider's login page (SP-initiated flow)
    2. **Authenticate** -- Log in with valid credentials at your IdP
    3. **Verify redirect** -- After authentication, you should land on your application with a valid session
    4. **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.

    <Check>
      **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.
    </Check>
  </Step>
</Steps>

## Troubleshooting

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

## What's Next

<CardGroup cols={2}>
  <Card title="Migrate Between Identity Providers" icon="right-left" href="/guides/authentication/idp-migration">
    Move users from one identity provider to another with zero downtime and no application changes
  </Card>

  <Card title="SAML Provider Reference" icon="book-open" href="/reference/modes/saml-provider">
    Explore the complete SAML Provider configuration -- assertions, attributes, signing, and advanced settings
  </Card>
</CardGroup>