Identity Servlet Driven Inbound Authentication in WSO2 IS
Each type of authentication protocol supported by WSO2 Identity Server is handled by a protocol specific inbound authenticator and Identity Server has endpoints for each type of request. Examples- saml endpoint: /samlsso , Oauth endpoint: /oauth, etc.
All authentication requests are received by the servlets in the relevant endpoint hosted. As an example, SAMLSSOProvider servlet receives and handles the SAML requests. Like that, for every protocol, there is a specific servlet to receive and handle the requests.
The Ordinary Flow of Authentication Request Handling
Each servlet will receive the relevant authentication requests and the request processor validates the request and then builds a common object model understood by the authentication framework and handovers the request to it. After framework login or logout, the response builder accepts the common object model from the authentication framework and build a response out of it.
But at each servlet, few common things repeat. Some major things are;
- Building a common framework-understood object model from the authentication request.
- Sending requests to the framework for login/ logout.
- Building the Http response after framework login or logout.
To overcome these unnecessary implementations, WSO2 Identity Server has been introduced a new approach to handle each type of authentication request.
In this approach, there is only one servlet to handle requests from the various authentication protocol types. That is Identity Servlet : /identity. All the endpoints replace the identity endpoint. and it will handle each type of authentication request.
Identity Servlet
when a certain request reaches the identity servlet, it will engage the appropriate inbound authenticator based on its logic. The inbound authenticator will be responsible for handling all the protocol-specific tasks. The entire request handling process will be handled by identity servlet but the servlet is protocol-unware.
The diagram below illustrates the architecture of the Identity Servlet driven inbound authenticator.
An explanation of the major components of the inbound authenticator is as follows:
HTTPIdentityRequestFactory
Takes in a servlet request from the /identity servlet and provides a builder to an IdentityRequest instance (or an instance of a subclass of IdentityRequest) as the output. Main functionalities carried by the canHandle() and create() methods.
canhandle(): Check whether or not a certain servlet request can be handled by this particular class.
create(): This should create the instance of IdentityRequestBuilder with the needed properties assigned.
Here we convert the authentication request to a common framework-understood format(Identity Request object) , delegate the object creation to an IdentityRequestBuilder instead of creating the objects directly. This builder is responsible for building a concrete instance of IdentityRequest for the framework when needed.
As the authentication request is a complex object with a large number of optional parameters, converting the request to another object model is a complex construction. Therefore Builder design pattern is used to construct the Identity Request object step by step and the final step will return the object. It also does separate the construction of the complex object from its representation so that the same construction process can create different representations.
IdentityProcessor
The main process of inbound authentication request holds this class. IdentityProcessor is responsible for handling a fresh IdentityRequest coming from the /identity servlet and a processed response from the authentication framework. Its main functionality, which is carried out in the canHandle() and process() method.
canHandle(): Just as in the RequestFactory, here we should decide whether the given IdentityReuest can be processed in this processor.
process(): The business logic is carried by this method. All the process methods should return an IdentityResponse.IdenstityResponse builder. This method can be summarised as follows:
In the in-flow (a fresh IdentityRequest coming from the /identity servlet):
- The business logic is carried out (for example, extracting and/or validating custom parameters, cookies, etc set in the request).
- A MessageContext is created so that any needed properties can be preserved for the outflow.
- Finally, the request is passed to the framework through the in-built method buildResponseForFrameworkLogin() with the created message context as a parameter. The response from the framework will then be sent again to the /identity framework.
In the out-flow (returning a processed response from the authentication framework, which was sent to the /identity servlet as described in the above case)
- Derive an instance of an AuthenticationResult object (which can be used to check if the authentication step specified in the corresponding SP is successful or not) through the processResponseFromFrameworkLogin() in-built framework method. If desired, separate IdentityResponse objects can be created for auth success and failure scenarios.
- Respond to the calling party through custom IdentityResponse and HTTP response implementations, as required.
HTTPIdentityResponseFactory
This class does the opposite of the HTTPIdentityRequestFactory; it builds a HTTP response instance based on the common IdentityResponse format used by the authentication framework. Here, the HTTP response is specific to the protocol in use (for example, a SAML HTTP response will contain headers and fields as per the SAML spec).
The Authentication Request Handling Process with Identity Servlet
- Parse the incoming authentication request from the server and see if it could be handled.
- convert that request into a format understood by the Identity Server’s authentication framework
- Pass the converted request (called an IdentityRequest) to the authentication framework
- When the framework responds with an IdentityResponse, convert it to a corresponding HTTP response
- Pass along the final HTTP response to the calling party
The diagram below illustrates the overall flow, starting from the authentication request issued from the external Service Provider:
References:
