This section provides instructions on how to configure the Token2 authenticator and WSO2 Identity Server using a sample app. See the following sections for more information.
Deploying Token2 artifacts
The artifacts can be obtained from the store for this authenticator.
- Place the
token2authenticationendpoint.war file into the <IS_HOME>/repository/deployment/server/webapps directory. Place the org.wso2.carbon.extension.identity.authenticator.token2.connector-1.0.0.jar file into the <IS_HOME>/repository/components/dropins directory.
Configuring the Token2 hardware device
- Register a Token2 account using "https://token2.com/register". Ensure that you do the following.
- Enter the Mobile phone number in e164 format (+94 77 ** ** ***)
- Select SMS Based as the User type.
- Click Register.
- Once you have registered with Token2, log in using your email, password and the OTP that is sent to the registered mobile number through Token2.
- Add a new site using "https://token2.com/manage" and obtain the API Key and site_id for the site.
- As mentioned in the Token2 API page, create the user and you can find the userid in the response.
- You have to obtain the hardware token device and send the userid, site_id and token serial number to Token2 support to enable it.
- Then logout and login again with your email, password and use the token generated in the hardware token device.
You have now enabled the token2 hardware device.
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 adding an identity provider and a service provider.
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.
- Run the WSO2 Identity Server.
- Log in to the management console as an administrator.
- In the Identity Providers section under the Main tab of the management console, click Add.
- Give a suitable name for Identity Provider Name (e.g., token2).
- Navigate to Token2Authenticator Configuration under Federated Authenticators.
Select both check boxes to Enable the Token2 authenticator and make it the Default.
Enter the following values:
- Click Register.
You have now added the identity provider.
Configuring user claims
- In the Main menu, click Add under Claims.
- Click Add New Claim.
Click Add Local Claim. The Dialect URI will be automatically set to http://wso2.org/claims, which is the internal claim dialect.
| Claim details | Description | Sample |
|---|
| Claim URI | This is the URI defined under the dialect, specific to the claim. There are different URIs available in the Identity Server and these equate to user attributes displayed in the profile of users. These URIs are mapped to the attributes in the underlying user store. | http://wso2.org/claims/identity/userid |
| Display Name | This is the name of the claim displayed on the UI. This can be viewed in the user's profile by navigating to the Main tab in the management console and clicking List in Users and Roles. In the resulting page, click Users and in the list of users that is displayed, click User Profile next to the one you wish to check. | User Id |
| Description | This gives you the option to describe the functionality of the claim. | Claim to User Id |
| Mapped Attribute | This is the corresponding attribute name from the underlying user store that is mapped to the Claim URI value.
When you have multiple user stores connected to the Identity Server, this maps the equivalent attribute in all of them to the Claim URI you are configuring.
For example, if you specify the cn attribute, this is mapped to the cn attribute in all the connected user stores. If you want to specify the attribute in a specific user store, you must add the domain name in addition to the mapped claim. For example, in a scenario where you have a primary user store configured called PRIMARY and secondary user stores called AD (representing Active Directory), you can map an attribute from each of these user stores to the Claim URI value by clicking Add Attribute Mapping, selecting the respective user store from the drop-down list, and mentioning the attribute of the userstore the attribute needs to be mapped to.
Example:
 | stateOrProvinceName |
| Regular Expression | This is the regular expression used to validate inputs. Example : For a claim URI like http://wso2.org/claims/email the regex should be something like ^([a-zA-Z0-9_\-\.]+)@([a-zA-Z0-9_\-\.]+)\.([a-zA-Z]{2,5})$ .This will validate the claim value and will not let other values except an email. |
|
| Display Order | This enables you to specify the order in which the claim is displayed, among the other claims defined under the same dialect. |
|
| Supported by Default | If unchecked, this claim will not be prompted during user registration. |
|
| Required | This specifies whether this claim is required for user registration. |
|
| Read-only | This specifies whether the claim is read-only or not. If the claim is read-only, it can't be updated by the user. |
|
| Additional Properties | These properties are not currently used in current WSO2 Identity server. If we need to write an extension using current claims, we can use these property values. |
|
- Next click List under Main > Identity > Users and Roles.
- Click User Profile under Admin and update the User Id.
Now you have configured the claim.
Configuring the service provider
The next step is to configure the service provider.
Return to the management console.
In the Identity section under the Main tab, click Add under Service Providers.
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.
Click here to view the field definitions
| Field | Description | Sample value |
|---|
| Issuer | Specify the Issuer. This is the <saml:Issuer> element that contains the unique identifier of the service provider. This is also the issuer value specified in the SAML Authentication Request issued by the service provider. When configuring single-sign-on across Carbon servers, ensure that this value is equal to the ServiceProviderID value mentioned in the <IS_HOME>/repository/conf/security/authenticators.xml file of the relying party Carbon server. | travelocity.com |
| Assertion Consumer URLs | Specify the Assertion Consumer URLs. This is the URL to which the browser should be redirected to after the authentication is successful. This is the Assertion Consumer Service (ACS) URL of the service provider. The identity provider redirects the SAML2 response to this ACS URL. However, if the SAML2 request is signed and SAML2 request contains the ACS URL, the Identity Server will honor the ACS URL of the SAML2 request. It should have this format: https://(host-name):(port)/acs. You can add multiple assertion consumer URLs for the service provider by entering the URL and clicking the Add button. | http://wso2is.local:8080/travelocity.com/home.jsp |
| Default Assertion Consumer URL | Since there can be multiple assertion consumer URLs, you must define a Default Assertion Consumer URL in case you are unable to retrieve it from the authentication request. | http://wso2is.local:8080/travelocity.com/home.jsp |
| NameID format | Specify the NameID format. This defines the name identifier formats supported by the identity provider. The service provider and identity provider usually communicate with each other regarding a specific subject. That subject should be identified through a Name-Identifier (NameID) , which should be in some format so that It is easy for the other party to identify it based on the format. Name identifiers are used to provide information regarding a user. | urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress |
| Certificate Alias | Select the Certificate Alias from thedropdown. This is used to validate the signature of SAML2 requests and is used to generate encryption.Basically the service provider’s certificate must be selected here. Note that this can also be the Identity Server tenant's public certificate in a scenario where you are doing atenant specific configuration. | wso2carbon |
| Response Signing Algorithm | Specifies the ‘SignatureMethod’ algorithm to be used in the ‘Signature’ element in POST binding. The default value can be configured in the <IS_HOME>/repository/conf/identity.xml file, in the SSOService element with SAMLDefaultSigningAlgorithmURI tag. If it is not provided the default algorithm is RSASHA 1, at URI http://www.w3.org/2000/09/xmldsig#rsasha1‘’. | http://www.w3.org/2000/09/xmldsig#rsasha1 |
| Response Digest Algorithm | Specifies the ‘DigestMethod’ algorithm to be used in the ‘Signature’ element in POST binding. The default value can be configured in the <IS_HOME>/repository/conf/identity.xml file, in the SSOService element with SAMLDefaultDigestAlgorithmURI tag. If it is not provided the default algorithm is SHA 1, at URI ‘ http://www.w3.org/2000/09/xmldsig#sha1’. | http://www.w3.org/2000/09/xmldsig#sha1 |
| Enable Response Signing | Select Enable Response Signing to sign the SAML2 Responses returned after the authentication process. | Selected |
| Enable SignatureValidation inAuthentication Requests and Logout Requests | Select Enable Signature Validation in Authentication Requests and Logout Requests if you need this functionality configured. This specifies whether the identity provider must validate the signature of the SAML2 authentication request and the SAML2 logout request thatare sent by the service provider. | Unselected |
| Enable Assertion Encryption | Enable Assertion Encryption, if you wish to encrypt the assertion. | Unselected |
| Enable Single Logout | Select Enable Single Logout so that all sessions are terminated once the user signs out from one server. If single logout is enabled, the identity provider sends logout requests to all service providers. Basically, the identity provider acts according to the single logout profile. If the service provider supports a different URL for logout, you can enter a SLO Response URL and SLO Request URL for logging out. These URLs indicate where the request and response should go to. If you do not specify this URL, the identity provider uses the Assertion Consumer Service (ACS) URL. WSO2 Identity Server supports both SAML Back-Channel Logout and SAML Front-Channel Logout methods. By default, when you select Enable Single Logout the Back-Channel Logout is enabled. In order to enable SAML Front-Channel Logout, you can either select Front-Channel Logout (HTTP Redirect Binding) or Front-Channel Logout (HTTP POST Binding). | Selected |
| Enable Attribute Profile | Select Enable Attribute Profile to enable this and add a claim by entering the claim link and clicking the Add Claim button. The Identity Server provides support for a basic attribute profile where the identity provider can include the user’s attributes in the SAML Assertions as part of the attribute statement. Once you select the checkbox to Include Attributes in the Response Always, the identity provider always includes the attribute values related to the selected claims in the SAML attribute statement. | Unselected |
| Enable Audience Restriction | Select Enable Audience Restriction to restrict the audience. You may add audience members using the Audience text box and clicking the Add button. | Unselected |
| Enable Recipient Validation | Select this if you require validation from the recipient of the response. | Unselected |
| Enable IdP Initiated SSO | Select the Enable IdP Initiated SSO checkbox to enable this functionality. When this is enabled, the service provider is not required to send the SAML2 request. | Unselected |
| Enable IdP Initiated SLO | Select the Enable IdP Initiated SLO checkbox to enable this functionality. You must specify the URL. | Unselected |
| Enable Assertion Query Request Profile | Select the Enable Assertion Query Request Profile checkboxto query assertions that are persisted to the database when you loginto the service provider application. For more information, see Querying SAML Assertions. | Unselected |
Now set the configuration as follows:
Issuer: travelocity.com
Assertion Consumer URL: http://localhost:8080/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 Claim configuration and select the userId claim as Subject Claim URI.
Go to Local and Outbound Authentication Configuration section.
Select the Advanced configuration radio button option .
Add the basic authentication as a first step and token2 authentication as a second step. This is done to configure multi-step authentication. What this means is that a user who logs in would first have to enter their credentials that are configured with the Identity Server and then get authenticated using Token2 as the second step. This is an added security measure and a common use of the Token2 authenticator.
Click here to view the field definitions
| Authentication Type | Details |
|---|
| Default | This is the default authenticator sequence for a configured service provider in the Identity Server. This sequence can be modified by updating following section in the <IS_HOME>/repository/conf/identity/application-authentication.xml file.
<Sequences>
<!-- Default Sequence. This is mandatory -->
<Sequence appId="default">
<Step order="1">
<Authenticator name="BasicAuthenticator"/>
</Step>
</Sequence>
</Sequences>
|
| LocalAuthentication | In this case, Identity Server itself authenticate the user. There are three types of local authenticators OOTB in a fresh Identity Server pack. - The basic authenticator is used to authenticate the user using the credentials available in the Identity Server.
- IWA stands for Integrated Windows Authentication and involves automatically authenticating users using their Windows credentials.
- FIDO authenticator is a local authenticator that comes with the WSO2 Identity Server. This will handle FIDO authentication requests related key validation against stored keys, the public key,keyhandler, and the counter, attestation certificate of FIDO registered users.
|
| FederatedAuthentication | In this case, Identity Server trust third-party Identity provider to perform the user authentication. These Identity providers use various protocols to transfer authentication/authorization related messages. Currently, the Identity Server only supports the following federated authenticators OOTB.- SAML2 Web SSO
- OAuth2/OpenID Connect
- WS-Federation (Passive)
- Facebook
- Microsoft (Hotmail, MSN, Live)
- Google
- SMS OTP
- Email OTP
- Twitter
- Yahoo
- IWA Kerberos
- Office365
|
| Advanced Configuration | Advanced configurations enable you to add multiple options or steps in authentication. When multiple authentication steps exist, the user is authenticated based on each and every one of these steps. If only one step is added then the user is only authenticated based on the local and/or federated authenticators added in a single step. However, in the case of local and/or federated authenticators, the authentication happens based on any one of the available authenticators. |
You have now added and configured the service provider.
Testing the sample
- To test the sample, go to the following URL: http://localhost:8080/travelocity.com
Click the link to log in with SAML from WSO2 Identity Server.
Basic authentication page will be visible, use your IS username and password.
Enter the code that is generated with token2 hardware device to authenticate. You are directed to the home page of the travelocity.com app.
