Versions Compared

Old Version 150

changes.mady.by.user Former user

Saved on

compared with

New Version 151

changes.mady.by.user Former user

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

This topic provides instructions on how to configure the TOTP authenticator and the Identity Server to integrate using a sample app. See the following sections for more information.

...

Anchor
Configuring User Claims
Configuring User Claims
Configuring user claims

  1. Download the WSO2 Identity Server from here and run it.
  2. Sign in to the Management Console by entering your username and password.
  3. In the Main menu, click Add under Claims.

  4. Click Add Local Claim. This displays the Add Local Claim screen.

    Note
    titleNote

    If you are using WSO2 Identity Server version 5.1.0 or 5.2.0, click Add New Claim. This displays the Add New Claim screen. On the Add New Claim screen, select http://wso2.org/claims as the Dialect.

  5. Specify the following claim details in the appropriate fields:

    Claim URIhttp://wso2.org/claims/identity/secretkey
    Display NameSecret Key
    DescriptionClaim to store the secret key
    Mapped Attribute

    State or province name

    Supported by Defaultselected

Anchor
Deploying TOTP artifacts
Deploying TOTP artifacts
Deploying TOTP artifacts

Note
titleNote

If you are using WSO2 Identity Server 5.6.0, you can skip steps 1 to 3 in the following section because totpauthenticationendpoint.war and org.wso2.carbon.extension.identity.authenticator.totp.connector-x.x.x.jar files are already packaged in the appropriate directories in the product distribution.

  1. Download the required TOTP artifacts from WSO2 Store. 

    Note

    If you are using WSO2 Identity Server version 5.5.0 or older, follow the steps below to manually add the commons-codec_1.4.0.wso2v1.jar file to WSO2 Identity Server:

    1. Create a directory with the name of the patch (for example, patch001) in the <IS_HOME>/repository/components/patches directory.
    2. Copy the commons-codec_1.4.0.wso2v1.jar file from the downloaded other_artifacts directory to the directory that you created in the above step.
  2. Place the totpauthenticationendpoint.war file into the <IS_HOME>/repository/deployment/server/webapps directory.

  3. Place the org.wso2.carbon.extension.identity.authenticator.totp.connector-x.x.x.jar into the <IS_HOME>/repository/components/dropins directory.

    Note

    If you want to upgrade the TOTP Authenticator that is available in your existing WSO2 Identity Server distribution, see the upgrade instructions.

  4. Add the following configuration  <IS_HOME>/repository/conf/identity/application-authentication.xml file under the <AuthenticatorConfigs> section. 

    Code Block
    languagexml
    <AuthenticatorConfig name="totp" enabled="true">
            <Parameter name="encodingMethod">Base32</Parameter>
            <Parameter name="timeStepSize">30</Parameter>
            <Parameter name="windowSize">3</Parameter>
            <Parameter name="authenticationMandatory">true</Parameter>
            <Parameter name="enrolUserInAuthenticationFlow">true</Parameter>
            <Parameter name="usecase">userAttribute<>local</Parameter>
      <Parameter name="userAttribute">http://wso2.org/foursquare/claims/email</Parameter>     <Parameter name="secondaryUserstore">primary</Parameter>
            <Parameter name="TOTPAuthenticationEndpointURL">totpauthenticationendpoint/totp.jsp</Parameter>
            <Parameter name="TOTPAuthenticationEndpointErrorPage">totpauthenticationendpoint/totpError.jsp</Parameter>
            <Parameter name="TOTPAuthenticationEndpointEnableTOTPPage">https://localhost:9443/totpauthenticationendpoint/>totpauthenticationendpoint/enableTOTP.jsp</Parameter>
      <Parameter name="redirectToMultiOptionPageOnFailure">false</Parameter>     <Parameter name="Issuer">WSO2</Parameter>
	
            <Parameter name="UseCommonIssuer">true</Parameter>
        </AuthenticatorConfig>

    The following table describes the definition of the parameters and the various values you can configure for federated authentication.

    FieldDescription
    usecase

    This field can take one of the following values: local, association, userAttribute, subjectUri. If you do not specify any usecase, the default value is local.

    Tip

    If you have chosen userAttribute as the usecase, add the following parmeter to specify the user attribute.

    Code Block
    <Parameter name="userAttribute">http://wso2.org/foursquare/claims/email</Parameter>
    encodingMethod

    The encoding method which is used to generate the TOTP.

    authenticationMandatory
    		If this value is true, the TOTP authentication will be enforced as a second step.
    timeStepSize

    The time step size, which is used to validate the TOTP.

    windowSize
    		The window size, which is used to validate the TOTP.
    enrolUserInAuthenticationFlow
    		If this value is true, it will ask the user to enable the TOTP authenticator in the authentication flow. 
    secondaryUserstore

    The user store configuration is maintained per tenant as comma separated values. For example, <Parameter name="secondaryUserstore">jdbc, abc, xyz</Parameter>. 

    TOTPAuthenticationEndpointURL

    This is the endpoint of the UI which is used to gather the TOTP.

    TOTPAuthenticationEndpointErrorPage
    		This is the endpoint of the error page.
    TOTPAuthenticationEndpointEnableTOTPPage
    		This is the endpoint of the TOTPauthenticator enrollment page.
    Issuer
    		This is the issuer name which will be shown the Mobile Application. If not configured, tenant domain will be shown.
    UseCommonIssuer
    		If true, the issuer name defined in application-authentication.xml will be used as the issuer for all the tenants.

  5. Place the authenticator parameters as above into the <IS_HOME>/repository/conf/identity/application-authentication.xml file.  An admin can activate the feature to enable the TOTP authenticator in the authentication flow by changing the enrolUserInAuthenticationFlow values (true or false). 

    1. If you specify that the user can enable TOTP in the authentication flow (<Parameter name="enrolUserInAuthenticationFlow">true</Parameter>) and the TOTP is not enabled to the user's profile, you will be asked to enable TOTP in the in the authentication flow. If you don't enable it at this stage, the TOTP error page appears. 
    2. If you specify that the user can't enable TOTP in the authentication flow (<Parameter name="enrolUserInAuthenticationFlow">false</Parameter>) and the TOTP is not enabled to the user's profile, the TOTP error page appears. 
  6. Replace the <IS_HOME>/repository/deployment/server/jaggeryapps/portal/gadgets/user_profile file with the corresponding user-profile provided under other_artifacts/user_profiles/.
    • Use 5.1.0/user_profile if you are using WSO2 Identity Server 5.1.0.
    • Use 5.2.0/user_profile if you are using WSO2 Identity Server 5.2.0.
    • Use 5.2.0/wum_update/user_profile if you are using WSO2 Identity Server 5.2.0 wum updated pack.
    • Use 5.3.0/user_profile if you are using WSO2 Identity Server 5.3.0.
    Note

    This step must be done since the user_profile that is shipped with the WSO2 Identity Server does not support TOTP out-of-the-box. Due to some changes in the Identity Server framework for each product release version, a different user profile is required for different versions. However, if you are using WSO2 Identity Server 5.4.0 upwards, then you do not need to replace the user_profile since WSO2 Identity Server has corresponding user_profile required out-of-the-box.

    Info

    Comment the <module ref="addressing"/> module from the <IS_HOME>/repository/conf/axis2/axis2.xml file.

  7. If you use the secondary user store, enter all the user store values for the particular tenant as comma separated values. Make this configuration change in the <IS_HOME>/repository/conf/identity/application-authentication.xml file under the AuthenticatorConfigs section. For example, <Parameter name="secondaryUserstore"> jdbc, abc, xyz</Parameter>.

Info

The user store configuration is maintained per tenant:

  • If you use a super tenant, put all the above parameter values (mentioned in step 4) into the <IS_HOME>/repository/conf/identity/application-authentication.xml file under the AuthenticatorConfigs section.
  • If you use a tenant, upload the same XML file (application-authentication.xml) into a specific registry location (/_system/governance/totp). Create the collection named totp, add the resource and upload the application-authentication.xml file into the registry) . While doing the authentication, first it checks whether there is an XML file uploaded to the registry. If that is so, it reads it from the registry but does not take the local file. If there is no file in the registry, then it only takes the property values from the local file. This is how the user store configuration is maintained per tenant. You can use the registry or local file to get the property values. 


Anchor
Deploying travelocity.com sample app
Deploying travelocity.com sample app
Deploying travelocity.com sample app

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

Once this is done, the next step is to configure the WSO2 Identity Server by configuring resident identity provider and service provider.

Anchor
Configuring the identity provider
Configuring the identity provider
Configuring the identity provider

Now you have to configure WSO2 Identity Server.

  1. Restart WSO2 Identity Server.
  2. Log in to the management console as an administrator.
  3. Login to the end user dashboard and go to My Profile by clicking View details.
  4. Update your email address (this email address is used to send the token). 
  5. To enable TOTP, select the Enable TOTP checkbox. 
  6. If you want to use the Google Authenticator Application to generate the one-time passwords (tokens), click on Scan QR Code to scan the QR-Code using the Google Authenticator mobile app.

You have now configured TOTP.

Info
titleObtaining the QR code without using the end user dashboard

If you need to obtain the QR code without using the end user dashboard, you can call an Admin Service that does this. The following is the Admin Service used to obtain the QR code.

Code Block
https://localhost:9443/services/TOTPAdminService?wsdl

The QR code URL can be retrieved using the initTOTP method in the TOTPAdminService.

The following is a sample cURL command that invokes the TOTPAdminService.

Code Block
curl -i -X POST -H 'Content-Type: application/x-www-form-urlencoded' -H 'Authorization:Basic YWRtaW46YWRtaW4=' https://localhost:9443/services/TOTPAdminService/initTOTP -k -d 'username=testuser@carbon.super'

The following is a sample response that is obtained.

Code Block
<ns:initTOTPResponse xmlns:ns="http://services.totp.authenticator.application.identity.carbon.wso2.org"><ns:return>b3RwYXV0aDovL3RvdHAvY2FyYm9uLnN1cGVyOmR1c2hhbmk/c2VjcmV0PUJGR0RFUllPU1ZSR0s3&#xd;
TE0maXNzdWVyPWNhcmJvbi5zdXBlcg==&#xd;
</ns:return></ns:initTOTPResponse>

The Secret Key can be retrieved using the retrieveSecretKeymethod in the TOTPAdminService.

The following is a sample cURL command that invokes the TOTPAdminService.

Code Block
curl -i -X POST -H 'Content-Type: application/x-www-form-urlencoded'  -H 'Authorization:Basic YWRtaW46YWRtaW4=' https://localhost:9443/services/TOTPAdminService/retrieveSecretKey -k -d 'username=testuser@carbon.super'

The following is a sample response that is obtained.

Code Block
<ns:retrieveSecretKeyResponse xmlns:ns="http://services.totp.authenticator.application.identity.carbon.wso2.org"><ns:return>4AAC2HEG7COGHQYI</ns:return></ns:retrieveSecretKeyResponse>


Anchor
Configuring Identity Server to send email
Configuring Identity Server to send email
Configuring the Identity Server to send email

  1. Configure the <IS_HOME>/repository/conf/axis2/axis2.xml to send an email notification. Enable the mailto transport sender by adding the following configuration. Replace your sender email credentials (USER_NAME, PASSWORD, and SENDER'S_MAIL) in the configuration.

    Code Block
    languagexml
    titleSMTP Transport Sender
    <transportSender name="mailto" class="org.apache.axis2.transport.mail.MailTransportSender">
    <parameter name="mail.smtp.host">smtp.gmail.com</parameter>
    <parameter name="mail.smtp.port">587</parameter>
    <parameter name="mail.smtp.starttls.enable">true</parameter>
    <parameter name="mail.smtp.auth">true</parameter>
    <parameter name="mail.smtp.user">{USER_NAME}</parameter>
    <parameter name="mail.smtp.password">{PASSWORD}</parameter>
    <parameter name="mail.smtp.from">{SENDER'S_MAIL}</parameter>
</transportSender>

  2. Add the email template that must be sent to the user when they generate the token in the  <IS_HOME>/repository/conf/email/email-admin-config.xml file as follows.

    Code Block
    languagexml
    titleEmail Template
    <configuration type="totp" display="TOTP" locale="en_US">
    <targetEpr></targetEpr>
    <subject>WSO2 Carbon - Time-Based One Time Password</subject>
    <body>
Hi {{ user.claim.givenname}},
Please use the token {totp-token} as the password for your login.
    </body>
    <footer>
Best Regards,
WSO2 Identity Server Team
http://www.wso2.com
    </footer>
    <redirectPath></redirectPath>
</configuration>  

Anchor
Configuring the service provider
Configuring the service 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 travelocityas the sample, enter travelocity.com in the Service Provider Name text box.

  4. Enable " SaaS Application" if you want to open up the application for all the users of all the tenants and click Register.

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

  6. Now set the configuration as follows:

    1. Issuer: travelocity.com

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

  7. Selectthefollowingcheck-boxes:

    1. Enable Response Signing.

    2. Enable Single Logout.

    3. Enable Attribute Profile.

    4. Include Attributes in the Response Always.

  8. Click Update to save the changes. Now you are sent back to the Service Providers page.

  9. Go to the Local and Outbound Authentication Configuration section.

  10. Select the Advanced configuration radio button option.

  11. Add basic or federated authentication as the first step and TOTP authentication as the second step and click Update to save the changes.The first step may be local authenticator (basic) or a federated authenticator (e.g., Facebook, Twitter, etc.)

    1. Select the local authenticator in the first step then select the local authenticator (e.g., basic) from the drop-down.

    2. Select the federated authenticator in the first step, then select federated authenticator (e.g., Twitter) from the drop-down.

    3. Configure the following parameter in the <IS_HOME>/repository/conf/identity/application-authentication.xml file under the  <AuthenticatorConfig name="totp" enabled="true"> section.

      Code Block
      languagexml
      <Parameter name="usecase">userAttribute</Parameter>

      The following table includes the definition of the parameter and the various values you can choose.

      ValueDescription
      usecase

      This field can take one of the following values: local, association, userAttribute, and subjectUri. If you do not specify any usecase, the default value is local.

      local

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

      association

      Federated username must be associated with the local account in advance in the Dashboard. So local username is retrieved from the association.To associate the user, Login to 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 username which is contained in a federated user's attribute. When using this, add the following parameter under the <AuthenticatorConfig name="totp" 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.).

      Code Block
      languagexml
      <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 TOTP as 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.,totp-userAttribute).

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

      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 TOTP authenticator.

      The configuration in the <IS_HOME>/repository/conf/identity/application-authentication.xml file under the AuthenticatorConfigs section will look like the following.

      Code Block
      languagexml
      titleParameter Values
      <AuthenticatorConfig name="totp" enabled="true">
    <Parameter name="encodingMethod">Base32</Parameter>
    <Parameter name="timeStepSize">30</Parameter>
    <Parameter name="windowSize">3</Parameter>
    <Parameter name="authenticationMandatory">true</Parameter>
    <Parameter name="enrolUserInAuthenticationFlow">true</Parameter>
    <Parameter name="usecase">userAttribute</Parameter>
    <Parameter name="userAttribute">http://wso2.org/foursquare/claims/email</Parameter>
    <Parameter name="secondaryUserstore">primary</Parameter>
    <Parameter name="TOTPAuthenticationEndpointURL">https://localhost:9443/totpauthenticationendpoint/totp.jsp</Parameter>
    <Parameter name="TOTPAuthenticationEndpointErrorPage">https://localhost:9443/totpauthenticationendpoint/totpError.jsp</Parameter>
    <Parameter name="TOTPAuthenticationEndpointEnableTOTPPage">https://localhost:9443/totpauthenticationendpoint/enableTOTP.jsp</Parameter>
</AuthenticatorConfig>
Tip

Tip: This is done to configure multi-factor authentication. See Multi-factor Authentication for more information.

You have now added and configured the service provider.

Anchor
Testing the sample
Testing the sample
Testing the sample

  1. To test the sample, go to the following URL: http://<TOMCAT_HOST>:<TOMCAT_PORT>/travelocity.com/index.jsp. For example, this looks like http://localhost:8080/travelocity.com.

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

  3. The basic authentication page is visible. Use your username and password to log in.
  4. If the TOTP is not enabled toin the user's profile and the user is allowed to enable the TOTP in the authentication flow, this page will appear. You can scan either continue or cancel.
  5. If you want to enrolthe user, click on the link to show the QR code. Scan the displayed QR code using the mobile application and continue.
  6. You are redirected to the TOTP authentication page. Enter the verification code from your Google Authenticator Mobile Application to authenticate. Alternatively, you can generate the verification code by clicking on Get a Verification Code" and use the code that is sent to your email address.

  7. If your verification is successful, you are taken to the home page of the travelocity.com app.

Anchor
Refreshing the Secret Key
Refreshing the Secret Key
Refreshing the secret key

You can refresh the secret key by selecting the Refresh Secret Keycheckbox in the dashboard. However, you must re-scan the QR code to sync the new secret key with your Google Authenticator mobile app.