I recently started using an online grocery service. No more long lineups in the grocery store (and the tempting candy near the cashier)! I simply created my order online and picked it up at the local grocery store. One of the items on my list was apples. There are many kinds of apples (McIntosh, Red Delicious, Granny Smith, Gala) but I was not given a choice of apple when ordering, they simply assigned me a Gala apple at pickup, which happened to be my first choice! This example demonstrates an experience where I asked for an item (apple) and the grocery store (perhaps based on inventory in Canada) selected a Gala apple. API Connect released a feature called Advance OAuth scope check, which is very similar to my ordering apples experience. Let's get into more details on how apples and OAuth scope are related.

What is OAuth scope?

A scope is a string that is used to identify the resources granted access within an OAuth access token. The meaning of the scope is dependent upon the resource provider. For example, common scopes may include strings such as read and write. If a read scope is issued to an access token but the API operation performs a write operation, then the resource provider will reject the request.

What is Advance Scope Check?

OAuth clients will present scopes to the OAuth server (as per the OpenAPI definition) and validate the resource owner credentials and obtain consent before issuing an access token with the scopes. In a regular scenario, what you ask for is what you get. If I ordered a gala apple (scope), then I would get a gala apple (scope) on checkout. In the Advance scope check scenario, I could order an apple (scope) but get a gala apple (scope) on checkout. This capability allows the OAuth server to constrain access to the resources via scopes with little complexity. Consider that if you decided to list every single apple as a scope, it would become quite complicated; instead, you provide a generic scope and using the Advance scope check, you can issue the actual scope to the application.

Advance Scope check configuration within API Connect

The Advance scope check is a toggle that is available in the OAuth2 provider configuration. You specify a URL to the microservice that reads the current scope and returns a new scope via a response header x-selected-scope. This step is performed before issuing the access token.



For example the microservice would receive the following input

{
 "app-name":"Default%2BApplication",
 "appid":"96bcdd05db5c74dad2aceb360",
 "org":"toolkit",
 "orgid":"5887803de4b06e6998c4b2c7",
 "catalog":"apic-dev",
 "catalogid":"5887803de4b06e6998c4b2d3",
 "transid":"16065",
 "token_scope":"apples",
 "api_scope":"oranges apples"
}

The key fields are the token_scope (user provided) and the api_scope (available scopes). The microservice can determine based on this information what is the scope they will issue (if any).

var token_scope = request.parameters.token_scope;
//pseudo code: check apples inventory
message.headers.x-selected-scope = 'gala_apples';

The following response returns the selected scope, which now becomes the new scope for the access token.

{
 "token_type": "bearer",
 "access_token": "AAEHZGVmYXVsdDL_yUUvOEJfWzJa48m5J7aYJ8dJHbQIoEljgGpfwthSX5wiB4V5z1zXPlUPwPyHon71aL7ylQ8bXly9pLGgceGfl85hHoYFv7wRcZmnTzkj",
 "expires_in": 3600,
 "scope": "gala_apples"
}

 

In this tutorial, you learned how to use the new advance scope check to assign new scopes to access tokens that are different than the original scope. In addition, you might be hungry for gala apples.

Reference

• IBM Knowledge Center