Skip navigation
All People > Sascha Preibisch > Sascha Preibisch's Blog > 2015 > September

Sascha Preibisch's Blog

September 2015 Previous month Next month

Lately I got involved in discussions that had “OAuth and Step-Up Authentication” as its topic. The question always was about how to tie OAuth access_token and other credentials together.


The idea of Step-Up Authentication is that an API can only be consumed if a credential with a higher (or different) assurance level is available. For example, a transaction API may require an access_token for general use. In addition, because that access_token is used with parameters that indicate a high risk transaction, the API wants to assure that the current resource_owner is still the one associated with the access_token. For that, it requires an OTP as an additional input parameter.

After considerable debate we discovered that it comes down to this:

  • Step-Up Authentication is a hierarchical order of credentials. It may be a list of individual credentials or credentials derived from each other


Looking at it that way may simplify things. Instead of finding of a way on how to tie credentials together it may be sufficient to simply require multiple ones of different types.

Imagine something like this:

  • the transaction API will handle two cases: lower assurance level required, higher assurance level required. This decision on what is required can be based on incoming parameter values or in conjunction with systems like CA Advanced Auth
  • the transaction API will process credentials in an hierarchical order, from low to high
  • it first requires and validates an access_token. This is the minimum requirement to get access to this API and reflects the lower assurance level in this scenario
  • for the higher assurance level the API requires an additional OTP

This is a simplified view but it shows the logic that could be used.

In order to make this work, it is certainly required that the API is well documented. Documentation also needs to explain how to retrieve a valid access_token and/ or an OTP and in which case they have to be provided.

Sascha Preibisch


Posted by Sascha Preibisch Employee Sep 15, 2015

I get many questions on how SCOPE works and on how it is handled in OTK. I will try to answer that question right here and now.


General rules:

  • OAuth clients have to be registered using OAuth Manager
  • OAuth clients can be registered with a space separated list of SCOPE values. These case sensitive values can be specified as desired. The target API has to be configured to exactly match those values
  • OTK will receive OAuth token requests and will only issue SCOPE values that were registered for the requesting OAuth client
  • OTK will not do any SCOPE verifications on OAuth protected APIs UNLESS the API author wants it to do so


Here is an example:

  • a developer registers a new OAuth client using OAuth Manager. The registrations includes valid SCOPE values 'READ WRITE'
  • a developer implements an API on the CA API Gateway or CA Mobile API Gateway. For its protection the API requires SSL and a valid access_token
  • since this API will be able to accept READ access, WRITE access and both it implements several flows:
    • if the access_token was granted for SCOPE=READ the API will only accept READ requests
    • if the access_token was granted for SCOPE=WRITE the API will only accept WRITE requests
    • if the access_token was granted for both, the API will accept both requests




As of here I will answer questions that I have received for the topic SCOPE. I will try to answer them with examples.


Q 1: Sascha, in earlier releases (before OTK-3.0.0) OTK did not check SCOPE by default, I had to implement checks myself. How does it work today (as of OTK-3.0+ shipped on gateway 8.3+)?


A 1: OTK only accepts requested SCOPE values that were registered for a given client. The assertion 'OTK Require OAuth 2.0 Token' that is used to protect APIs now takes desired SCOPE values and validates a given access_token against those. If not all required SCOPE values were granted to that access_token, the request will fail.

Example 1:

Issuing token: A requesting client, let's say a client that uses the authorization_code flow, sends a code request that includes the URL encoded parameter '...&scope=READ%20DELETE&...'. OTK will automatically check if the SCOPEs 'READ' and 'DELETE' have been registered for the specific client. If that is the case it will grant the SCOPE, if not, it will remove all non-registered SCOPE values. In this case 'READ' would have been granted where as 'DELETE' would have been removed from the list. If the client had included 'DELETE' only the request would have failed.

API protection, requiring token: The API developer would include the assertion 'OTK Require OAuth 2.0 Token' in its API. That assertion will require 'READ' since the API developer has made the decision that at least 'READ' must have been included. The assertion will only accept the request if the access_token has not expired, is not disabled and has been granted for 'READ'. Following that assertion the API developer will implement branches. Depending on the granted SCOPE the API will accept a READ request or a WRITE request or both. To do that the assertion 'OTK SCOPE Verification' can be used. One branch would be executed if both SCOPEs were granted, 'READ" and 'WRITE', other branches for the case that only one of them has been granted.


Q 2: Sascha, the /token endpoint, how and where does it validate SCOPE?

A 2: The token issuing endpoint /auth/oauth/v2/token verifies SCOPE for all token requests very early in the policy. Find it by searching for the assertion 'OTK SCOPE Issuing'.  There is just one exception: grant_type=authorization_code. SCOPE for that grant type is verified when the client sends the initial response_type=code request. In addition some grant_types require special handling. Find those within the folder 'OTK-<version>/Policy Fragments/grant_types/*'.

Example 2: Use the CA API Policy Manager to explore the API of /auth/oauth/v2/token

Sascha Preibisch

My first blog

Posted by Sascha Preibisch Employee Sep 15, 2015

Hi there!


My first blog, just to get started.


Let's put some real content in here now.