> ## 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

**1. 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**

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:

   * **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.

**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.

**2. 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**

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.

**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.

**3. 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**

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**.

**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.

> [!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.

> [!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.

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

**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.

**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>
```

**5. 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**

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**.

**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.

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

**6. 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**

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.

**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.

**7. 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.

> [!TIP]
>
> **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](/guides/authentication/idp-migration)**
>
> Move users from one identity provider to another with zero downtime and no application changes

> **[SAML Provider Reference](/reference/modes/saml-provider)**
>
> Explore the complete SAML Provider configuration -- assertions, attributes, signing, and advanced settings