Using a Basic Auth handler
In most of the real-world use cases of REST, when a consumer attempts to access a privileged resource, credentials must be provided in an Authorization header or the consumer will be refused access. In WSO2 ESB, when we want to secure an API, we can simply make it available via HTTPS and let the security handlers validate the credentials. By default, the ESB does not include any REST Security Handlers, but the following example of a primitive security handler serves as a template that can be used to write your own security handler to secure an API in the ESB.
You add the REST request handler to the <handlers> element of the API configuration, as follows (you cannot add it through the API UI):
<api name="StockQuoteAPI" context="/stockquotenew" xmlns="http://ws.apache.org/ns/synapse">
<resource uri-template="/view/{symbol}" methods="GET" protocol="https">
<inSequence>
<payloadFactory>
<format>
<m0:getQuote xmlns:m0="http://services.samples">
<m0:request>
<m0:symbol>$1</m0:symbol>
</m0:request>
</m0:getQuote>
</format>
<args>
<arg expression="get-property('uri.var.symbol')"/>
</args>
</payloadFactory>
<header name="Action" value="urn:getQuote"/>
<send>
<endpoint>
<address uri="http://localhost:9000/services/SimpleStockQuoteService" format="soap11"/>
</endpoint>
</send>
</inSequence>
<outSequence>
<send/>
</outSequence>
</resource>
<handlers>
<handler class="org.wso2.rest.BasicAuthHandler"/>
</handlers>
</api>
The custom Basic Auth handler in this sample simply verifies whether the request uses username: admin and password: admin. Following is the code for this handler:
package org.wso2.rest;
import org.apache.commons.codec.binary.Base64;
import org.apache.synapse.MessageContext;
import org.apache.synapse.core.axis2.Axis2MessageContext;
import org.apache.synapse.core.axis2.Axis2Sender;
import org.apache.synapse.rest.Handler;
import java.util.Map;
public class BasicAuthHandler implements Handler {
public void addProperty(String s, Object o) {
//To change body of implemented methods use File | Settings | File Templates.
}
public Map getProperties() {
return null; //To change body of implemented methods use File | Settings | File Templates.
}
public boolean handleRequest(MessageContext messageContext) {
org.apache.axis2.context.MessageContext axis2MessageContext
= ((Axis2MessageContext) messageContext).getAxis2MessageContext();
Object headers = axis2MessageContext.getProperty(
org.apache.axis2.context.MessageContext.TRANSPORT_HEADERS);
if (headers != null && headers instanceof Map) {
Map headersMap = (Map) headers;
if (headersMap.get("Authorization") == null) {
headersMap.clear();
axis2MessageContext.setProperty("HTTP_SC", "401");
headersMap.put("WWW-Authenticate", "Basic realm=\"WSO2 ESB\"");
axis2MessageContext.setProperty("NO_ENTITY_BODY", new Boolean("true"));
messageContext.setProperty("RESPONSE", "true");
messageContext.setTo(null);
Axis2Sender.sendBack(messageContext);
return false;
} else {
String authHeader = (String) headersMap.get("Authorization");
String credentials = authHeader.substring(6).trim();
if (processSecurity(credentials)) {
return true;
} else {
headersMap.clear();
axis2MessageContext.setProperty("HTTP_SC", "403");
axis2MessageContext.setProperty("NO_ENTITY_BODY", new Boolean("true"));
messageContext.setProperty("RESPONSE", "true");
messageContext.setTo(null);
Axis2Sender.sendBack(messageContext);
return false;
}
}
}
return true;
}
public boolean handleResponse(MessageContext messageContext) {
return true;
}
public boolean processSecurity(String credentials) {
String decodedCredentials = new String(new Base64().decode(credentials.getBytes()));
String usernName = decodedCredentials.split(":")[0];
String password = decodedCredentials.split(":")[1];
if ("admin".equals(username) && "admin".equals(password)) {
return true;
} else {
return false;
}
}
}
You can build the project (mvn clean install) for this handler by accessing its source here:
Alternatively, you can download the JAR file from the following location, copy it to the repository/component/lib directory, and restart the ESB:
You can now send a request to the secured API. For example, you can send it using cURL as the REST client:
curl -v -k -H "Authorization: Basic YWRtaW46YWRtaW4=" https://localhost:8243/stockquotenew/view/IBM
Using an OAuth base security token
You can generate an OAuth base security token using WSO2 Identity Server, and then use that token when invoking your API to connect to a REST endpoint. This approach involves the following tasks:
- Create a custom handler that will validate the token
- Create an API that points to the REST endpoint and includes the custom handler
- Create an OAuth application in Identity Server and get the access token
- Invoke the API with the access token
Creating the custom handler
The custom handler must extend AbstractHandler and implement ManagedLifecycle as shown in the following example. You can download the Maven project for this example at https://github.com/wso2-docs/ESB/tree/master/ESB-Artifacts/OAuthHandler_Sample
package org.wso2.handler;
import org.apache.axis2.AxisFault;
import org.apache.axis2.client.Options;
import org.apache.axis2.client.ServiceClient;
import org.apache.axis2.context.ConfigurationContext;
import org.apache.axis2.context.ConfigurationContextFactory;
import org.apache.axis2.transport.http.HTTPConstants;
import org.apache.axis2.transport.http.HttpTransportProperties;
import org.apache.commons.logging.Log;
import org.apache.commons.logging.LogFactory;
import org.apache.http.HttpHeaders;
import org.apache.synapse.core.axis2.Axis2MessageContext;
import org.wso2.carbon.identity.oauth2.stub.OAuth2TokenValidationServiceStub;
import org.wso2.carbon.identity.oauth2.stub.dto.OAuth2TokenValidationRequestDTO;
import org.apache.synapse.ManagedLifecycle;
import org.apache.synapse.MessageContext;
import org.apache.synapse.core.SynapseEnvironment;
import org.apache.synapse.rest.AbstractHandler;
import org.wso2.carbon.identity.oauth2.stub.dto.OAuth2TokenValidationRequestDTO_OAuth2AccessToken;
import java.util.Map;
public class SimpleOAuthHandler extends AbstractHandler implements ManagedLifecycle {
private static final String CONSUMER_KEY_HEADER = "Bearer";
private static final String OAUTH_HEADER_SPLITTER = ",";
private static final String CONSUMER_KEY_SEGMENT_DELIMITER = " ";
private static final String OAUTH_TOKEN_VALIDATOR_SERVICE = "oauth2TokenValidationService";
private static final String IDP_LOGIN_USERNAME = "identityServerUserName";
private static final String IDP_LOGIN_PASSWORD = "identityServerPw";
private ConfigurationContext configContext;
private static final Log log = LogFactory.getLog(SimpleOAuthHandler.class);
@Override
public boolean handleRequest(MessageContext msgCtx) {
if (this.getConfigContext() == null) {
log.error("Configuration Context is null");
return false;
}
try{
//Read parameters from axis2.xml
String identityServerUrl =
msgCtx.getConfiguration().getAxisConfiguration().getParameter(
OAUTH_TOKEN_VALIDATOR_SERVICE).getValue().toString();
String username =
msgCtx.getConfiguration().getAxisConfiguration().getParameter(
IDP_LOGIN_USERNAME).getValue().toString();
String password =
msgCtx.getConfiguration().getAxisConfiguration().getParameter(
IDP_LOGIN_PASSWORD).getValue().toString();
OAuth2TokenValidationServiceStub stub =
new OAuth2TokenValidationServiceStub(this.getConfigContext(), identityServerUrl);
ServiceClient client = stub._getServiceClient();
Options options = client.getOptions();
HttpTransportProperties.Authenticator authenticator = new HttpTransportProperties.Authenticator();
authenticator.setUsername(username);
authenticator.setPassword(password);
authenticator.setPreemptiveAuthentication(true);
options.setProperty(HTTPConstants.AUTHENTICATE, authenticator);
client.setOptions(options);
OAuth2TokenValidationRequestDTO dto = this.createOAuthValidatorDTO(msgCtx);
return stub.validate(dto).getValid();
}catch(Exception e){
log.error("Error occurred while processing the message", e);
return false;
}
}
private OAuth2TokenValidationRequestDTO createOAuthValidatorDTO(MessageContext msgCtx) {
OAuth2TokenValidationRequestDTO dto = new OAuth2TokenValidationRequestDTO();
Map headers = (Map) ((Axis2MessageContext) msgCtx).getAxis2MessageContext().
getProperty(org.apache.axis2.context.MessageContext.TRANSPORT_HEADERS);
String apiKey = null;
if (headers != null) {
apiKey = extractCustomerKeyFromAuthHeader(headers);
}
OAuth2TokenValidationRequestDTO_OAuth2AccessToken token =
new OAuth2TokenValidationRequestDTO_OAuth2AccessToken();
token.setTokenType("bearer");
token.setIdentifier(apiKey);
dto.setAccessToken(token);
return dto;
}
private String extractCustomerKeyFromAuthHeader(Map headersMap) {
//From 1.0.7 version of this component onwards remove the OAuth authorization header from
// the message is configurable. So we dont need to remove headers at this point.
String authHeader = (String) headersMap.get(HttpHeaders.AUTHORIZATION);
if (authHeader == null) {
return null;
}
if (authHeader.startsWith("OAuth ") || authHeader.startsWith("oauth ")) {
authHeader = authHeader.substring(authHeader.indexOf("o"));
}
String[] headers = authHeader.split(OAUTH_HEADER_SPLITTER);
if (headers != null) {
for (String header : headers) {
String[] elements = header.split(CONSUMER_KEY_SEGMENT_DELIMITER);
if (elements != null && elements.length > 1) {
boolean isConsumerKeyHeaderAvailable = false;
for (String element : elements) {
if (!"".equals(element.trim())) {
if (CONSUMER_KEY_HEADER.equals(element.trim())) {
isConsumerKeyHeaderAvailable = true;
} else if (isConsumerKeyHeaderAvailable) {
return removeLeadingAndTrailing(element.trim());
}
}
}
}
}
}
return null;
}
private String removeLeadingAndTrailing(String base) {
String result = base;
if (base.startsWith("\"") || base.endsWith("\"")) {
result = base.replace("\"", "");
}
return result.trim();
}
@Override
public boolean handleResponse(MessageContext messageContext) {
return true;
}
@Override
public void init(SynapseEnvironment synapseEnvironment) {
try {
this.configContext =
ConfigurationContextFactory.createConfigurationContextFromFileSystem(null, null);
} catch (AxisFault axisFault) {
log.error("Error occurred while initializing Configuration Context", axisFault);
}
}
@Override
public void destroy() {
this.configContext = null;
}
private ConfigurationContext getConfigContext() {
return configContext;
}
}
Creating the API
You will now create an API named TestGoogle that connects to the following endpoint: https://www.google.lk/search?q=wso2
- In the ESB Management Console, go to Manage -> Service Bus and click Source View.
Insert the following XML configuration into the source view before the closing
</definitions>tag to create the TestGoogle API:<api xmlns="http://ws.apache.org/ns/synapse" name="TestGoogle" context="/search"> <resource methods="GET"> <inSequence> <log level="full"> <property name="STATUS" value="***** REQUEST HITS IN SEQUENCE *****"/> </log> <send> <endpoint> <http method="get" uri-template="https://www.google.lk/search?q=wso2"/> </endpoint> </send> </inSequence> </resource> <handlers> <handler class="org.wso2.handler.SimpleOAuthHandler"/> </handlers> </api>Notice that the
<handlers>tag contains the reference to the custom handler class.- Copy the custom
handler.jarto the<ESB_HOME>/repository/components/libsdirectory. Open
<ESB_HOME>/repository/conf/axis2/axis2.xmland add the following parameters:<!-- OAuth2 Token Validation Service --> <parameter name="oauth2TokenValidationService">https://localhost:9444/services/OAuth2TokenValidationService</parameter> <!-- Server credentials --> <parameter name="identityServerUserName">admin</parameter> <parameter name="identityServerPw">admin</parameter>
- Restart the ESB.
Getting the OAuth token
You will now use Identity Server to create an OAuth application and generate the security token.
- Start WSO2 Identity Server and log into the management console.
- Click Manage -> OAuth and create an OAuth application.
- Note the access token URL and embed it in a cURL request to get the token. For example, use the following command and replace
<client-id>and<client secret>with the actual values:
curl -v -k -X POST --user <client-id>:<client secret> -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" -d 'grant_type=password&username=admin&password=admin' https://localhost:9444/oauth2/token
Identity Server returns the access token, which you can now use when invoking the API. For example:
curl -v -X GET -H "Authorization: Bearer ca1799fc84986bd87c120ba499838a7" http://localhost:8280/search
Using a policy file to authenticate with a secured back-end service
You can connect a REST client to a secured back-end service (such as a SOAP service) through an API that reads from a policy file.
First, you configure the ESB to expose the API to the REST client. For example:
<definitions xmlns="http://ws.apache.org/ns/synapse">
<localEntry key="sec_policy"
src="file:repository/samples/resources/policy/policy_3.xml"/>
<api name="StockQuoteAPI" context="/stockquote">
<resource methods="GET" uri-template="/view/{symbol}">
<inSequence trace="enable">
<header name="Action" value="urn:getQuote"/>
<payloadFactory>
<format>
<m0:getQuote xmlns:m0="http://services.samples">
<m0:request>
<m0:symbol>$1</m0:symbol>
</m0:request>
</m0:getQuote>
</format>
<args>
<arg expression="get-property('uri.var.symbol')"/>
</args>
</payloadFactory>
<send>
<endpoint name="rest">
<address uri="http://localhost:9000/services/SecureStockQuoteService"
format="soap11">
<enableAddressing/>
<enableSec policy="sec_policy"/>
</address>
</endpoint>
</send>
</inSequence>
<outSequence trace="enable">
<header xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd"
name="wsse:Security"
action="remove"/>
<send/>
</outSequence>
</resource>
<resource methods="POST">
<inSequence>
<property name="FORCE_SC_ACCEPTED" value="true" scope="axis2"/>
<property name="OUT_ONLY" value="true"/>
<send>
<endpoint>
<address uri="http://localhost:9000/services/SimpleStockQuoteService"
format="soap11"/>
</endpoint>
</send>
</inSequence>
</resource>
</api>
</definitions>
The policy file stores the security parameters that are going to authenticated by the back-end service. You specify the policy file with the localEntry property, which in this example we've named sec_policy:
<localEntry key="sec_policy"
src="file:repository/samples/resources/policy/policy_3.xml"/>
You use then reference the policy file by its localEntry name when enabling the security policy for the end point:
<address uri="http://localhost:9000/services/SecureStockQuoteService"
format="soap11">
<enableAddressing/>
<enableSec policy="sec_policy"/>
</address>
In the outSequence property, the security header must be removed before sending the response back to the REST client.
<outSequence trace="enable">
<header xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd"
name="wsse:Security"
action="remove"/>
To test this API configuration, you must run the SecureStockQuoteService, which is bundled in the WSO2 ESB samples folder, as the back-end server. Start this sample as described in Setting Up the ESB Samples. Because this sample uses Apache Rampart for the back-end security implementation, you might also need to download and install the unlimited strength policy files for your JDK before using Apache Rampart.
To download the unlimited strength policy files:
- Go to http://www.oracle.com/technetwork/java/javase/downloads/index.html.
- Scroll to the bottom of the page and download the file called Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files x (x is the JDK version) for your JDK version.
- Extract the downloaded ZIP. You’ll now have two JAR files:
local_policy.jarandUS_export_policy.jar. - In your Java installation directory, go to the
jre/lib/securitydirectory, such as:/usr/java/jdk1.6.0_38/jre/lib/security - Make a backup of the files
local_policy.jarandUS_export_policy.jarand then replace them with the ones from the JCE ZIP file.
Now that you have set up the API and the secured back-end SOAP service, you are ready to test this configuration with the following curl command.
curl -v http://127.0.0.1:8280/stockquote/view/IBM
Observe that the REST client is getting the correct response (the wsse:Security header is removed from the decrypted message) while going through the secured back-end service and the API implemented in the ESB. You can use a TCP monitoring tool such as tcpmon to monitor the message sent from the ESB and the response message received by the ESB. For a tutorial on using tcpmon, see: http://technonstop.com/tcpmon-tutorial
Transforming Basic Auth to WS-Security
REST clients typically use Basic Auth over HTTP to authenticate the user name and password, but if the back-end service uses WS-Security, you can configure the API to transform the authentication from Basic Auth to WS-Security.
To achieve this transformation, you configure the ESB to expose the API to the REST client as shown in the previous example, but you add the HTTPS protocol and Basic Auth handler to the configuration as shown below:
<?xml version="1.0" encoding="UTF-8"?>
<definitions xmlns="http://ws.apache.org/ns/synapse">
<localEntry key="sec_policy"
src="file:repository/samples/resources/policy/policy_3.xml"/>
<api name="StockQuoteAPI" context="/stockquote">
<resource methods="GET" uri-template="/view/{symbol}" protocol="https" >
...
</resource>
<handlers>
<handler class="org.wso2.rest.BasicAuthHandler"/>
</handlers>
</api>
</definitions>
This configuration allows two-fold security: the client authenticates with the API using Basic Auth over HTTPS, and then the API sends the request to the back-end service using the security policy.
You can test this configuration using the following command:
curl -v -k -H "Authorization: Basic YWRtaW46YWRtaW4=" https://localhost:8243/stockquote/view/IBM