Writing a custom local authenticator for WSO2 IS 5.11.0

The default authenticator in the WSO2 Identity Server is the Basic authenticator. It is a local authenticator that authenticates the end users using a connected user store and the provided user name and password.

WSO2 Identity Server comes with extensibility which allows you to change the authentication logic which the local users are validated. You only have to write a local authenticator with the customized authentication logic and deploy it in the WSO2 Identity Server.

This guide discusses the three main steps required when introducing custom local authenticator to the WSO2 Identity Server and how you can try out the custom authenticator. Following are the main topics that I’m going to cover.

1. Implement the custom local authenticator
2. Deploy the authenticator in the WSO2 IS
3. Configure an application with the custom authenticator
4. Trying out the custom authenticator

Sample Scenario

Let’s say we need to login into an application using our telephone number(http://wso2.org/claims/telephone) instead of the username. Therefore if the user enters his/her mobile number as the username, the authentication logic should validate the credentials of the user identified by the given telephone number.

Customization and configuration details are given relevant to the WSO2 Identity Server 5.11.0

You can find the complete source code of this sample custom local authenticator here[1]. I have added inline comments for more details.

Implement the custom local authenticator

1. Create a maven project for the custom authenticator. You can refer to the pom.xml file used to implement the sample local authenticator that is discussed in this guide.
2. The authenticator should be written as an OSGi service and deployed in the WSO2 Identity Server. Therefore we need to have a service component class in our sample authenticator to register it as a local authenticator.
3. The custom local authenticator should be written by extending the AbstractApplicationAuthenticator class and implementing the LocalApplicationAuthenticator class.

Methods that needed to be implemented,

• getFriendlyName(): returns the name you want to display for your custom authenticator.
  ** Our sample custom local authenticator is named as sample-local-authenticator
• getname(): get the name of the authenticator.
• canHandle(): checks whether the authentication request is valid, according to the custom authenticator’s requirements. The user will be authenticated if the method returns ‘true’. This method also checks whether the authentication or logout request can be handled by the authenticator.
  ** For example, you can check if the username and password is ‘not null’ in the canHandle method. if that succeeds, the authentication flow will continue (to have the user authenticated).
• processAuthenticationResponse(): Implementation of custom authentication logic happens inside this method.
  ** In our example, we use the following API where the user claim used as the username is passed along with the value and authenticate the user. Since we are using the telephone number as the login identifier, the prefferedUsernameClaim is http://wso2.org/claims/telephone.

AuthenticationResult authenticateWithID(String preferredUserNameClaim, String preferredUserNameValue, Object credential, String profileName) throws UserStoreException;

• initiateAuthenticationrequest(): redirects the user to the login page in order to authenticate
  ** In our sample, the user is redirected to the default WSO2 IS login
• getContextIdentifier(): gets the Context identifier sent with the request. This identifier is used to retrieve the state of the authentication/logout flow.

Now you have successfully implemented the custom authentication logic.

4. To compile the service, go to the root of your project where the pom.xml file is located and run the following command

mvn clean install

Deploy the custom local authenticator in WSO2 IS

1. Once the project is successfully built, you can find the compiled jar file insider <sample-local-authenticator>/target.
2. Copy the jar file; in our sample org.wso2.carbon.auth.local.sample-1.0.0.jar file to the <IS_HOME>/repository/components/dropins.

Configure an application with the custom authenticator

1. Start WSO2 Identity Server
2. Sign in to the Management Console
3. Create a service provider for the application. (We will use the OIDC sample application pickup-dispatch and it is already deployed in the tomcat server locally.)
4. In the service provider configuration, under the Inbound Authentication Configuration section, click OAuth/OpenID Connect Configuration > Configure. OAuth/OpenID Connect Configuration option. (Refer to the official documentation for more details)
5. Provide the callback URL and register it as an OAuth2 client app. For the pickup-dispatch application, the callback URL is http://localhost.com:8080/pickup-dispatch/oauth2client
6. Under Local & Outbound Authentication Configuration, select Local authentication radio button and sample authenticator that we deployed from the drop-down menu.

configuring the custom local authenticator

Try out the custom authenticator

1. Create a user called with the username alex.
2. Since we are trying to login with the user’s mobile number, provide a valid telephone number in the default user profile
3. Access the sample application. (http://localhost:8080/pickup-dispatch/ for the application that I’m using)
4. Click on the Login button
5. Provide the configured telephone number as the username and the corresponding password of the user
6. You will be successfully authenticated to the application.

Trying out the custom local authenticator

References

[1] https://github.com/pamodaaw/sample-local-authenticator

Thanks for reading.