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
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.
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.
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
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.
2. If 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.
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.
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.
Consumer API enforcement
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
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
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
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]"
}
}
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.