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

はじめに

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

本機能は Authlete 2.2 以降でのみ利用可能になります。

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

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

parameterized-scopes_1

“consent” スコープに「パラメーター化されたスコープ」の設定を行う例

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

認可リクエスト

認可リクエストの “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 ライブラリ）

スコープ属性カスタムスコープの言語別説明文の登録