> For the complete documentation index, see [llms.txt](https://docs.platform9.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.platform9.com/private-cloud-director/identity-and-multi-tenancy/enterprise-sso/set-up-duo.md).

# Set up Duo

## Overview

Configure single sign-on (SSO) for your <code class="expression">space.vars.product\_acronym</code> environment using Duo. This integration allows users to authenticate to <code class="expression">space.vars.product\_acronym</code> using their existing Duo credentials and enables Duo's multi-factor authentication (MFA) policies for all <code class="expression">space.vars.product\_acronym</code> logins.

In this guide, you will create a Duo SAML application, map user attributes, and connect Duo to your <code class="expression">space.vars.product\_acronym</code> deployment.

## Prerequisites

Before you begin, ensure you have:

* Administrative access to the Duo Admin Panel.
* Administrative access to your <code class="expression">space.vars.product\_acronym</code> environment.
* Your <code class="expression">space.vars.product\_acronym</code> domain FQDN (fully qualified domain name), without the region name.
* Users enrolled in Duo who need access to <code class="expression">space.vars.product\_acronym</code>.

## Step 1: Create a SAML Application in Duo

Create a new generic SAML service provider application in the Duo Admin Panel to handle the SSO integration.

1. Log in to the Duo Admin Panel at `admin.duosecurity.com`.
2. Navigate to **Applications** and select **Protect an Application**.
3. Search for **Generic Service Provider** and select **Protect** next to it.
4. Note the **Entity ID**, **Single Sign-On URL**, and **Certificate** values — you will need these when configuring <code class="expression">space.vars.product\_acronym</code>.

## Step 2: Configure SAML Settings in Duo

Configure the service provider settings so Duo can send SAML assertions to your <code class="expression">space.vars.product\_acronym</code> deployment.

1. Under **Service Provider**, configure the following fields.

| Field                                    | Value                                                        |
| ---------------------------------------- | ------------------------------------------------------------ |
| **Entity ID**                            | `https://<FQDN>/keystone`                                    |
| **Assertion Consumer Service (ACS) URL** | `https://<FQDN>/sso/<DOMAIN_NAME>/Shibboleth.sso/SAML2/POST` |
| **NameID format**                        | `EmailAddress`                                               |

{% hint style="info" %}
**Note**

Replace `<FQDN>` with your <code class="expression">space.vars.product\_acronym</code> domain FQDN without any region suffix. Use `IDP1` for the default domain, or substitute your specific domain name for `<DOMAIN_NAME>`.

For example, use `companyx.app.pcd.platform9.com`, not `companyx-regionone.app.pcd.platform9.com`.
{% endhint %}

2. Under **SAML Response**, configure the following.

| Field                   | Value         |
| ----------------------- | ------------- |
| **Signature algorithm** | `SHA-256`     |
| **Signing options**     | Sign response |

3. Save the application.

## Step 3: Map Attributes in Duo

Add attribute statements so that Duo passes the user's name and email to <code class="expression">space.vars.product\_acronym</code>.

1. In your Duo SAML application, navigate to **SAML Response** > **Map Attributes**.
2. Add the following attribute mappings.

| SAML Attribute Name | Duo User Attribute  |
| ------------------- | ------------------- |
| `FirstName`         | `<user.first_name>` |
| `LastName`          | `<user.last_name>`  |
| `Email`             | `<user.email>`      |

3. Save the attribute mappings.

## Step 4: Download the Duo Metadata

Download the SAML metadata XML from Duo so you can register it in <code class="expression">space.vars.product\_acronym</code>.

1. In your Duo SAML application, select **Download XML Metadata** or note the **Metadata URL** from the application overview.

You will supply either the metadata URL or the XML content in the next step.

## Step 5: Configure SSO in <code class="expression">space.vars.product\_acronym</code>

Connect your <code class="expression">space.vars.product\_acronym</code> deployment to the Duo SAML application.

1. Log in to your <code class="expression">space.vars.product\_acronym</code> environment.
2. Navigate to **Settings** > **Enterprise SSO**.
3. Enable SSO and configure the following fields.

| Field                                 | Value                                                                                |
| ------------------------------------- | ------------------------------------------------------------------------------------ |
| **SSO Provider**                      | Select **Other** (Duo is not listed as a named provider; use the generic SAML path). |
| **Entity ID**                         | Enter the **Entity ID** from your Duo SAML application.                              |
| **SAML Metadata URL**                 | Enter the metadata URL from Duo, or leave blank if supplying the XML directly.       |
| **SSO Provider Attribute Map in XML** | Paste the attribute map XML below.                                                   |

4. Paste the following attribute map XML into the **SSO Provider Attribute Map in XML** field. Adjust attribute names if you used different names in Step 3.

```xml
<Attributes
    xmlns="urn:mace:shibboleth:2.0:attribute-map"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

    <Attribute
        id="FirstName"
        name="FirstName"
        nameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
        <AttributeDecoder xsi:type="StringAttributeDecoder" caseSensitive="false"/>
    </Attribute>

    <Attribute
        id="LastName"
        name="LastName"
        nameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
        <AttributeDecoder xsi:type="StringAttributeDecoder" caseSensitive="false"/>
    </Attribute>

    <Attribute
        id="Email"
        name="Email"
        nameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
        <AttributeDecoder xsi:type="StringAttributeDecoder" caseSensitive="false"/>
    </Attribute>

</Attributes>
```

5. Select **Save**.

## Step 6: Configure SAML Groups in <code class="expression">space.vars.product\_acronym</code>

Set up SAML groups to manage user permissions and role assignments.

1. On the **Enterprise SSO** page, select **SAML Groups**.
2. Select **Add Group**.
3. Configure the group settings.

| Field                                 | Description                                                         |
| ------------------------------------- | ------------------------------------------------------------------- |
| **Name**                              | Enter a unique name for the group.                                  |
| **Description**                       | Enter a brief description.                                          |
| **SAML Attribute Key for First Name** | Enter `FirstName` (or the attribute name you configured in Step 3). |
| **SAML Attribute Key for Last Name**  | Enter `LastName`.                                                   |
| **SAML Attribute Key for Email**      | Enter `Email`.                                                      |

4. Configure the group mapping.

| Field                    | Description                                                               |
| ------------------------ | ------------------------------------------------------------------------- |
| **SAML Group Attribute** | Enter the group attribute name configured in your Duo attribute mappings. |
| **Criteria**             | Select **Any one of**.                                                    |
| **SAML Group Values**    | Enter the Duo group names whose members should match this mapping.        |

5. Under **Tenants & Roles**, assign the group to the appropriate tenants and roles (Administrator, Self-Service User, or ReadOnly).
6. Select **Save**.

## Step 7: Test the SSO Configuration

Verify that your Duo SSO integration works correctly.

1. Log out of your current <code class="expression">space.vars.product\_acronym</code> session.
2. Open a new private or incognito browser window.
3. Navigate to your <code class="expression">space.vars.product\_acronym</code> login page.
4. Select **Sign In with SSO**.
5. Complete the authentication process using your Duo credentials and MFA.
6. Verify that you can access <code class="expression">space.vars.product\_acronym</code> resources according to your assigned role.

You have now successfully configured SSO integration between <code class="expression">space.vars.product\_acronym</code> and Duo. Users can authenticate using their Duo credentials and access <code class="expression">space.vars.product\_acronym</code> resources based on their assigned roles.

## Next Steps

* To troubleshoot SSO login failures, see [SSO Troubleshooting Guide](/private-cloud-director/identity-and-multi-tenancy/enterprise-sso/sso-troubleshooting.md).
* To understand role permissions, see [RBAC Roles and Permissions](/private-cloud-director/identity-and-multi-tenancy/rbac-roles-and-permissions.md).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.platform9.com/private-cloud-director/identity-and-multi-tenancy/enterprise-sso/set-up-duo.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.