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

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

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

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

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

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

> **[Identity Fabric](/reference/orchestrator/identity-fabric)**
>
> Overview of all identity providers

> **[Generic SAML](/reference/orchestrator/identity-fabric/custom-saml)**
>
> Generic SAML 2.0 connector

> **[ADFS](/reference/orchestrator/identity-fabric/adfs)**
>
> ADFS connector

> **[Continuity](/reference/orchestrator/identity-fabric/continuity)**
>
> IdP failover connector