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.
