This site contains the documentation that is relevant to older WSO2 product versions and offerings.
For the latest WSO2 documentation, visit https://wso2.com/documentation/.

Configuring Duo Security Authenticator

Owned by Former user (Deleted)
Last updated: Oct 01, 2020 by Former user (Deleted)
6 min read

This topic provides instructions on how to configure the Duo Security app and the Identity Server. A sample app is used to demonstrate this integration. See the following sections for more information.

This is tested for the Duo Security API version V2.

See the following sections for more information.

Configuring the Duo Security app

  1. Go to https://duo.com and click free signup and register.
  2. Log in to Duo Security. Click Applications from the left panel and then click the Protect an Application button.
     
  3. In the Protect an Application page, select Web SDK.
  4. Once the integration is created, you are given a Secret key and an Integration key for your integration. You can use these along with your Duo host when accessing Duo Security APIs.

  5. You can also configure the Admin API credentials if you need to validate the mobile numbers. When you verify the mobile number, use only these credentials. Navigate back to the Protect an Application  page and select  Admin API  from the list.  Once the Integration is created, you are given a Secret key and an Integration key for your integration.

    Important : If you can not see the type “Admin API” in the dropdown, contact the Duo team through support@duosecurity.com and ask for Admin API permission.

    When configuring the Admin API, select the Grant read resource permission.

    Tip: This step is mandatory if you need to verify the user's mobile number in the user store with the mobile number in Duo Security. This is configured in step 4 of Deploying Duo Security artifacts.

Deploying Duo Security artifacts

To download the authenticator and artifacts, go to the WSO2 store.

  1. Place the duoauthenticationendpoint.war file into the <IS_HOME>/repository/deployment/server/webapps directory.

  2. Place the org.wso2.carbon.identity.authenticator.duo-1.0.2.jar file into the <IS_HOME>/repository/components/dropins directory.

    If you want to upgrade the Duo Authenticator in your existing IS pack, please refer upgrade instructions.

  3. Place the okio-1.9.0.jar  into the <IS_HOME>/repository/components/lib directory.

    You may have done this step already if you configured the Duo Security Provisioning Connector. If so, you can skip this step.

  4. Optionally, to verify the user store user's mobile number with the same user's mobile number in Duo Security, add the following to the   <IS_HOME>/repository/conf/identity/application-authentication.xml file under the <AuthenticatorConfigs> section. This verification only requires the Admin API credentials.

    <AuthenticatorConfig name="DuoAuthenticator" enabled="true">
     <Parameter name="EnableMobileVerification">true</Parameter>
</AuthenticatorConfig>

  5. Optionally, if Duo authenticator is configured as the second factor in multi-factor authentication where a federated identity provider is configured as the first step, the following properties should be configured in the application-authentication.xml file in the <IS_HOME>/repository/conf/identity directory.

    <AuthenticatorConfig name="DuoAuthenticator" enabled="true">
     ...
          <Parameter name="usecase">association</Parameter>
          <Parameter name="sendDuoToFederatedMobileAttribute">true</Parameter>
          <Parameter name="federatedMobileNumberAttributeKey">http://wso2.org/claims/mobile</Parameter>
          <Parameter name="secondaryUserstore">primary</Parameter>
     ...
</AuthenticatorConfig>
    ValueDescription
    sendDuoToFederatedMobileAttributeThis specifies whether the mobile number claim should be taken from the claims provided by the Identity Provider.
    federatedMobileNumberAttributeKeyThis specifies the value of the mobile claim provided by the Identity Provider. This property must be configured if the useFederatedMobileClaim is true.
    usecaseThis field can take one of the following values: local, association, userAttribute, subjectUri. If you do not specify any use case, the default value is local.
    secondaryUserstoreThe user store configuration is maintained per tenant as comma-separated values. For example, <Parameter name="secondaryUserstore">jdbc, abc, and xyz</Parameter>.

    The usecase value can be local, association,  userAttribute  or  subjectUri .

    local

    This is based on the federated username. This is the default value. You must set the federated username in the local user store. Basically, the federated username must be the same as the local username.

    association

    The federated username must be associated with the local account in advance in the Dashboard. So the local username is retrieved from the association. To associate the user, log into the end user dashboard and go to Associated Account by clicking View details.

    userAttribute

    The name of the federated authenticator's user attribute. That is the local user name that is contained in a federated user's attribute. When using this, add the following parameter under the <AuthenticatorConfig name="DuoAuthenticator" enabled="true"> section in the <IS_HOME>/repository/conf/identity/application-authentication.xml file and put the value (e.g., email, screen_name, id, etc.).

    <Parameter name="userAttribute">email</Parameter>

    If you use, OpenID Connect supported authenticators such as LinkedIn, Foursquare, etc., or in the case of multiple social login options as the first step and Duo Authenticator as the second step, you need to add similar configuration for the specific authenticator in the <IS_HOME>/repository/conf/identity/application-authentication.xml file under the <AuthenticatorConfigs> section as follows (the following shows the configuration for foursquare, LinkedIn and Facebook authenticator respectively).

    Inside the AuthenticatorConfig (i.e., Foursquare), add the specific userAttribute with a prefix of the (current step) authenticator name (i.e., SMSOTP-userAttribute).

    <AuthenticatorConfig name="Foursquare" enabled="true">
       <Parameter name="DuoAuthenticator-userAttribute">http://wso2.org/foursquare/claims/email</Parameter>
</AuthenticatorConfig>
    <AuthenticatorConfig name="LinkedIn" enabled="true">
   <Parameter name="DuoAuthenticator-userAttribute">http://wso2.org/linkedin/claims/emailAddress</Parameter>
</AuthenticatorConfig>
    <AuthenticatorConfig name="FacebookAuthenticator" enabled="true">
	<Parameter name="DuoAuthenticator-userAttribute">email</Parameter>
</AuthenticatorConfig>

    Likewise, you can add the AuthenticatorConfig for amazon, Google, Twitter, and Instagram with relevant values.

    subjectUriWhen configuring the federated authenticator, select the attribute in the subject identifier under the service provider section in UI, this is used as the username of the Duo authenticator.

Tip: Duo Security mainly uses Mobile Phone two-factor authentication to ensure secure login.

Important: When you update the mobile claim in the user profile, use the same format of mobile number with country code as you registered in the DUO site. (i.e +9477*******)


Deploying travelocity.com sample app

The next step is to deploy the travelocity.com sample app in order to use it in this scenario.

To do this, see the topic on deploying the travelocity.com sample app.

Configuring the identity provider

Now you have to configure WSO2 Identity Server by adding a new identity provider.

  1. Download the WSO2 Identity Server from here and run it.
  2. Log in to the management console as an administrator.
  3. In the Identity section under the Main tab of the management console, click Add under Identity Providers.
  4. Give a suitable name as the Identity Provider Name.
  5. Go to Duo Configuration under Federated Authenticators.
  6. Enter the values for Integration Key, Secret Key, Admin Integration Key,  Admin Secret Key ( Admin Integration Key and Admin Secret Key are optional) and Host, as indicated in the above figure.
  7. Select both check-boxes to Enable the Duo Authenticator and make it the Default.
  8. Click Register.
You have now added the identity provider.

Configuring the service provider

The next step is to configure the service provider.

  1. Return to the management console.

  2. In the Service Providers section under the Main tab, click Add.

  3. Since you are using travelocity as the sample, enter travelocity.com in the Service Provider Name text box and click Register.

  4. In the Inbound Authentication Configuration section, click Configure under the SAML2 Web SSO Configuration section.

  5. Now do the following configurations.

    1. Issuer: travelocity.com

    2. Assertion Consumer URL: http://localhost:8081/travelocity.com/home.jsp

  6. Select the following check boxes:

    1. Enable Response Signing.

    2. Enable Single Logout.

    3. Enable Attribute Profile.

    4. Include Attributes in the Response Always.
  7. Click Update to save the changes. Now you will be sent back to the Service Providers page.
  8. Go to Local and Outbound Authentication Configuration section.
  9. Select the Advanced Configuration radio button option.
  10. Add the basic authentication as the first step and Duo authentication as the second step and click Update to save the changes.
You have now added and configured the service provider.

Testing the sample

  1. To test the sample, go to the following URL: http://<TOMCAT_HOST>:<TOMCAT_PORT>/travelocity.com/.  
    E.g:http://localhost:8080/travelocity.com

  2. Click the link to log in with SAML from WSO2 Identity Server. 

  3. The basic authentication page appears. Log in using your username and password.
  4. You are directed to the Duo Security authentication page.
  5. If your verification is successful, you are taken to the home page of the travelocity.com app.