Sascha Preibisch

OTK and SCOPE

Blog Post created by Sascha Preibisch Employee on 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

 

Q&A:

 

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

Outcomes