Identity Gateway
The WSO2 Identity Server 6.0.0 takes the identity management into a new direction. The identity gateway we are introducing in IS 6.0.0 powers to enable more extensions and lightweight gateway. The objective of this part is to introduce high-level concepts associated with the identity gateway.
WSO2 released a new carbon kernell as C5 and IS 6.0.0 based on C5. This identity gateway contains 3 major component as Gateway API, Gateway and Gateway Resource.
Gateway API
Gateway API component provides the generic API for gateway implementation and some abstract implementation itself. Mainly it will be based to implement request/response service model. API has key classes to implement the model.
1. GatewayRequestFactory
2. GatewayRequest/GatewayRequestBuilder
3. GatewayProcessor
4. GatewayResponseFactory
5. GatewayResponse/GatewayResponseBuilder
6. GatewayMessageContext
GatewayProcessor is the place that we start process the request and based on the requirement we can extends the GatewayProcessor. In process method only accept the GatewayReuqest type. So if we are going to handle a custom request type with additional attributes rather than what we have provided in GatewayRequest API, we can extends that. To build that new custom request we have to implement the GatwayRequestFactory as well. GatewayRequestFactory get the MSF4J Request and build the GatewayRequest.
As same as to the request type, we have to do to the response as well. We can extend the GatewayResponse and return from the custom processor and GatewayResponseBuilder can build the MSF4J response using GatewayResponse object data.
All the factory level APIs are coupled with the MSF4J transport that is allowing to build request from the transport level to gateway and build response from gateway level to transport. But processor API is not coupled with any transport and we can call that API to do the task within JVM by consuming the Processors in OSGi services.
It is always return the request builders from the factory APIs instead of returning concrete immutable object. Because if we get the builder in any level, we can set more values to that and build the actual immutable object. As example, factory method return GatewayRequestBuilder and after we get that in resource layer, still we can set values and finally we can build the immutable GatewayRequest object.
GatewayMessageContext is the context class that we can used to share the context detail through the gateway based on the scope.
Gateway
Gateway component provides the concrete gateway implementation based on Gateway API. This is covered complete identity gateway run time except the resource endpoints.
This is the high level architecture diagram for the basic flows.
As in this architecture, we expect to build a request based on the protocol by using the GatewayRequestFactory or extended type. There should be a unique GatewayRequest subtype to each protocol because of within the gateway, it would be easy to handle the protocol specific things easily.
We have two types of requests in the gateway,
- ClientAuthenticationRequest - This type of request represent the initial client request only.
- CallbackAuthenticationRequest - Except the initial client request, all the other request type should be subtype of this.
AuthenticationProcessor is control the main handler flow based on the request and context
informations.
We have implemented AuthenticationContext as the main context object to the runtime that can be used to keep the runtime information for the request. This context will initialize for the initial client request by the AuthenticationProcessor and pass through all the handler APIs. If the request is callback one, then this context will be loaded from the cache by the AuthetnicationProcessor.
Validation
We have a super type called AbstractRequestValidator to implement each protocol validators and AthenticationProcessor will trigger this handler if the request is from client request only. If the request is callback one, then we skip this validation handler execution.
*** We have to identify the service provider which is trying to access this request and in order to do that, we have to get the unique value of the client protocol and set it to the context. Mainly that can be done by the protocol validator.
Authentication
This handler is executed by the processor after the client validation or the request come as a callback to the gateway runtime.
First this handler will build the sequence to start the authentication flow.
- Seqeunce
We have introduce a Sequence interface to implement a custom sequence and make the authentication flow more dynamic rather than only coupled with the static configurations. DefaultSequence is the default one that is rely on the service provider configuration.
After build the sequence, AuthenticationStepHandler handle the flow. When can have multiple identity providers in each steps and there can be different execution strategy to execute the authenticators. So based on the execution strategy, step handler get the relevant execution handle and handover the authentication task to that.
There are multiple execution strategy that we have already identified out of the box.
- SingleOptionExcutionHandler
- MultiOptionExcutionHandler
- ParellalExecutionHandler
- FailoverExecutionHandler
Each execution handler responsible to handle the flow based on strategy. Developer can write their own handler to handle this in custom way.
Ex: In multioption execution, we have to redirect to the landing page with all the option details when the request or context don’t have the identity provider details. Call the authenticators and handle the retry also should within that specific handler.
Finally, AuthenticationStepHandler update the session context based on the result of the authentication if there are no more steps to be authenticated
Response Handling.
If the request could reach to the last steps without return result back before that, then we must give the response back to the client using client expected protocol. GatewayResponseHandler type can be extended to the each protocol.
Gatway Resource
This component handle the resource endpoints that is provide the service as the gateway runtime.
/gateway POST and GET support.
All the protocol request come to this endpoint. After get the request, this transform MSF4J request to the GatewayRequest by using protocol specific factories and pass the new GatewayRequst to the AthenticationProcessor.
As a result, processor return the GatwayResponse and, it transform to a MSF4J response by using its specific GatewayResponseFactory.
This resource bundle consume all the Processors and Factories to handle the transport level request/response and start the process.
Following the sequence diagrams that is explain the flow of gateway runtime.
