WorkOS Docs Homepage
DashboardSign In


Learn how to configure a connection to Duo via SAML.

Each SSO Identity Provider requires specific information to create and configure a new Connection. Often, the information required to create a Connection will differ by Identity Provider.

To create a Duo SAML Connection, you’ll need three pieces of information: an ACS URL (provide by WorkOS), an Identity Provider Issuer (also known as an Entity ID, provided by WorkOS), and the Metadata URL (provided by Duo).

Duo is also unique in that it requires a 3rd party IDP to federate the authentication. This means that along with the three pieces of information, you’ll also need to configure a Single Sign-On Authentication Source and a Cloud Application in your Duo Workspace.

The high level overview of the authentication flow:

Your App → WorkOS → Duo → Your SSO IDP → Duo → WorkOS → Your App

A flowchart showing the authentication flow of Duo using WorkOS.

Navigate to the Organization in your WorkOS Dashboard under which you would like to set up this new SSO Connection. Click “Manually Configure Connection” and select Duo SAML from the list of SSO Identity Providers. You’ll want to select “Duo SAML” as the Identity Provider and give the Connection a descriptive name. Once this is filled out, click “Create Connection”.

A screenshot showing how to create a Duo Saml connection in the WorkOS dashboard.

Take note of the Connection Details as you’ll need to enter those in Duo later on. This page is also where you’ll enter the Metadata URL in a later step.

A screenshot showing where to access Service Provider details in the connection settings.

WorkOS will allow you to use any Duo supported IDP to handle the Federated authentication. Since each IDP will have different ways of setting up the SSO connection between Duo and the IDP, please refer to the documentation that Duo provides to configure a Duo SSO Connection.

After configuring the Duo SSO Connection with the IDP of your choice, the next step is to create a Cloud Application in Duo. This app will handle the connection between WorkOS and Duo.

Navigate to the Duo Admin Panel and click on Applications on the left sidebar.

Click “Protect an Application” and locate the entry for “Generic SAML Service Provider” with a protection type of “2FA with SSO hosted by Duo (Single Sign-On)” in the applications list. Click Protect to the far-right to start configuring “Generic SAML Service Provider”.

A screenshot showing how to create a Cloud App in Duo.

Next, configure the Generic Service Provider settings. There are pieces of information on this page that need to come from WorkOS and your Duo SSO Connection, and also information to copy and enter in the WorkOS Connection.

Start by gathering the Metadata URL to enter in the WorkOS Duo SAML Connection that you created in the prior step.

A screenshot showing where to copy the IdP Metadata URL in Duo.

Navigate to your WorkOS Duo SAML Connection and paste the Metadata URL in to the Metadata field.

You won’t see the connection flip to Active yet as there is still some configuration to do on the Duo side.

A screenshot showing how to add the IDP metadata in the WorkOS dashboard.

From the WorkOS Connection page you are currently on, copy the ACS URL value from the field just above the SAML Settings.

A screenshot highlighting the ACS URL in the WorkOS dashboard.

Navigate to the Duo Applications Generic Service Provider configuration settings and paste the ACS URL in the Assertion Consumer Service (ACS) URL field under the Service Provider section.

A screenshot showing where to input the ACS URL in Duo settings.

Next, copy the SP Entity ID value from the WorkOS Connection page.

A screenshot highlighting the Entity ID in the WorkOS dashboard.

Paste the SP Entity ID into the Entity ID field under the Service Provider section in the Duo Applications Generic Service Provider confiuration.

You may leave the Single Logout URL, Service Provider Login URL, and Default Relay State fields empty.

A screenshot showing where to input the Entity ID in Duo settings.

Scroll down on this page to the SAML Response section. Ensure that the NameID format has the id that you’d like to use for the unique identifier selected and matches the NameID attribute that you’d like to use as the value. If you’re using email as the unique ID, the options would look like the below.

A screenshot showing how to configure SAML Response NameID in Duo.

Ensure the Signature algorithm is SHA256 and that the Signing options have both Sign response and Sign assertion selected.

A screenshot showing where to configure the SAML Response Signing.

Next make sure that you are mapping the attributes which WorkOS requires: id, email, firstName, and lastName. In the Map Attributes section enter these on the right side under SAML Response Attribute. on the left side, click the empty field box and select the pre-populated values that look like <Email Address>. Duo will automatically grab the corresponding fields and map them to the expected values.

You can map any values you like, but WorkOS requires that these four values are included in SAML responses. If your users don’t have a last name value for instance, you could map Display Name or any other value to lastName, but lastName still needs to be included or WorkOS will reject the SAML Response.

Here’s an example of the attribute mappings:

A screenshot showing where to configure SAML Attribute Mapping in Duo.

Users can automatically be assigned roles within your application by sending their group memberships. To enable this, set up a group attribute statement following the guidance below.

This feature is currently in beta, contact customer support for more information.

In the "Role Attributes" section, enter groups as the "Attribute name". Then map the role names to their corresponding Duo groups. In the example below, the "Admins" role is mapped to the Admins group and the "Developers" role is mapped to the Developers group.

A screenshot showing how to configure a groups attribute in Duo.

You may leave all of the other fields as their defaults. Scroll to the very bottom of the page and click the Save button.

A screenshot highlighting the finished SAML Configuration in Duo.

Navigate back to the WorkOS dashboard. After a minute or two you should see the Connection become Active as indicated by the green badge next to the connection name.

A screenshot highlighting active status of the Duo connection.