In this post let see how we can configure WSO2 Identity Server 5.7.0 with two step Authentication. Following are the two steps we are going to configure :
1. First step is configured with Local Basic Authentication, where the user is authenticated with the credentials available in the Identity Server.
2. Second step is configured as Federated Multi-Factor Authentication with Email OTP and SMS OTP.
Configuring Email OTP with WSO2 IS as the email OTP provider
Configure the MailTransportSender
Configure the MailTransportSender with the relevant mail address that is to be used as the sender's mail address from which the Email OTP will be sent to the user's email address configured in the user's profile.
By default the WSO2 MailTransportSender will be commented out in the configuration. Navigate to the <IS_HOME>/repository/conf/axis2/axis2.xml file and uncomment the following configuration.
Replace the parameters in the curly braces with the relevant values.
In the same axis2.xml file comment the out the following property to avoid syntax errors.
If you are using Gmail Account as the Sender's Email, you have to on "Allow less secure apps" in your Gmail account. Navigate to Google Account -> Security -> Less secure app access and Turn it On.
Configure the Email OTP Template
The Email Templates used for various purposes (Password Reset, User Registration, Account Locked... etc) are defined in the <IS_HOME>/repository/conf/email/email-admin-config.xml file. By default the Email OTP template is not defined in this file. Add the Email OTP template to the end of the
<IS_HOME>/repository/conf/email/email-admin-config.xml file.
Make sure to include the {{OTPCode}} in the Email template as it functions as a placeholder value and will be replaced by the actual OTP Code when the mail is generated. Make sure to configure the double curly braces for the place holder value else the value won't be replaced with the actual OTP.
Enable the Authentication Policy to check for the OTP
Configure the following properties in the
<IS_HOME>/repository/conf/identity/identity-mgt.properties file to true.
Configure the Email OTP Authenticator
Application Authenticator configurations are available in the <IS_HOME>/repository/conf/identity/application-authentication.xml file.
By default the EmailOTP authenticator is enabled true and configured to point to Gmail as the Email OTP provider. Comment out the existing EmailOTP AuthenticatorConfig
<AuthenticatorConfig name="EmailOTP" enabled="true">
Add the following configuration to the
<IS_HOME>/repository/conf/identity/application-authentication.xml file.
Configure the SMTP Server
Since we are using WSO2 as the Email OTP provider (not Gmail as Email OTP provider) to sent out the Email we need to configure the SMTP server with the credentials.
We will connect to the Gmail SMTP server to deliver the mail.
If we use Gmail as the Email OTP provider, instead of directly connecting to the Gmail SMTP server we would use some Google APIs to configure the Email OTP with Gmail.
Modify the <adapterConfig type="email"> found in the <IS_HOME>/repository/conf/output-event-adapters.xml file as the below.
Replace the SENDER'S_EMAIL_ID, USERNAME and PASSWORD parameters with the relevant values.
Now that we have successfully made all the configuration changes to the files to enable the Email OTP. Still we need to do a few more changes to the Claims, Service Provider and Identity Provider from the UI. We will continue to do that after doing the changes required to enable SMS OTP as well. Please skip the SMS OTP configuration section if you don't have a requirement.
Configuring SMS OTP with Nexmo
WSO2 Identity Server supports several SMS OTP service providers like Nexmo, Clickatell, Plivo, Bulksms and Twilio. In this blog i will be using Nexmo service provider.
Generating Nexmo API key and secret
In order to send SMS with Nexmo we need to register and generate an API key and secret.
You can register with Nexmo free of charge.
Go to https://dashboard.nexmo.com/sign-up and sign up.
Once you successfully register, the API key and secret are displayed. Copy and save them as you need them for the next step.
Construct the SMS URL by replacing the API_KEY and API_SECRETin the below URL.
HTTP Method - POST (Nexmo used POST HTTP method)
HTTP Response Code - 200 (Nexmo service provider sends 200 response code if the API is successfully called)
Nexmo API and Bulksms API sends 200 as the code, while Clickatell and Plivo send 202. If this value is unknown, leave it blank and the connector checks if the response is 200, 201 or 202.
The SMS URL, HTTP Method and HTTP Response Code are needed in the future step when we configure the Identity Provider with SMS OTP as the Federated Authenticator.
Add Nexmo Public Certificate to WSO2 Client Trust Store
Download the certificate of the SMS provider by going to the SMS providers website on your browser, and clicking the HTTPS trust icon on the address bar.
For example, navigate to https://www.nexmo.com, and click the padlock next to the URL on Chrome.
Navigate to the <IS_HOME>/repository/resources/security directory via the terminal and import the downloaded certificate into the WSO2 IS client keystore.
The default client-truststore.jks password is wso2carbon.
Now that we have done all the relevant configuration changes to the files. Let's start the WSO2 Identity Server and add the Service Provider, Identity Providers, Claim Configurations and User Profile information.
Configure the Identity Provider for Email OTP
Click Add under Main > Identity > Identity Providers.
Configure the Identity Provider Name as EmailOTP
Expand the EmailOTPAuthenticator Configuration under Federated Authenticators.
Select the Enable and Default check boxes.
If you are using Gmail or Sendgrid as the Email OTP provider, provide the values for Email API and Email fields as well.
Click Register.
Now we have successfully added the Identity Provider for Email OTP.
Configure the Identity Provider for SMS OTP
Click Add under Identity Providers.
Configure the Identity Provider Name as SMSOTP.
Go to the SMS OTP Configuration under Federated Authenticators.
Select both check-boxes to Enable SMSOTP Authenticator and to make it the Default.
Configure the SMS URL, HTTP Method and HTTP Response Code we constructed earlier.
Click Register.
Now we have successfully added the Identity Provider for SMS OTP.
Configure the user claims
Click Add under Main > Identity > Claims.
Click Add Local Claim.
Add the following:
Display Name:Â DisableEmailOTP
Description: DisableEmailOTP
Mapped Attribute (s): title
Supported by Default:Â checked
Click Add.Â
Similarly add a local claim DisableSMSOTP.
Add the following:
Display Name:Â DisableSMSOTP
Description: DisableSMSOTP
Mapped Attribute (s): stateOrProvinceName
Supported by Default:Â checked
Click Add
Configure the user profile
Configure the user profile with the Email address to which the Email OTP need to be sent and the mobile number to which the SMS OTP need to be sent.
Configure the Service Provider
Configure the service provider "travelocity.com" with inbound SAML protocol.
Navigate to Local and Outbound Authentication -> Advanced Configuration and do the following:
Configure step-01 with "Basic Authentication"
Configure step-02 with "EmailOTP" and "SMSOTP" Federated Authenticators.
This concludes the setup. Try out the flow by accessing the "travelocity.com" service provider URL.
Thank you for reading. Please feel free to drop your comments below.