Sascha Preibisch

Tip of the week: protecting APIs using OAuth / OTK

Blog Post created by Sascha Preibisch Employee on Oct 2, 2017

Hi everybody!

This weeks tip is meant for anybody implementing oauth protected API's on the CA API Gateway or CA Mobile API Gateway. With both products the OAuth Toolkit (OTK) will be leveraged.


Here is the tip: Use variables set by 'OTK Require OAuth 2.0 Token'

When implementing oauth protected API's the main assertion to use is named OTK Require OAuth 2.0 Token. That assertion finds an incoming access_token and validates it. If the given token is invalid the assertion fails and returns an error. If the token is valid a few variables are being set. And those can be very useful when it comes to requiring more than just the token itself.

Here is a list of those variables and what they contain:

  • access_token: the token that was used by the client. This is mainly for informational purposes
  • session.client_id: the client_id of the client that has requested the token initially. This is for informational purposes but it could also be used to look up other associated values of this client
  • session.scope: the granted SCOPE for this token. The content is a space separated list of values. It is useful to implement branches within an API that retrieves data based on the SCOPE. An example can be found at /openid/connect/v1/userinfo. That API first requires the SCOPE=openid (configured in OTK Require OAuth 2.0 Token). Further down it checks if the granted SCOPE includes values such as email or profile. Have a look how this variable is used with OTK SCOPE Verification
  • session.subscriber_id: this is the username of the resource_owner that has granted the initial authorization request. If no consent was required during the token issuing process (e.g.: grant_type=password) it's simply the authenticated user. If the token was issued via grant_type=client_credentials the value will be the name of the client
  • session.expires_at: the timestamp at which the token expires
  • session.custom: this contains a JSON structure. The content contains values that were specified when the oauth client was registered in OAuth Manager. It also contains runtime information. In order to learn about the content, and since it varies, do the following during development: Use an Audit Detail assertion to log the content of '${session.custom}'. Afterwards extract values using the Evaluate JSON Path Expression assertion when you know what you want to extract. By default values such as the following are available:
    • client_type: either 'confidential' or 'public'
    • grant_type: the grant_type used to obtain the token

What to do with those variables

Now that you know about these variables you can implement use cases such as the following:

  • grant access only if the token was obtained via a specific grant_type
  • extract attributes of the current user to pass them on to the backend service
  • grant different access to resources depending on the client type
  • implement rate limiting based on the access_token for special cases


I hope this helps, and as usual, let me know if you need more information or details or if you have got other related questions!