Skip navigation
Documentation

Duo Access Gateway - Generic SAML Service Providers

Last Updated: May 26th, 2022

Duo Access Gateway adds two-factor authentication, complete with inline self-service enrollment and Duo Prompt to cloud services.

Duo Access Gateway will reach end of life in October 2023. Customers may not create new DAG applications after May 19, 2022. Please see the Guide to Duo Access Gateway end of life for more details.

Use the Duo Single Sign-on Generic SAML Service Provider application to protect SAML applications with Duo Single Sign-On, our cloud-hosted identity provider featuring Duo Central and the Duo Universal Prompt.

Duo Access Gateway

Duo Access Gateway (DAG), our on-premises SSO product, layers Duo's strong authentication and flexible policy engine on top of your service provider application logins using the Security Assertion Markup Language (SAML) 2.0 authentication standard. Duo Access Gateway acts as an identity provider (IdP), authenticating your users using existing on-premises or cloud-based directory credentials and prompting for two-factor authentication before permitting access to your service provider application.

Duo Access Gateway is included in the Duo Premier, Duo Advantage, and Duo Essentials plans, which also include the ability to define policies that enforce unique controls for each individual SSO application. For example, you can require that Salesforce users complete two-factor authentication at every login, but only once every seven days when accessing your service provider application. Duo checks the user, device, and network against an application's policy before allowing access to the application.

We've already added a number of popular SaaS applications to Duo pre-configured for use with the Access Gateway. If you want to protect a cloud service that we don't have listed by name, you can use our generic SAML Service Provider application.

Prerequisites

Before you start you should have already deployed the Duo Access Gateway with a configured authentication source. You should also verify that your cloud app supports SAML 2.0 and locate their instructions for configuring SSO.

Create Your Cloud Application in Duo

Important: When you create your cloud application in Duo you download a configuration file. This file contains information that uniquely identifies this application to Duo. Secure this file as you would any other sensitive or password information. Don't share it with unauthorized individuals or email it to anyone under any circumstances!
  1. Log in to the Duo Admin Panel and click Applications on the left navigation, and then click Protect an Application.

  2. Click Protect an Application and locate the entry for Generic SAML Service Provider with a protection type of "2FA with SSO self-hosted (Duo Access Gateway)" in the applications list. Click Protect to the far-right to start configuring Generic SAML Service Provider. See Protecting Applications for more information about protecting applications in Duo and additional application options.

  3. Enter the following information about your cloud app vendor in the Service Provider section:

    Name Description
    Service Provider Name The name of the service provider.
    Entity ID The service provider identifier.
    Assertion Consumer Service The URL where your service provider receives SAML assertions.
    Single Logout URL Optional: The URL where your service provider receives SAML logout assertions.
    Service Provider Login URL Optional: Enter the URL for IdP-initiated logins if your service provider specifies one.
    Default Relay State Optional: If your service provider requires a specific RelayState parameter, enter it here.

    If your service provider requires IdP-initiated logins using SSO, the login URL is composed of the URL to your DAG logon page plus the entity id of the service to which you are authenticating, e.g. https://yourserver.example.com/dag/saml2/idp/SSOService.php?spentityid=Your_SP_Entity_ID.

  4. Use your service provider's SSO instructions to complete the SAML Response section:

    Name Description
    NameID format Format of NameID when sent to the service provider.
    NameID attribute The authentication source attribute used to identify the user to the service provider. This attribute is sent as the NameID. This is often a user's e-mail address ("mail" or "email"). See the list below for the names of common attributes from Duo Access Gateway authentication sources.
    Send attributes By default Duo Access Gateway sends only the NameID IdP attribute to a service provider. Change this option to "All" if your service provider requires additional attributes included in the SAML response. Mapping or creating any additional attributes will also cause Duo Access Gateway to send all attributes.
    Signature Algorithm Select the encryption strength supported by your service provider. Defaults to SHA-256.
    Sign response Leave this option enabled if the Duo Access Gateway needs to sign the SAML response to the service provider. Uncheck the box if the response should not be signed.
    Sign assertion Leave this option enabled if the DAG needs to sign the SAML assertion to the service provider. Uncheck the box if the assertion should not be signed.
    Map attributes If your service provider requires specific names for the attributes sent by the DAG identity provider, you can map the authentication source attributes to the required names here. Enter the attribute name from your authentication source on the left, and the new attribute name on the right. See the list below for the names of common attributes from Duo Access Gateway authentication sources. Consult your service provider's documentation for the required SAML Response Attribute names.
    Create attributes If your service provider requires that the DAG identity provider sends an attribute with a specific value, you can define that here. Enter the new attribute name on the left, and the static attribute value on the right. Consult your service provider's documentation for the required attribute names.

    Here's a list of attributes and the value you should use based on your Duo Access Gateway authentication source:

    Attribute Active Directory OpenLDAP SAML IdP Google Azure
    Mail attribute mail mail mail email mail
    Username attribute sAMAccountName uid mail email mail
    First name attribute givenName gn givenName given_name givenName
    Last name attribute sn sn sn family_name surname

    Here's an example generic SAML Service Provider configuration:

    Generic SAML Provider
  5. After entering the service provider information click the Save Configuration button and download the configuration file.

    Generic SAML Provider Download

Configure Allowed Hostnames

If you plan to permit use of WebAuthn authentication methods (security keys, U2F tokens, or Touch ID) in the traditional Duo Prompt, Duo recommends configuring allowed hostnames for this application and any others that show the inline Duo Prompt before onboarding your end-users.

The Duo Universal Prompt has built-in protection from unauthorized domains so this setting does not apply.

Add Your Cloud Application to Duo Access Gateway

  1. From the Duo Access Gateway server's console, click the Configure icon in the "Duo Access Gateway" application group to log on to https://yourserver.example.com/dag. Log in with the administrator password and click Applications.

  2. Click the Choose File button in the "Add Application" section of the page and locate the SAML application JSON file you downloaded from the Duo Admin Panel earlier. Click the Upload button after selecting the JSON configuration file.

    Upload Service Provider JSON
  3. The new SAML application is added.

    Upload Service Provider JSON
  4. You may want to customize the logo shown for a generic SAML application, as this logo is shown to users in the Duo Access Gateway Launcher. Duo's pre-defined SAML applications show the service provider's logo, while generic SAML apps show a Duo logo by default.

    To change the logo shown, click the Edit Logo button to the right of the SAML SP-initiated logon URL and default logo.

    Edit Generic SAML App Logo
  5. Select a PNG image to use for the generic SAML application's logo and then click Save

    Select Custom SAML App Logo
  6. Your generic SAML application now has a custom logo.

    Custom Generic SAML App Logo

Configure Your Service Provider

You'll need to provide some information about Duo Access Gateway to your cloud application provider, like URL information, a metadata file, a certificate file, or a certificate thumbprint. You can find this information in the "Metadata" section at the bottom of the Duo Access Gateway admin console's "Applications" page.

DAG Metadata Information

Refer to your service provider's SSO configuration guide for instructions.

Enable Remembered Devices

To minimize additional Duo two-factor prompts when switching between Duo Access Gateway SAML applications, be sure to apply a shared "Remembered Devices" policy to your new application. See the Duo Access Gateway with Remembered Devices instructions.