「パラメーター化されたスコープ」の利用

はじめに


Authlete の「パラメーター化されたスコープ (parameterized scopes)」機能を利用すると、スコープ文字列の一部を可変にできます。本記事では「パラメーター化されたスコープ」を利用する方法について説明します。



パラメーター化されたスコープの定義方法


「パラメーター化されたスコープ」は、通常の固定文字列のスコープに対して特別なスコープ属性を設定することで利用できます。設定は以下の手順で行います。
  1. スコープ属性の設定画面を開きます。（詳細な手順は「スコープ属性」をご覧ください。）
  2. 「属性のキー」に、 "regex"（「パラメーター化されたスコープ」を示す固定値）を指定します。
  3. 「属性の値」に、可変値を含むスコープ文字列にマッチする正規表現を指定します。
以下の例では、"consent" スコープに対し、可変値を含むスコープ文字列にマッチする正規表現として "^consent:.*$" を指定しています。この場合 Authlete は、"consent" スコープだけではなく、"consent:urn:bancoex:C1DD33123" のような、スコープ属性として設定した正規表現にマッチする値も、有効なスコープとして受け入れます。



「パラメーター化されたスコープ」の利用例


認可リクエスト


認可リクエストの "scope" パラメーターに「パラメーター化されたスコープ」が含まれている場合の、Authlete の /auth/authorization API のリクエスト・レスポンスの例を以下に示します。

  • リクエスト
$ curl -s -X POST https://api.authlete.com/api/auth/authorization \
 -u ...:... \
 -H 'Content-type: application/json' \
 -d '{"parameters":
  "redirect_uri=...
   &client_id=...
   &response_type=code
   &scope=email+consent:urn:bancoex:C1DD33123"}'
  • レスポンス
{
  "type": "authorizationResponse",
  "resultCode": "A004001",
  "resultMessage":
    "[A004001] Authlete has successfully issued a ticket
     to the service (API Key = 2407...) for the 
     authorization request from the client (ID = 2614...). 
     [response_type=code, openid=false]",
  "action": "INTERACTION",
  "dynamicScopes": [
    {
      "name": "consent",
      "value": "consent:urn:bancoex:C1DD33123"
    }
  ],
  "scopes": [
    {
      "defaultEntry": false,
      "description": "A permission to request an OpenID Provider to include the email claim and the email_verified claim in an ID Token. See OpenID Connect Core 1.0, 5.4. for details.",
      ...
      "name": "email"
    }
  ],
...

スコープ属性の "value" に設定されている正規表現にマッチしたスコープは、レスポンスの "dynamicScopes" 配列に含まれます。この配列の、"name" フィールドにはスコープ名が、"value" フィールドには実際に "scope" リクエストパラメーターで指定されたスコープ文字列が、それぞれ設定されます。

イントロスペクション


アクセストークンが特定の「パラメーター化されたスコープ」を持つかどうかは、固定文字列のスコープの場合と同様の方法により確認できます。以下は Authlete の /auth/introspection API のリクエスト・レスポンスの例です。
  • リクエスト
curl -s -X POST .../auth/introspection \
 -u ...:... \
 -H 'Content-type: application/json' \
 -d '{"token":"L2sOx9...","scopes":["email","consent:urn:bancoex:C1DD33123"]}'
  • レスポンス
{
  "type": "introspectionResponse",
  "resultCode": "A056001",
  "resultMessage": "[A056001] The access token is valid.",
  "action": "OK",
  "clientId": ...,
  "expiresAt": ...,
  "responseContent": "Bearer error=\"invalid_request\"",
  "scopes": [
    "email",
    "consent:urn:bancoex:C1DD33123"
  ],
  "subject": "testuser01",
  ...
}

/auth/introspection API を利用したトークンが持つスコープの確認の詳細については「アクセストークンがカバーするスコープの確認」をご覧ください。


ディスカバリードキュメントの表示


「パラメーター化されたスコープ」は、ディスカバリードキュメントにおいてはスコープ名のみ表示されます。以下は Authlete の /service/configuration API のレスポンスの例です。

{
  "issuer": "...",
  "authorization_endpoint": "...",
  "token_endpoint": "...",
  "userinfo_endpoint": "...",
  "jwks_uri": "...",
  "scopes_supported": [
    "address",
    "email",
    "openid",
    "offline_access",
    "phone",
    "profile",
    "consent"
  ],
  ...
}


参考


  • DynamicScope クラス （authlete-java-common ライブラリ）
How did we do with this article?