Scope

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

In IBM® API Connect, scopes have no inherent meaning. Instead, scopes are defined in the OAuth Provider so that an application can request an access token that is valid for one or more of the scopes. 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 for the API must be granted by the access token.
Note:
  • An OAuth Provider must have at least one scope.
  • An OAuth token will not be granted unless a default scope is configured at the provider, or one or more predefined scopes are included in the grant request.
  • If no default scope is defined, and the request does not contain a scope, an invalid scope error is returned for the request.

OAuth provider

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

When you define an OAuth provider, the Advanced scope check extensions provide the flexibility to check and override allowed scopes. The optional extensions are Application scope check and Owner scope check.

The scope that is eventually received by the application is determined by the interactions that are described in the three following paragraphs. Scope processing follows the sequence of items 1, 2, and 3 in the following list, offering three opportunities to override the scope value. Figure 1 provides an overview of the process.

  1. After the application successfully authenticates, and if OAuth Native provider > Advanced scope check > Application scope check is configured, API Connect makes a call to allow extra verification and uses 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.
  2. If OAuth Native provider > User Security > Authentication is configured to authenticate application users using an Authentication URL, then API Connect makes a call, as documented in Authentication URL user registry. 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 the Application scope check described in paragraph 1. In the response header, x-selected-scope is an optional element.
  3. After the user successfully authenticates, and if OAuth Native provider > 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.
    Figure 1. OAuth advanced scope overview
    OAuth advanced scope overview.

The final scope permission that is granted by the access token is the result of the flow described in items 1, 2, and 3. Figure 2 shows a more detailed view of the transaction flow with examples that show when x-selected-scope provides a new scope value.

Figure 2. OAuth advanced scope detail
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 OAuth provider. If the request doesn't contain a scope, you must specify a default scope to use. If no default scope is defined, and the request doesn't contain a scope, an invalid scope error is returned for the request.
GET /getaccount
HTTP/1.1
Host: server.example.com
X-IBM-Client-Id: 8888-8888-8888
Authorization: Bearer AAEkNjVkOWIyYjgtOWY5ZS00YWQwLWIyYzktZ
The following application OpenAPI 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 that is defined in secure-banking.yaml such as:
  • checking
  • saving mutual
  • checking saving mutual
Advanced Scope Check

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 OpenAPI 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 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 a permission error for the token.

     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.

Additional validation options

You can optionally use additional fields for validation:

Request Header
Defines the regular expression to match against request headers. Matching headers are included in the request to the advanced scope validation endpoint.
Response Context Variable

Defines the regular expression to match against response headers. Matching headers are saved as context variables in the format oauth.advanced-consent.*.