[WSO2] [APIM] Custom authentication handler for Okta based token validation

When invoking an API published in WSO2 API manager, the user has to send a valid access token (Oauth 2.0 token) in the Authorization header to verify the identity of the invoker. WSO2 API gateway calls the key validation service in the key manager component in order to check the validity of the token. If it is valid, the user can invoke the API and if not, the user will be served with a 401 (Unauthorized) response.

The key manager is usually a WSO2 component (APIM key manager, Identity Server as key manager). However, there can be some usecases where we need to integrate a third part key manager for authorizing API invocation requests. API manager provides an extension point for integrating third part identity providers as the key manager of APIM manager setup. You can follow [1] and integrate a third party key manager to WSO2 API manager deployment.

There can be situations, where the token was issued by a different key manager/Oauth identity provider which is not integrated to APIM and you just need to validate the token against the particular identity provider. In such cases, you can write a custom handler to replace the default Authentication handler which calls the default key validation service.

In this article, I will discuss on how to write a custom authentication handler to validate an access token (issued by Okta) against Okta.

This custom handler will replace the default authentication handler and validate the access token by calling the Okta introspection endpoint [3]. If the introspection endpoint identifies the token as valid, then the handler will authorize the request. If you want to control the API access based on the scopes, this handler can be modified to authorize the requests if and only if the given token was generated with a white listed scope (We have to maintained a set of white listed scopes in the properties file and validate the requests against it).

Following are the steps to configure the Okta based integration.

1. Download the source code here. Open the okta.properties file located at resources directory and provide the values for introspectionEndpoint, client_id and client_secret of the APP you have already created in Okta. You can provide 'NA' (client_secret=NA) if the id and secret values are not available for the app.

 Please enable debug logs if you want to check the requests being sent to the introspection endpoint.

• open log4j.properties file located at <APIM_HOME>/repository/conf/ directory and add the following line:

     log4j.logger.org.wso2.carbon.authorization=DEBUG

2. Use Maven to build the project (mvn clean install), copy the authorization-1.0.0-SNAPSHOT.jar to <server-home>/repository/components/lib/ folder and restart the server.

 3. Create and publish your API using API publisher UI(Eg: let's assume API name is BlogPost, API version is 1.0.0 and user who published the API is admin)

4. Then go to the following directory

<API_MANAGER_HOME>/repository/deployment/server/synapse-configs/default/api/

5. Open the xml file with the following format

{API Provider}–{API Name}_v{Version}.xml(Eg: admin--BlogPost_v1.0.0.xml)

6. Replace

<handler class="org.wso2.carbon.apimgt.gateway.handlers.security.APIAuthenticationHandler"/>

with

<handler class="org.wso2.carbon.authorization.UserAuthorizationHandler"/>

7. Wait some time until he API get redeployed (Expects following message in <server-home>/repository/logs/wso2carbon.log file

[2017-02-08 11:51:54,988] INFO - API Initializing API: admin--BlogPost:v1.0.0

[2017-02-08 11:51:54,990] INFO - DependencyTracker API : admin--BlogPost:v1.0.0 was updated from the Synapse configuration successfully

[2017-02-08 11:51:54,990] INFO - APIDeployer API: admin-BlogPost:v1.0.0 has been updated from the file: /home/user/demo/setup/wso2am-2.1.0/repository/deployment/server/synapse-configs/default/api/admin--BlogPost_v1.0.0.xml

[2017-02-08 11:51:56,990] INFO - API Destroying API: admin--BlogPost:v1.0.0

8. Now the API is ready to be invoked with a token returned from Okta.

Sample request:

curl -X GET --header 'Accept: application/xml' --header 'Authorization: Bearer <complete token returned from okta>' 'https://10.200.7.41:8243/test/1/*' -k

We configured the custom handler through editing the API xml directly. This change will be overridden by the default handler if your republish the API. Also, your new apis will not be deployed with the custom handler. In order to make this change permanent, please modify the global API template (velocity_template) as follows:

1. Backup existing velocity_template.xml file located at

 <APIM_HOME>/repository/resources/api_templates/ directory and open it in an editor.

2. Replace the <handlers> element with following (this will replace the default handler with the custom handler we wrote):

<handlers xmlns="http://ws.apache.org/ns/synapse">

<handler class="org.wso2.carbon.authorization.UserAuthorizationHandler" />

#foreach($handler in $handlers)

#if(!($handler.className == "org.wso2.carbon.apimgt.gateway.handlers.security.APIAuthenticationHandler"))

<handler xmlns="http://ws.apache.org/ns/synapse" class="$handler.className">

#if($handler.hasProperties())

#set ($map = $handler.getProperties() )
#foreach($property in $map.entrySet())

<property name="$!property.key" value="$!property.value"/>

#end
#end

</handler>

#end
#end

</handlers>

3. Save the change and publish a test api to check whether the custom handler is properly placed as bellow in the api xml file located at <APIM_HOME>/repository/deployment/server/synapse-configs/default/api/ directory.

<handlers>

<handler class="org.wso2.carbon.authorization.UserAuthorizationHandler"/>

<handler class="org.wso2.carbon.apimgt.gateway.handlers.common.APIMgtLatencyStatsHandler"/>

<handler class="org.wso2.carbon.apimgt.gateway.handlers.security.CORSRequestHandler">

<property name="apiImplementationType" value="ENDPOINT"/>

</handler>

<handler class="org.wso2.carbon.apimgt.gateway.handlers.throttling.ThrottleHandler"/>

<handler class="org.wso2.carbon.apimgt.gateway.handlers.analytics.APIMgtUsageHandler"/>

<handler class="org.wso2.carbon.apimgt.gateway.handlers.analytics.APIMgtGoogleAnalyticsTrackingHandler">

<property name="configKey" value="gov:/apimgt/statistics/ga-config.xml"/>

</handler>

<handler class="org.wso2.carbon.apimgt.gateway.handlers.ext.APIManagerExtensionHandler"/>

</handlers>

Please note the following limitations as well

1. Since this approach replaces the APIM default key validation flow, you won't be able to create applications, generate access tokens and invoke apis through the WSO2 API store. You will have to pass a valid token retrieved from Okta to invoke the apis.

2. Handler will call the okta introspection endpoint for validating each request since there is no token caching mechanism.

3. API subscription level usage stats and some of the subscription level throttling policies won't work as those are handled by the default authentication handler.

[1] https://docs.wso2.com/display/AM210/Configuring+a+Third-Party+Key+Manager

[2] https://docs.wso2.com/display/AM200/Writing+Custom+Handlers

[3] https://developer.okta.com/docs/api/resources/oauth2.html#introspection-request