Normally, when creating an API the logic will be carried out by another backend or endpoint. It is highly likely that this other endpoint has its own authentication system. In order to resolve this, API Manager provides a configuration mechanism for endpoint authentication. However, it only allows the configuration of two security algorithms: Basic and Digest.
Extensibility
As previously mentioned, one of the most important characteristics of API Manager is its capacity to increase and customize its already wide variety of features.
It offers two customization options: custom handlers and custom mediation.
- Custom Handler: When an API is created, a configuration file is generated in which all API-associated handlers are stored. This set of handlers will be executed in the order indicated by the folder each time API is invoked. With custom handlers we can create a logic operation that will be executed in each generated API invocation.
- Custom Mediation (Mediation Flow): When calling an API, a set execution flow is followed. It works in a similar way to how API does on ESB. This means that it is composed of an input, output and error sequence. Through a custom mediation, we can modify this flow by creating specific input, output or error sequences.
Normally, WSO2 recommends using custom handlers instead of custom mediation. However, in this case it recommends the opposite. This is due to the fact that custom handlers facilitate a more generic and global customization. And we may only want to apply this new security algorithm to a single API. Although this can also be carried out with custom handlers, customization is easier and reusable with custom mediations.
-For more information about this see also: API MANAGER TUTORIAL: EXTENSIBILITY –
Example of Custom Mediation Flow
For this example, we will create an API call to an endpoint that requires security. This authentication will, as usual, go to the Authentication header petition. Here, an HMAC-MD5 in Base64 code password will appear.
Custom class
The first step is to create a library that allows us to generate the Authorization header. This library will be made up of an AbstractMediator extension class and will comprise two input parameters that will enable the proper creation of the header. Since this header must appear in the request to the endpoint, the library needs to be included in the input sequence via a class mediator.
public class CreateHeaderHMACMD5 extends AbstractMediator {
private String consumerSecret;
private String data;
@Override
public boolean mediate(final MessageContext context) {
try {
String sHMACMD5Encode = sStringToHMACMD5(data, consumerSecret);
String sBasicEncode = Base64.getEncoder().encodeToString(sHMACMD5Encode.getBytes());
org.apache.axis2.context.MessageContext mc = ((org.apache.synapse.core.axis2.Axis2MessageContext) context).getAxis2MessageContext();
Map<String, String> transportHeaders = (Map<String, String>) mc.getProperty(org.apache.axis2.context.MessageContext.TRANSPORT_HEADERS);
transportHeaders.put("Authorization", "Basic " + sBasicEncode);
} catch (Exception e) {
log.error(e.getMessage(), e);
}
return true;
}
//...
}
In order to use this library, we have to pack it as a JAR and place it in the folder.
{APIM_HOME}/repository/components/lib.
Later, we have to restart the server for it to be correctly detected.
Custom Mediation
The above-mentioned input sequence will be our custom mediation. It should be created with the same format that we would use to create another sequence.
<sequence xmlns="http://ws.apache.org/ns/synapse" name="authenticationHMACMD5:v1--In"> <class name="com.chakray.apim.mediator.CreateHeaderHMACMD5"> <property name="consumerSecret" value="<consumerSecretValue>"/> <property name="data" value="<dataValue>"/> </class> </sequence>
For the consumerSecret and data variables, the specific values that allow us to correctly create the password must be indicated.
-HOW TO CREATE A CUSTOM MEDIATOR AND ASSIGN IT A TAG IN WSO2-
API
Lastly, we will create our own API, which will call the backend. This API will also associate to with the necessary Authentication header through custom mediation.
In order to do so we will create an API via the publisher. In the second step, Implementation, we indicate that we want to modify the default mediation. And we include the previously created sequence as an input sequence,
Afterwards, we continue with the standard API generation, in the Publisher and Store tabs.
Test
We will make an API call to our sample API named ‘secureApi’ and to its ‘authorize’ method. As it is an API Manager secured API, we will need the API Manager bearer token to call it.
curl -k -X POST "https://localhost:8243/secureApi/v1/authorize" -H "Content-Type: application/json" -H "Authorization: Bearer e90f5c06-411b-3fcc-8e09-47b2bed105aa" -d "{ \"payload\": \"string\"}"
For this example, and in order to visualize the API Manager call, we have used a wiremock backend. In said call we will be able to see the status of the Authorization header with the HMAC-MD in base64 password.
127.0.0.1 - POST /authorize
Authorization: [Basic Y29uc3VtZXJLZXlWYWx1ZTpmZmVmOGIxZmI4YjAzNzZlMWE4ZTI3NWM5MWU1NTQ3YQ==]
Transfer-Encoding: [chunked]
Accept: [application/json]
Connection: [keep-alive]
User-Agent: [Synapse-PT-HttpComponents-NIO]
Host: [localhost:57001]
Content-Type: [application/json; charset=UTF-8]
{ "payload": "string"}
Conclusion
Through this custom mediation flow example, we were able to see how WSO2 provides a wider range of solutions that can be easily implemented. We also learned how to solve real problems when creating our API and when integrating them to other servers.
Ultimately, API Manager provides a configuration and customization mechanism for endpoint security.
