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

# Duo (SAML)

The Duo Security connector integrates the Maverics Orchestrator with Duo -- enabling SAML-based single sign-on with built-in multi-factor authentication.

<Note>
  **Console terminology:** In the Maverics Console, this section is called
  **Identity Fabric**. The YAML configuration uses the `connectors` key to define
  identity provider integrations.
</Note>

## Overview

The Duo Security connector uses SAML 2.0 federation. Duo combines identity verification with multi-factor authentication in a single sign-on flow -- making it well-suited for environments where strong authentication is required at every login.

## Use Cases

* **MFA-integrated SSO** -- Leverage Duo's built-in multi-factor authentication alongside SAML-based single sign-on, adding strong authentication to applications managed by the Orchestrator
* **Unify SSO with Duo MFA for legacy apps** -- Extend Duo's MFA capabilities to legacy and on-prem applications that lack native Duo support, delivering consistent strong authentication across your hybrid environment
* **Strengthen resilience with MFA failover** -- Pair Duo with a secondary IdP through the Continuity connector so authentication continues even if one provider is unavailable, with MFA enforced throughout
* **Consolidate MFA under Duo** -- Route authentication from multiple IdPs through Duo to standardize multi-factor policies, reducing the cost and complexity of managing MFA across separate platforms

## Setup

<Tabs>
  <Tab title="Console UI">
    To create a Duo (SAML) connector in the Maverics Console:

    1. Navigate to **Identity Fabric** in the Console sidebar.
    2. Click **Create** and select **Duo (SAML)**.
    3. Enter a **Name** -- the friendly name for your Duo provider.
    4. Enter the **Metadata URL** -- the URL of Duo's SAML metadata document, typically `https://{api-host}/saml2/idp/metadata`.
    5. Enter the **Consumer Service (ACS) URL** -- the Assertion Consumer Service URL where Duo sends SAML responses.
    6. Enter the **Entity ID** -- the unique identifier for the Orchestrator as the SAML Service Provider.
    7. Optionally enter a **Logout Callback URL** for Single Logout (SLO) callback.
    8. Optionally enter the **SP Certificate Path** and **SP Private Key Path** for signing SAML requests.
    9. Optionally enable **IdP Initiated Login** to allow authentication flows started by Duo.
    10. Click **Save**.
  </Tab>

  <Tab title="Configuration">
    ```yaml maverics.yaml theme={null}
    connectors:
      - name: duo
        type: saml
        samlMetadataURL: "https://{{ env.DUO_HOST }}/saml2/idp/metadata"
        samlConsumerServiceURL: "https://orch.example.com/saml/callback"
        samlEntityID: "https://orch.example.com"
    ```

    <Note>
      Duo's SAML metadata URL uses the API hostname assigned to your Duo account. You can find this in the Duo Admin Panel under the SAML application configuration.
    </Note>

    ## Configuration Reference

    | Key                      | Type   | Required | Description                                                        |
    | ------------------------ | ------ | -------- | ------------------------------------------------------------------ |
    | `name`                   | string | Yes      | Unique connector identifier referenced by app policies             |
    | `type`                   | string | Yes      | Must be `saml`                                                     |
    | `samlMetadataURL`        | string | Yes      | URL to Duo's SAML metadata XML                                     |
    | `samlConsumerServiceURL` | string | Yes      | Assertion Consumer Service (ACS) URL for SAML responses            |
    | `samlEntityID`           | string | No       | Service Provider entity ID that identifies the Orchestrator to Duo |
    | `samlLogoutCallbackURL`  | string | No       | Logout callback URL for SAML single logout                         |
    | `samlSPCertPath`         | string | No       | Path to the SP certificate file for signing SAML requests          |
    | `samlSPKeyPath`          | string | No       | Path to the SP private key file for signing SAML requests          |
    | `cache`                  | string | No       | Cache name reference for SAML request data storage                 |
    | `tls`                    | string | No       | Named TLS profile for metadata retrieval and IdP communication     |

    For the complete field reference including health check details, see [Identity Fabric](/reference/orchestrator/identity-fabric#configuration-reference).
  </Tab>
</Tabs>

## Troubleshooting

* **Verify the SAML metadata URL is accessible** from the Orchestrator host -- ensure the Duo API hostname is correct
* **Ensure the Entity ID matches the Duo configuration** -- the `samlEntityID` must match what is configured as the trusted Service Provider in the Duo Admin Panel
* **Check the ACS URL** -- the `samlConsumerServiceURL` must match the Orchestrator's callback endpoint. If behind a load balancer, use the external-facing URL.
* **Confirm Duo SAML application is active** -- disabled or draft applications in Duo will not respond to authentication requests

## Related Pages

<CardGroup cols={2}>
  <Card title="Identity Fabric" icon="id-badge" href="/reference/orchestrator/identity-fabric">
    Overview of all identity providers
  </Card>

  <Card title="Generic SAML" icon="file-shield" href="/reference/orchestrator/identity-fabric/custom-saml">
    Generic SAML 2.0 connector
  </Card>

  <Card title="ADFS" icon="server" href="/reference/orchestrator/identity-fabric/adfs">
    ADFS connector
  </Card>

  <Card title="Continuity" icon="arrows-rotate" href="/reference/orchestrator/identity-fabric/continuity">
    IdP failover connector
  </Card>
</CardGroup>