Carbon Authentication Framework

Authentication is a key aspect when it comes to security and identity management. As well as any platform should incorporate  a stronger authentication mechanism, it would be good to have it pluggable and extensible so that custom authentication mechanisms can be developed and plugged-in as required.

WSO2 Carbon platform has an extensible authentication framework which supports custom authenticators to be plugged-in as required. 

Carbon middleware platform has two main separations as front-end and back-end. Carbon Authentication framework has two extension points to plugin front-end and back-end authenticators.

BE Authentication

Following is the architecture diagram of extension point for back end authenticators.

                                               Image 1: Extension for Carbon back end authentication

• To implement a BE authenticator, you need to implement CarbonServerAuthenticator interface.
• Implementation needs to be registered as an OSGi service.
• Default carbon BE authenticator implementation is AuthenticationAdmin.
• Authenticator checks whether the httpsession of the incoming request is authenticated.
• It is the login() method of an AuthenticationAdmin service, which sets whether a particular session is authenticated or not by validating the credentials provided at login.
• If we need to customize login() method then our custom authenticator should also be an AdminService exposing the login() method.
• Hence the login() request is bypassed at the AuthenticationHandler (which is hit at the invocation of any AdminService operation) and sent directly to the corresponding AdminService.
• AuthenticationHandler picks up the correct authenticator from the AuthenticatorServerRegistry based on the priority and whether a particular authenticator can handle the current request.

FE Authentication

If you want to customize the authentication logic from front-end itself, you can write a corresponding FE authenticator as well.

It is the FE custom authenticator which is associated with the BE custom authenticator that calls the login() method of the relevant BE custom authenticator.

Following is the architecture diagram extension point for front end authenticators.

Image 2: Extension for Carbon front end authentication

• You need to implement CarbonUIAuthenticator interface for a custom FE Authenticator.
• DefaultCarbonAuthenticator is the default implementation of FE authenticator.
• It is the CarbonSecuredHttpContext that looks for FE authenticators in AuthenticatorRegistry and picks up the correct authenticator.

Existing Authenticators

In addition to the default authenticators, there are several custom authenticator implementations in Carbon code base which are used at different occasions. They are:

1. saml2-sso-authenticator
2. sso-authenticator
3. token authenticator
4. webseal-authenticator

Configuring Custom Authenticators

As I mentioned earlier, one aspect on which the correct authenticator is picked, is the priority. Either we can set the priotity in code level or in configuration. If you later need to change the priority of your custom authenticator in [carbon_home]/reository/conf/advanced/authenticator.xml (in Carbon 3.2.0 or higher) or [carbon_home]/repository/conf/carbon.xml (in earlier versions).

Sample configuration is given below:

        5
    

Sample

I have attached here a sample back-end authenticator written for Carbon 3.1.0. The implementation will be same for 3.2.0 as well.

It customizes the login method for creating a role per each user at the user log in.

Drop the bundle found in the target (org.wso2.carbon.sample.authenticator) into [carbon_home]/repository/components/dropins folder and start the server. 

Try to log into the management console, you will notice that custom lines are printed on the backend server log which indicates that our custom authenticator has been picked.

You will need to write a FE custom authenticator also in the same way in order to fully customize the authentication logic.