有効範囲 (Scope)

OAuth プロバイダー

OAuthスコープ処理をより洗練されたサポートを提供するために、 URL ユーザーレジストリ拡張機能でスコープ値を変更できるようにします。

OAuth プロバイダーを定義すると、 「拡張スコープ検査」 拡張機能により、許可されたスコープを検査およびオーバーライドする柔軟性が提供されます。 オプションの拡張は、「アプリケーション・スコープ検査」および「所有者スコープ検査」です。

アプリケーションが最終的に受け取るスコープは、以下の 3 つのパラグラフで説明されている対話を通じて決定されます。 スコープ処理は以下のリストの項目 1、2、3 の順で行われ、スコープ値をオーバーライドする 3 つの機会を提供します。 図 1 はプロセスの概要を示します。

1. アプリケーションが正常に認証された後、 OAuth ネイティブ・プロバイダー > 「拡張スコープ検査」 > 「アプリケーション・スコープ検査」 が構成されている場合、 API Connect は、追加の検査を許可するための呼び出しを行い、 x-selected-scope の内容を使用して、アプリケーションによって最初に要求されたスコープ値をオーバーライドします。 「アプリケーション・スコープ検査」が有効になっている場合、HTTP 応答ヘッダー x-selected-scope が存在している必要があります。存在していない場合、呼び出しは失敗します。
2. OAuth ネイティブプロバイダー > ユーザーセキュリティ > 認証が、認証 URL を使用してアプリケーションユーザーを認証するように設定されている場合、 API Connect は認証 URL ユーザーレジストリに記載されているように、コールを行います。 応答コードが以下の場合HTTP 200、および応答ヘッダー x-selected-scope が存在する場合、 x-selected-scope で構成されている値が新しいスコープ値として使用され、アプリケーションが既に要求したものと、段落 1 で説明されているアプリケーション・スコープ検査で提供されたものの両方がオーバーライドされます。 応答ヘッダーで、 x-selected-scope はオプションのエレメントです。
3. ユーザーが認証に成功した後、 OAuth ネイティブプロバイダー > 高度なスコープチェック > オーナースコープの確認 が有効になっており、有効な URL で構成されている場合、 API Connect がコールを行い、 x-selected-scope のコンテンツがスコープ値を絞り込むことを許可します。 「所有者スコープ検査」が有効になっている場合、HTTP 応答ヘッダー x-selected-scope が存在している必要があります。存在していない場合、呼び出しは失敗します。

   

アクセス・トークンによって付与される最終スコープ許可は、項目 1、2、および 3 で説明されているフローの結果です。 図 2 に、トランザクション・フローのより詳細なビューと、 x-selected-scope が新しいスコープ値をいつ提供するかを示す例を示します。

コンシューマー 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

管理者は、コンシューマーAPIプロパティ「高度なスコープチェック」 URL を設定することで、追加のスコープチェックを有効にすることができます。次のファイル例のように、 は x-scopeValidate となります。 OpenAPI ファイルの例に示されているように、

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'

スコープ要件に対してアクセス・トークンが正常に検証されたら、以下の例のように、 x-scopeValidate エンドポイントに対して HTTP POST 要求を行います。 応答コードHTTP 200エンドポイントからの値は成功を示しています。 その他の応答コードや接続エラーは、トークンの許可エラーとして処理されます。

     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

「x-」で始まる HTTP 応答ヘッダーはすべて、コンテキスト変数 oauth.advanced-consent として保持されます。 成功した応答の例に基づいて、 X-Custom-For-Assemble-Process: audit は次のようになります。oauth.advanced-consent.x-custom-for-assemble-processこれには、アセンブル・ステップでアクセスできます。

オプションとして、検証に追加フィールドを使用できます。

要求ヘッダー

要求ヘッダーに突き合わせる正規表現を定義します。 一致するヘッダーが、拡張スコープ検証エンドポイントに対する要求に含まれます。

応答コンテキスト変数

応答ヘッダーに突き合わせる正規表現を定義します。 一致するヘッダーが、コンテキスト変数として oauth.advanced-consent.* の形式で保存されます。