Scope

Per IETF RFC 6749, the value of the scope parameter is expressed as a list of space-delimited, case-sensitive strings.

In API Connect, scopes have no inherent meaning. Instead, scopes are defined in the provider API so that an application can request an access token that is valid for one or more of the scopes that are defined in the provider API. In the secured API, scopes are listed as requirements for an access token to be considered valid. All scopes that are listed by the security definition of the secured API must be granted by the access token. When an access token is requested from the provider API, multiple scopes are separated by spaces.

OAuth provider

For illustration purposes, the example provider API swagger file that is named provider.yaml defines three scopes that an application can request: checking, saving, and mutual.

provider.yaml

x-ibm-configuration:
    testable: true
    enforced: true
    phase: realized
    oauth2:
      client-type: confidential
      scopes:
        checking: Checking Account
        saving: Saving Account
        mutual: Mutual Fund

To provide more refined support for the OAuth scope handling, API Connect allows the Authentication URL extension to modify the scope value.

[V5.0.8 or later] When you define an OAuth provider, two more extensions allow the flexibility to check and override what scope the application is allowed. The optional extensions are Enable Application Scope Check and Enable Owner Scope Check. The extensions can be set independently.

[V5.0.8 or later] The scope that is eventually received by the application is determined by the interactions that are described in the three following paragraphs. Processing follows the sequence of paragraphs 1, 2, then 3, offering three distinct opportunities to override the scope value. Figure 1. provides an overview of the process.

1. From version 5.0.7.2, after the application successfully authenticates, and if OAuth 2 > Advanced Scope Check > Application Scope Check is configured, API Connect makes a call to allow extra verification and use the contents of x-selected-scope to override the scope value that was initially requested by the application. When Application Scope Check is enabled, the HTTP response header x-selected-scope must be present, or the call fails.

[V5.0.8 or later] 2. If OAuth 2 > Authentication > Authentication URL is enabled and configured with a valid URL, API Connect makes a call, as documented in Authentication URL. When the response code is HTTP 200, and the response header x-selected-scope is present, the value that is configured in x-selected-scope is used as the new scope value, overriding both what the application already requested and what was provided in paragraph 1. In the response header, x-selected-scope is an optional element.

3. After the user successfully authenticates, and if OAuth 2 > Advanced Scope Check > Owner Scope Check is enabled and configured with a valid URL, API Connect makes a call to allow the content of x-selected-scope to refine the scope value. When Owner Scope Check is enabled, the HTTP response header x-selected-scope must be present, or the call fails. [V5.0.8 or later]

OAuth advanced scope overview. — Figure 1. OAuth advanced scope overview

[V5.0.8 or later] The final scope permission that is granted by the access token is the result of the described processing. Figure 2. shows a more detailed view of the transaction flow with examples that show when x-selected-scope provides a new scope value.

OAuth advanced scope detail. — Figure 2. OAuth advanced scope detail

Consumer API enforcement

Standard scope validation

To access the API /getaccount the application must send a GET request with an access token that contains the scope, or scopes, defined in the application API swagger file that describes the secured API.

GET /getaccount
HTTP/1.1
Host: server.example.com
X-IBM-Client-Id: 8888-8888-8888
Authorization: Bearer AAEkNjVkOWIyYjgtOWY5ZS00YWQwLWIyYzktZ

The following application API swagger file secure-banking.yaml defines the scope, or scopes, that must exist in the token to be granted access to the API /getaccount.

secure-banking.yaml

securityDefinitions:
   scope-only:
    type: oauth2
    description: ''
    flow: implicit
    authorizationUrl: ''
    scopes:
      checking: 'Checking Account'
      saving: 'Saving Account'
      mutual: 'Mutual Fund Account'
security:
  - scope-only:
      - checking
  - scope-only:
      - saving
      - mutual

In the examples, the access token AAEkNjVkOWIyYjgtOWY5ZS00YWQwLWIyYzktZ is able to access the API because it contains one, or a combination of scope-only defined in secure-banking.yaml such as:

checking
saving mutual
checking saving mutual

Advanced Scope Check

From version 5.0.7.2, administrators can enable an additional scope check by configuring the consumer API property Advanced Scope Check URL that becomes x-scopeValidate as shown in the following consumer API swagger file example.

securityDefinitions:
  advanced-scope-only:
    type: oauth2
    description: ''
    flow: implicit
    authorizationUrl: ''
    scopes:
      checking: 'Checking Account'
      saving: 'Saving Account'
      mutual: 'Mutual Fund Account'
    x-scopeValidate:
      url: 'https://advanced-scope-check.bk.com/validate-scope'
      tls-profile: 'ssl-client'

After IBM® API Connect successfully verifies the access token against any scope requirement, API Connect will make an HTTP POST request to the x-scopeValidate endpoint similar to the following example. Response code HTTP 200 from the endpoint indicates a success. Any other response code, or a connection error, is treated as the token does not contain necessary permission to access the resource.

     POST /validate-scope?app-name=..&appid=..&org=..&orgid=..&catalog=..&catalogid=..&transid=.. 
HTTP/1.1
     Host: advanced-scope-check.bk.com
     Content-Type: application/json

   {"context-root" : checking,
    "resource" : accountinfo,
    "method" : GET,
    "api-scope-required" : [jointaccount],
    "access_token" : {"client_id" : "2cd71759-1003-4a1e-becb-0474d73455f3",
                      "not_after" : 174364070,
                      "not_after_text" : "2017-07-11T02:27:50Z",
                      "not_before" : 174360470,
                      "not_before_text" : "2017-07-11T01:27:50Z",
                      "grant_type" : "code",
                      "consented_on" : 1499736470,
                      "consented_on_text" : "2059-07-11T01:27:50Z",
                      "resource_owner" : "cn=spoon,email=spoon@poon.com",
                      "scope" : "jointaccount mutual",
                      "miscinfo" : "[r:gateway]"
                    }
}

An example of successful response follows.

     HTTP/1.1 200 OK
     Cache-Control: no-store
     Pragma: no-cache
     X-Custom-For-Assemble-Process: audit

Any HTTP response header that begins with "x-" is kept as the context variable oauth.advanced-consent. Based on the example successful response, X-Custom-For-Assemble-Process: audit becomes oauth.advanced-consent.x-custom-for-assemble-process, and can be accessed in the assemble step.