Configuring single sign-on with Duo Security

Edit online

Duo Security can be configured as the authentication provider for the system.

Duo Security does not support acting as an Identity Provider (IdP) for single sign-on. To use Duo for single sign-on, an alternative authentication source must be configured. Refer to the Duo Security documentation for Configure Your Authentication Source. You might also need to refer to the documentation for your chosen authentication source in order to integrate it with Duo Security.

Note: Ensure that the prerequisite tasks are completed on the system before you configure single sign-on. For more information, see the Prerequisites section in Configuring single sign-on.

Prerequisites

The following prerequisite steps on Duo Security must be completed before you can configure single sign-on on the system:
  1. Create a subscription for Duo Security. A 30-day free trial subscription is also available. For more information, see Sign Up for a Free Trial | Duo Security. During subscription creation, you specify a tenant that is used to create a URL to access the Duo Security dashboard.
  2. Access the Duo Security administrator dashboard by entering the following URL in a web browser:
    https://admin-tenant.duosecurity.com
    where tenant is the name of the tenant that you specified when you created your subscription. Usually, the tenant name is associated with your company or organization.
  3. In the Duo Security interface, select Applications > Protect an Application.
  4. Select Generic OIDC Relying Party.
    Note: Each system must be added as a separate application.
    The new application loads. The following table shows the required fields and actions for the Metadata section in the Duo Security interface.
    Table 1. Metadata section
    Field Action Details
    Client ID This value is automatically generated when the system is saved as an application. This value must be entered on the Single Sign-on page in the management GUI under OpenID Credentials.
    Client Secret This value is automatically generated when the system is saved as an application. This value must be entered on the Single Sign-on page in the management GUI under OpenID Credentials.
    Discovery URL Indicates the OpenID Connect configuration end point URL of the authentication server. This value must be entered on the Single Sign-on page in the management GUI under Authentication server.
    The following table shows the required fields and actions for the Relying Party section in the Duo Security interface.
    Table 2. Relying Party section
    Field Action Details
    Grant Type Select Authorization Code. Authorization code indicates that the client can request access to protected resources on behalf of users.
    Sign-in Redirect URLs Enter the locations where the authorization server sends users after they are successfully authorized and granted an authorization code or access token. Multiple redirect URIs can be specified for the management GUI. For management GUI access, the redirect URI consists of the management IP address or hostname followed by /sso. For example,
    https://hostname.com/sso
    Note: Duo Security does not support the use of IP addresses when accessing your system by using a web browser. Once single sign-on is configured, make sure that a hostname is used when accessing your system by using a web browser.
    The following table shows the required fields and actions for the OIDC Response section in the Duo Security interface. In this section, you configure the OpenID Connect response from Duo Security to the system during authentication. Depending on the name of the IdP attributes on your authentication source, you create mappings between the IdP attributes (for example a SAML attribute sent back from your authentication source) and the claims that Duo Security sends back in the OIDC response.
    Table 3. OIDC Response section
    Field Action Details
    Scopes Select openid and profile.

    After selecting profile, a list of IdP Attribute and Claim mappings will appear.

    Ensure at least two attributes (username and group) are mapped correctly to claims in the OIDC response. For example, to map an IdP Attribute called Username from your authentication source, enter Username into the IdP Attribute field.

    You can choose the name of the claim that gets sent back in the OIDC response to the system. For example, to map the IdP Attribute called Username to an OIDC claim called groups, enter groups in the Claim field.
    Additional Scopes No action is required. Additional scopes are not required.

    Optionally, configure the policy settings for this application in the Policy section.

    The following table shows the required fields and actions for the Settings section in the Duo Security interface.

    Table 4. Settings section
    Field Action Details
    Name Enter a name. Enter a name to identify the system on Duo Security. If you are adding multiple systems, enter a unique name.
    Additional Scopes No action is required. Additional scopes are not required.
  5. Click Save. After the system is saved as a new application, the application reloads with the chosen settings.

Using the management GUI

To configure single sign-on with Duo Security, complete these steps:
  1. Select Settings > Security > Single Sign-on.
  2. Enter the OpenID Configuration Endpoint URL of the authentication server. This is the Discovery URL from the Metadata settings of the application you created earlier in Duo Security. For Duo Security, it is in the following format:
    https://sso-tenant.sso.duosecurity.com/oidc/clientid/.well-known/openid-configuration
    where tenant is the name that is associated with your subscription, and clientid is the client ID that is associated with your application.
  3. For the OpenID Credentials, add the Client ID and Client Secret that you copied on from the Sign-on tab in the Duo Security interface.
  4. For the User claim, the value to enter depends on how your authentication provider is configured. The User claim must match the name that the authentication service uses to specify the username attribute in the ID Token of the OIDC response it sends to the system. Use the Claim name that maps to your username IdP Attribute from the OIDC Response section of your application.
  5. For the Group claim, the value to enter depends on how your authentication provider is configured. The Group claim must match the name that the authentication service uses to specify the group attribute in the ID Token of the OIDC response it sends to the system. Use the Claim name that maps to your group IdP Attribute from the OIDC Response section of your application.
  6. For Proxy server, consider how the system accesses the authentication provider. For an authentication provider within your network, a proxy server usually is not needed. If you connect to the authentication provider through the Internet, check the box, and ensure that a proxy server is defined on the system.
  7. Click Save. On the confirmation page, click Confirm to enable single sign-on for the system.

Single sign-on is enabled for the system. You can configure user groups to use single sign-on. Click Navigate to launch the User Groups page.

Using the command-line interface

To enable single sign-on, enter the following command:

https://sso-tenant.sso.duosecurity.com/oidc/clientid/.well-known/openid-configuration

In the example, tenant is the tenant name that is associated with your subscription, and clientid is the client ID that is associated with your application. The values for the -clientid and the -clientsecret are the Open ID Client and Open ID Secret that are automatically generated when you created your system as an application in Duo Security, and are displayed in the Metadata section of the application on the Duo Security interface. The values for the -userclaim and the -groupclaim must match the name of the claims that are configured for the ID Token in the OIDC Response section of the application on the authentication provider.