Write a Custom Local Authenticator¶

A local authenticator in WSO2 identity server authenticates users, who are stored in the local database, using a defined authentication logic.

The default local authenticator in WSO2 identity server is the Username & Password authenticator. It authenticates end users stored in a connected user store using the provided username and password.

WSO2 identity server supports extensibility in local authentication so that you can implement a different authentication logic by writing a custom local authenticator. You can implement custom authentication logic tailored to your requirement, as follows:

Authenticating users only if they belong to a particular role.
Authenticating based on any claim, such as the user's telephone number or employee registration number.
Calling another API to authenticate the user.

Scenario¶

You have a sample app to which you want users to log in with their telephone numbers instead of usernames. Once a user enters a telephone number, your authentication logic should identify the user and validate the user's credentials.

The following guide shows you how to write a custom local authenticator to implement this authentication logic.

Write the local authenticator¶

To write the local authenticator:

Create a maven project for the custom local authenticator. Refer the following files:
- The pom.xml file used for the sample custom local authenticator.
- The service component class file to deploy in WSO2 Identity Server and register it as a local authenticator.
Write the custom local authenticator by extending the AbstractApplicationAuthenticator class and implementing the LocalApplicationAuthenticator class.

Info

See the sample custom local authenticator for your reference.

Methods in AbstractApplicationAuthenticator class and LocalApplicationAuthenticator interface

Method	Description
public String getName()	Return the name of the authenticator. In the sample project, we have used this method to return the name SampleLocalAuthenticator.
public String getFriendlyName()	Returns the display name for the custom local authenticator. In the sample project, we have returned the name sample-local-authenticator.
public String getContextIdentifier(HttpServletRequest request)	Returns a unique identifier that will map the authentication request and the response. The value returned by the invocation of the authentication request and the response should be the same.
public boolean canHandle(HttpServletRequest request)	This method 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. In our sample project, we used this method to check if the username and password are 'not null' in the authentication request. If that succeeds, the authentication flow will continue.
protected void initiateAuthenticationRequest(HttpServletRequest request,HttpServletResponse response, AuthenticationContext context)	This method is used to redirect the user to the login page to authenticate. You can redirect the user to a custom login URL using this method or you can use the default WSO2 Identity Server login page.
protected void processAuthenticationResponse(HttpServletRequest request,HttpServletResponse response, AuthenticationContext context)	Implementation of custom authentication logic happens inside this method. For example, you can call any API that can do authentication and authenticate the user or you can authenticate the user against the underlying user store. Then you can also do any other custom logic after authenticating the user such as, you can check if a user belongs to a particular role and allowing authentication accordingly. In the sample project, we used this method to authenticate the user with the user's telephone number and password, and make the authentication successful.
public AuthenticatorFlowStatus process(HttpServletRequest request, HttpServletResponse response, AuthenticationContext context)	This method is used to process or carry out the user authentication process. It calls the processAuthenticationResponse() method in the custom authenticator class to execute the custom authentication logic. In the sample project, we call the super.process(), so that the super class process method will handle the authentication process, instead of implementing our own process method.
protected boolean retryAuthenticationEnabled(AuthenticationContext context)	This method returns a boolean value. If the authentication fails due to some issue like invalid credentials, this method will be called to know whether to retry the authentication flow. If this method returns 'true', the authentication flow will be retried. If returns 'false', the flow is stopped with an exception thrown. You need to override this method if you are calling the super.process() method. But if you are writing your own process() method, you can handle all the retrying logic accordingly within the method.

Deploy the authenticator¶

To deploy the custom local authenticator:

Open a terminal, navigate to the root of your project, and compile the service by running the following command:
```
mvn clean install
```
Copy the generated org.wso2.carbon.identity.sample.local.authenticator-1.0.0.jar file from <Sample-local-authenticator>/target folder to the <IS_HOME>/repository/components/dropins folder.
Add the following config to the deployment.toml file in the <IS_HOME>/repository/conf folder. The name should be the authenticator name returned by the getName() method in the authenticator class.
```
[authentication.authenticator.sample_authenticator]
name = "SampleLocalAuthenticator"
enable = true
```

Configure the Identity Server¶

This section guides you on how to configure the identity server to use the custom local authenticator.

Prerequisites¶

You need to set up the sample application.

Configure the application with the custom local authenticator¶

To configure the custom local authenticator for the application:

On the WSO2 Identity Server console, go to Applications.
Select your application, go to the Login Flow tab and add the custom local authenticator from your preferred editor:
Classic EditorVisual Editor
To add custom local authenticator using the Classic Editor:
1. If you haven't already defined a sign-in flow, click Start with Default configuration to get started.
2. Remove the existing Username & Password authenticator and click Add Authentication on the step, select your custom local authenticator, and click Add.
To add custom local authenticator using the Visual Editor:
1. Switch to the Visual Editor tab, by default the Username & Password login flow will be added onto the Visual Editor's workspace.
2. Remove the existing Username & Password authenticator and click on + Add Sign In Option to add a new authenticator to the same step and select your custom local authenticator.
Click Update to save your changes.

Add a new user¶

To add a new user:

On the WSO2 Identity Server console, go to User Management > Users.
Click Add User and provide the required details.
Add a telephone number to the Mobile field and click Next.
Add the user to a group, if necessary, and click Next.
Assign the user a role, if necessary, and click Next.
Review the summary and click Finish.

Try it out¶

Access the application URL.
Click Login. You will be redirected to the WSO2 Identity Server login page.
Enter the user's telephone number as the identifier and enter the user's password, and click Continue.

The user will be successfully authenticated.

Contributing your connectors¶

You are welcome to share and host your connectors in our connector store. As an organization that believes in the open source paradigm, we always encourage our community to make contributions so that our community around WSO2 Identity server can benefit from using an open source product. Contributions can be made by following the procedure below.

Create an issue in the product-is git repository.
Provide a basic description of the purpose and functionality of your connector. Include the following information in the git issue.
Downloadable connector artifact (ex: JAR files).
Documentation on setup and testing instructions for the connector.
Source code repository of the connector.
Make sure your source code follows WSO2 coding standards and secure development guidelines.
Our team will perform necessary functionality, security, and usability testing on the connector and provide suggestions for improvements.
If your code and the functionality are deemed to comply with the standards of WSO2, you will be able to get the connector hosted on our connector store and contribute the source code to WSO2.
You will be required to sign the Contributor License Agreement once the connector is accepted.

You can also contact us through our Discord channel if you need more information.