> ## Documentation Index
> Fetch the complete documentation index at: https://developers.authlete.com/llms.txt
> Use this file to discover all available pages before exploring further.

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

> Authleteの「パラメーター化されたスコープ」機能の利用方法について解説。

## はじめに

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

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

***

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

「パラメーター化されたスコープ」は、通常の固定文字列のスコープに対して特別なスコープ属性を設定することで利用できます。設定は以下の手順で行います。1. スコープ属性の設定画面を開きます。（詳細な手順は「[スコープ属性](/ja/configuration-reference/tokens-and-claims/scope-attributes)
」をご覧ください。）2. 「属性のキー」に、 "regex"（「パラメーター化されたスコープ」を示す固定値）を指定します。3. 「属性の値」に、可変値を含むスコープ文字列にマッチする正規表現を指定します。

以下の例では、"consent" スコープに対し、可変値を含むスコープ文字列にマッチする正規表現として "^consent:.\*\$" を指定しています。この場合 Authlete は、"consent" スコープだけではなく、"consent:urn:bancoex:C1DD33123" のような、スコープ属性として設定した正規表現にマッチする値も、有効なスコープとして受け入れます。

<img src="https://mintcdn.com/authlete/WGQFc11Y4wUplGrc/img/kb/ja/oauth-and-openid-connect/scopes/parameterized-scopes_1.png?fit=max&auto=format&n=WGQFc11Y4wUplGrc&q=85&s=d093e9522b3d889d0f81227be4454779" alt="parameterized-scopes_1" width="881" height="282" data-path="img/kb/ja/oauth-and-openid-connect/scopes/parameterized-scopes_1.png" />

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

***

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

### 認可リクエスト

認可リクエストの "scope" パラメーターに「パラメーター化されたスコープ」が含まれている場合の、Authlete の [/auth/authorization API](https://docs.authlete.com/#authorization-endpoint)
のリクエスト・レスポンスの例を以下に示します。

* リクエスト

```
$ 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](https://docs.authlete.com/#introspection-endpoint)
のリクエスト・レスポンスの例です。

* リクエスト

```
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](https://docs.authlete.com/#introspection-endpoint)
を利用したトークンが持つスコープの確認の詳細については「[アクセストークンがカバーするスコープの確認](/ja/configuration-reference/endpoints/checking-if-an-access-token-has-particular-scopes)
」をご覧ください。

***

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

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

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

***

## 参考

* [DynamicScope](http://authlete.github.io/authlete-java-common/com/authlete/common/dto/DynamicScope.html)
  クラス （authlete-java-common ライブラリ）