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
- Go to https://duo.com and click free signup and register.
- Log in to Duo Security. Click Applications from the left panel and then click the Protect an Application button.
- In the Protect an Application page, select Web SDK.
- 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.
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 [email protected] 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.
- Place the
duoauthenticationendpoint.warfile into the
org.wso2.carbon.identity.authenticator.duo-1.0.2.jarfile into the
If you want to upgrade the Duo Authenticator in your existing IS pack, please refer upgrade instructions.
You may have done this step already if you configured the Duo Security Provisioning Connector. If so, you can skip this step.
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.xmlfile under the
<AuthenticatorConfigs>section. This verification only requires the Admin API credentials.
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.xmlfile in the
This specifies whether the mobile number claim should be taken from the claims provided by the Identity Provider.
This specifies the value of the mobile claim provided by the Identity Provider. This property must be configured if the
This field can take one of the following values:
subjectUri. If you do not specify any use case, the default value is
The 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
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.
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.
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.xmlfile and put the value (e.g., email, screen_name, id, etc.).
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.xmlfile under the <
AuthenticatorConfigs> section as follows (the following shows the configuration for foursquare, LinkedIn and Facebook authenticator respectively).
AuthenticatorConfig(i.e., Foursquare), add the specific
userAttributewith a prefix of the (current step) authenticator name (i.e., SMSOTP-userAttribute).
Likewise, you can add the AuthenticatorConfig for amazon, Google, Twitter, and Instagram with relevant values.
subjectUri When 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.
- Download the WSO2 Identity Server from here and run it.
- Log in to the management console as an administrator.
- In the Identity section under the Main tab of the management console, click Add under Identity Providers.
- Give a suitable name as the Identity Provider Name.
- Go to Duo Configuration under Federated Authenticators.
- 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.
- Select both check-boxes to Enable the Duo Authenticator and make it the Default.
- Click Register.
Configuring the service provider
The next step is to configure the service provider.
Return to the management console.
In the Service Providers section under the Main tab, click Add.
Since you are using travelocity as the sample, enter travelocity.com in the Service Provider Name text box and click Register.
In the Inbound Authentication Configuration section, click Configure under the SAML2 Web SSO Configuration section.
Now do the following configurations.
Assertion Consumer URL: http://localhost:8081/travelocity.com/home.jsp
- Select the following check boxes:
Enable Response Signing.
Enable Single Logout.
Enable Attribute Profile.
- Include Attributes in the Response Always.
- Click Update to save the changes. Now you will be sent back to the Service Providers page.
- Go to Local and Outbound Authentication Configuration section.
- Select the Advanced Configuration radio button option.
- Add the basic authentication as the first step and Duo authentication as the second step and click Update to save the changes.
Testing the sample
To test the sample, go to the following URL:
Click the link to log in with SAML from WSO2 Identity Server.
- The basic authentication page appears. Log in using your username and password.
- You are directed to the Duo Security authentication page.
- If your verification is successful, you are taken to the home page of the travelocity.com app.