Custom Federated Authenticator for WSO2 Identity Server

Through this blog, I’m going to guide you on how to write a custom federated authenticator for the WSO2 Identity Server to authenticate a user with an external system. So the external system can be any Identity provider such as Facebook, Twitter, Google and Yahoo. In this blog, I’m using another Identity Server as a federated authenticator which is called as a partner identity server throughout this blog. It is possible to use the extension points available in the WSO2 Identity Server to create custom federated authenticators.

Let’s write the custom federated authenticator

1. First, create a maven project for the custom federated authenticator. Refer to the pom.xml file for the sample from here.
2. Refer to the service component class in our sample authenticator to register it as a federated authenticator and to deploy it as an OSGi service in the WSO2 Identity Server.
3. The custom federated authenticator should be written by extending the AbstractApplicationAuthenticator class and implementing the FederatedApplicationAuthenticator class.
4. You can find a custom federated authenticator sample from here for your reference.

The important methods in the AbstractApplicationAuthenticator class and the FederatedApplicationAuthenticator interface are listed as follows.

• public String getName()

Return the name of the authenticator

• public String getFriendlyName()

Returns the display name for the custom federated authenticator.
In this sample, we are using custom-federated-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 authentication request and the response should be the same.

• public boolean canHandle(HttpServletRequest request) -

Specifies whether this authenticator can handle the authentication response.

• protected void initiateAuthenticationRequest(HttpServletRequest request,HttpServletResponse response, AuthenticationContext context)

Redirects the user to the login page in order to authenticate and in this sample, the user is redirected to the login page of the application which is configured in the partner identity server which acts as the external service.

• protected void processAuthenticationResponse(HttpServletRequest request,HttpServletResponse response, AuthenticationContext context)

Redirects the user to the login page in order to authenticate and in this sample, the user is redirected to the login page of the application which is configured in the partner identity server which acts as the external service.

Deploy the custom federated authenticator in WSO2 IS

1. Navigate to the root of your project and run the “mvn clean install” command to compile the service.
2. Once the project is successfully built, you can find the compiled jar file insider <custom-federated-authenticator>/target.
3. Copy the jar file; in our sample org.wso2.carbon.identity.custom.federated.authenticator-1.0.0.jar file to the <IS_HOME>/repository/components/dropins.

Let’s prepare the partner identity server

In this sample, the partner identity provider acts as the external Identity Provider.

So, for that I will be using another WSO2 IS which is running on the same machine in a different port. You can configure it by adding the following config to the deployment.toml file.

[server]
offset=1

After starting that partner identity server, it will run on localhost:9444.

1. Access the Management console of the partner identity server.
2. Then go to the Service Providers under the main tab. Then add Service Provider Name and register it. Let’s use the playground app. Refer this to configure the playground app.
3. Then List the Service Providers and edit the service provider by navigation to the OAuth/OpenID Configuration under Inbound Authentication Configuration and add “https://localhost:9443/commonauth as the callback URL.
4. Create a user Alex in the partner identity server.

Let’s configure Federated Authenticator

To configure the federated authenticator, click add button under Identity Providers and add an IDP name as “Partner-Identity-Server” and register the new IDP.

Click on the Federated Authenticators and expand the custom-federated-authenticator configurations and configure it as follows.

Here, the Client Id and Client Secret are the values of external service provider from the Partner-Identity-Server.

• Enable / Default — You can enable and set to default
• Authorization Endpoint URL — https://localhost:9444/oauth2/authorize/
• Token Endpoint URL — https://localhost:9444/oauth2/token/
• Client Id — The value generated by the service provider of the pater IS
• Client Secret — The value generated by the service provider of the partner IS

Configure an application with the custom federated authenticator

1. Start the server and log in to the WSO2 IS Management Console.

2. Then go to the Service Providers under the main tab. Then add Service Provider name and register it. Let’s use the playground app and refer to this to configure the playground app.

3. Then List the Service Providers and edit the service provider as follows by navigation to the OAuth/OpenID Configuration under Inbound Authentication Configuration as explained above.

4. Then click Configure and add http://localhost:8080/playground2/oauth2client as the call back URL. Click Update.

5. Navigate to Local & Outbound Authentication Configuration as follows and you can find Authentication Type. Select Federated Authentication and select the configured federated authenticator and update to save the changed configurations.

Let’s try out our scenario

1. Access the playground app by using http://localhost:8080/playground2.
2. Then it will redirect to the login page of the application which is configured in the partner identity server which acts as the external service.
3. Give Alex’s username and password (The user was created, in the partner identity server).
4. Then the federated authentication can be experienced since Alex is authenticated from the partner Identity Server.

Similar to the above-explained sample, now you can write a federated authenticator to authenticate the users using an external system.

Congratulations!!! Now you know how to write a custom federated authenticator for the WSO2 identity Server.