How to Get Scopes Related with an Application Based on Subscribed APIs in WSO2 API Manager 2.1.0?

Megala Uthayakumar
4 min readDec 6, 2017

--

WSO2 API Manager provides the capability to create, manage and publish APIs. APIs are very important in most of the business scenarios today. The list of users, who can use the particular API can vary based on the nature of the business. Hence, there should be a proper way of securing APIs. API Manager provides OAuth 2.0 based secured access to the APIs.

However due to high impact of APIs in business scenarios, it is important to have fine grained authorization to API resource level. Fine grained authorization is provided by OAuth 2.0 scopes in API Manager. When creating the API, we can add relevant scopes to each API resource as below,

Adding scopes
Above screenshot shows a sample scenario, where an API is exposed in an online food delivery service. There are 3 roles in the system, which are delivery_boy, customer_service_agent and manager. As the name indicates, relevant employees will be added to relevant roles, based on their position.As shown above API resources that are used for adding and updating the order can only be accessible by customer_service_agents and manager. Getting the order details is exposed to delivery_boy, customer_service_agent and manager roles. Deleting an order is a sensitive operation, so it can only be used by manager.

We need to subscribe to an API, to generate the relevant access token to access the API. However when generating the access token, we need to pass the relevant scopes as an argument, to get the token generated with relevant scopes. Even though if we have an access token but without scopes, we cannot access the relevant API resources that are protected with scopes. So it is an essential requirement, for an subscriber to know the relevant scopes related with the subscribed API before generating token.

In the current API Store UI, when generating token with application client ID and client secret, if there are any scopes related with the subscribed APIs, those will be listed as below,

The API subscribers can select the scopes and generate the access token. This is achieved in UI using jaggery APIs. Recently we introduced a new REST API to achieve extended similar capability with the WUM update. In order to get the scopes of an application based on subscribed APIs, application UUID should be passed as path parameter. Application UUID can be retrieved by using following curl URL,

curl -k -H “Authorization: Bearer a2ddc5fb-6509–3dc7–8956-f47037a3cf52” “https://localhost:9443/api/am/store/v0.11/applications/"

Response will be in followoing format,

{“count”:1,”next”:””,”previous”:””,”list”:[{“applicationId”:”f1d1095d-5928–427e-8100–968ea09d637f”,”name”:”DefaultApplication”,”subscriber”:”delivery_boy”,”throttlingTier”:”Unlimited”,”description”:null,”status”:”APPROVED”,”groupId”:””}]

Then we can call the REST API for getting scopes as below

curl -k -H “Authorization: Bearer a2ddc5fb-6509–3dc7–8956-f47037a3cf52” “https://localhost:9443/api/am/store/v0.11/applications/scopes/f1d1095d-5928-427e-8100-968ea09d637f"

This will return all the scopes as below,

{“list”:[{“key”:”orderUpdate”,”name”:”orderUpdate”,”roles”:”customer_service_agent,manager”,”description”:””},{“key”:”addOrder”,”name”:”addOrder”,”roles”:”customer_service_agent,manager”,”description”:””},{“key”:”orderDelete”,”name”:”orderDelete”,”roles”:”manager”,”description”:””},{“key”:”delivery”,”name”:”delivery”,”roles”:”delivery_boy,customer_service_agent,manager”,”description”:””}]}

This API also supports an optional query parameter which is “filterByUserRoles”. By default “filterByUserRoles” parameter is considered as false. If the filterByUserRoles is set to true, only the relevant scopes, that the particular user is entitled to will be returned based on user roles.

When the filterByUserRoles is set to true, responses for the scope REST API will vary as follow,

Request

curl -k -H “Authorization: Bearer a2ddc5fb-6509–3dc7–8956-f47037a3cf52” “https://localhost:9443/api/am/store/v0.11/applications/scopes/f1d1095d-5928-427e-8100-968ea09d637f?filterByUserRoles=true"

For delivery boy,

{“list”:[{“key”:”delivery”,”name”:”delivery”,”roles”:”delivery_boy,customer_service_agent,manager”,”description”:””}]}

For customer service agent,

{“list”:[{“key”:”orderUpdate”,”name”:”orderUpdate”,”roles”:”customer_service_agent,manager”,”description”:””},{“key”:”addOrder”,”name”:”addOrder”,”roles”:”customer_service_agent,manager”,”description”:””},{“key”:”delivery”,”name”:”delivery”,”roles”:”delivery_boy,customer_service_agent,manager”,”description”:””}]}

For manager,

{“list”:[{“key”:”orderUpdate”,”name”:”orderUpdate”,”roles”:”customer_service_agent,manager”,”description”:””},{“key”:”addOrder”,”name”:”addOrder”,”roles”:”customer_service_agent,manager”,”description”:””},{“key”:”orderDelete”,”name”:”orderDelete”,”roles”:”manager”,”description”:””},{“key”:”delivery”,”name”:”delivery”,”roles”:”delivery_boy,customer_service_agent,manager”,”description”:””}]}

For the purpose of caching scopes we have introduced a cache called “ScopeCache”, which caches, the scope entries against particular user. This can be enabled by adding following configuration under CacheConfigurations element in api-manager.xml in <APIM_Home>/repository/conf directory.

<CacheConfigurations>
.....
<EnableScopeCache>true</EnableScopeCache>
</<CacheConfigurations>

We highly recommend to enable this cache, if the API Manager setup is in a environment where the subscription changes or user role list changes does not happen very frequently. Enabling this cache will give positive effect on the performance.

However, if you are in a development environment, where the API subscription changes or user role update changes happens frequently, this cache can be disabled by setting “EnableScopeCache” element to false.

In order to use this feature, download WSO2 API Manager 2.1.0 and update it through WUM.

References

--

--