「サンプルユースケース」の「スコープとクレーム」

以下の例では、認可コードフローを使ってユーザーを認証し、必要な権限（スコープ）とトークンを要求します。要求パラメーターおよびこのフローの完全実装の詳細については、チュートリアル「ログインを通常のWebアプリケーションに追加する」をお読みください。

ユーザーを認可して標準クレームを要求する

この例では、ユーザーを認証し、ユーザーインターフェイスをパーソナライズできるようにユーザー詳細を取得したいとします。このためには、ユーザー名、ニックネーム、プロフィール画像、およびメール情報を含んだIDトークンが必要です。

ユーザーに認証URLを送信して、認可フローを開始します。
```
https://{yourDomain}/authorize?
  response_type=code&
  client_id={yourClientId}&
  redirect_uri={https://yourApp/callback}&
  scope=openid%20profile%20email&
  state=YOUR_STATE_VALUE
```
Was this helpful?
/
この例では、以下の点に注意してください。
- response_typeパラメーターには1つの値が含まれます。
  - code：標準のWebアプリケーションを使用しているため、最初に認証コードに対する要求が行われます。このコードを使ってトークンを要求すると、認証に必要なIDトークンが送られてきます。
- scopeパラメーターには、3つの値（要求されたOIDCスコープ）が含まれます。
  - openid：アプリケーションがユーザーの身元検証にOIDCを使用することを伝えるため
  - profile：name、nickname、およびpictureを取得するため
  - email：emailとemail_verifiedを取得するため
ユーザーが同意し（必要な場合）、Auth0がアプリにリダイレクトした後、トークンを要求します。
応答からIDトークンを抽出し、解読します。次のクレームが表示されます。
```
{
  "name": "John Doe",
  "nickname": "john.doe",
  "picture": "https://myawesomeavatar.com/avatar.png",
  "updated_at": "2017-03-30T15:13:40.474Z",
  "email": "john.doe@test.com",
  "email_verified": false,
  "iss": "https://{yourDomain}/",
  "sub": "auth0|USER-ID",
  "aud": "{yourClientId}",
  "exp": 1490922820,
  "iat": 1490886820,
  "nonce": "crypto-value",
  "at_hash": "IoS3ZGppJKUn3Bta_LgE2A"
}
```
Was this helpful?
/
アプリはユーザー属性を取得し、この属性を使ってUIをパーソナライズできるようになります。

カスタムAPIへのアクセスを要求する

以下の例では、呼び出す側のアプリケーションがユーザーの予定を読み取れるようにするカレンダーAPIのカスタムスコープを要求します。このため、APIから予定を読み取るための適切なスコープを含んだアクセストークンを取得します。アクセストークンの要求は、IDトークンの要求に依存することはありません。

カスタムAPIを使用する前に、呼び出すAPIで使用できるスコープを知っておく必要があります。カスタムAPIを管理できる場合、Auth0を使ってアプリケーションとAPIの両方を登録し、Auth0 DashboardでAPIのスコープを定義する必要があります。定義された権限を使って、ユーザーの同意プロンプトをカスタマイズすることもできます。

ユーザーに認証URLを送信して、認可フローを開始します。
```
https://{yourDomain}/authorize?
  response_type=code&
  client_id={yourClientId}&
  redirect_uri={https://yourApp/callback}& 
  scope=read:appointments&
  audience=YOUR_API_AUDIENCE&
  state=YOUR_STATE_VALUE
```
Was this helpful?
/
この例では、以下の点に注意してください。
- response_typeパラメーターには1つの値が含まれたままです。
  - code：標準のWebアプリケーションを使用しているため、最初に認証コードに対する要求が行われます。このコードを使ってトークンを要求すると、APIの呼び出しに使用できるアクセストークンが送られてきます。
- scopeパラメーターには、1つの値（要求されたAPIスコープ）が含まれます。
  - read:appointments：APIからユーザーの予定を読み取れるようにするため
- audienceパラメーターは新しいパラメーターで、1つの値が含まれます。
  - APIの一意識別子で、ここからユーザーの予定を読み取ります。
前の例にあるように、ユーザーが同意し（必要な場合）、Auth0がアプリにリダイレクトした後、トークンを要求します。
応答からアクセストークンを抽出し、アクセストークンを資格情報に使ってAPIを呼び出します。

ユーザーを認可し、標準クレームとカスタムAPIアクセスを要求します。

この例では、前の2つの例を組み合わせて、ユーザーの認可と標準クレームの要求を行うほか、呼び出す側のアプリケーションがユーザーの予定を読み取れるようにするカレンダーAPIのカスタムスコープも要求します。このために、2つのトークンを取得します。

IDトークンに含まれるもの：
- ユーザー名
- Nickname（ニックネーム）
- プロファイル画像
- メール情報
適切なスコープを含むトークンにアクセスし、APIから予定を読み取ります。アクセストークンの要求は、IDトークンの要求に依存することはありません。

ユーザーに認証URLを送信して、認可フローを開始します。
```
https://{yourDomain}/authorize?
  response_type=code&
  client_id={yourClientId}&
  redirect_uri={https://yourApp/callback}& 
  scope=openid%20profile%20email%20read:appointments&
  audience=YOUR_API_AUDIENCE&
  state=YOUR_STATE_VALUE
```
Was this helpful?
/
この例では、以下の点に注意してください。
- response_typeパラメーターには1つの値が含まれたままです。
  - code：標準のWebアプリケーションを使用しているため、最初に認証コードに対する要求が行われます。このコードを使ってトークンを要求すると、認証に必要なIDトークンとAPIの呼び出しに使用できるアクセストークンの両方が送られてきます。
- scopeパラメーターはOIDCスコープとAPIスコープの両方に使用されるため、4つの値が含まれるようになりました。
  - openid：アプリケーションがユーザーの身元検証にOIDCを使用することを伝えるため
  - profile：name、nickname、およびpictureを取得するため
  - email：emailとemail_verifiedを取得するため
  - read:appointments：APIからユーザーの予定を読み取れるようにするため
- audienceパラメーターには1つの値が含まれます。
  - APIの一意識別子で、ここからユーザーの予定を読み取ります。
前の例にあるように、ユーザーが同意し（必要な場合）、Auth0がアプリにリダイレクトした後、トークンを要求します。
応答からIDトークンを抽出、解読し、ユーザー属性を取得し、その属性を使ってUIをパーソナライズします。
応答からアクセストークンを抽出し、アクセストークンを資格情報に使ってAPIを呼び出します。

カスタムクレームをトークンに追加する

以下の例では、ユーザーのお気に入りの色と使用する連絡先方法をIDトークンに追加します。このためには、これらのクレームを追加することで、アクションを作成し、IDトークンをカスタマイズします。追加すると、/userinfoエンドポイントを呼び出すときに、カスタムクレームを取得することもできます（ただし、Actionは認可プロセス中のみ実行されます）。

Auth0では、名前空間を指定したクレームと名前空間を指定しないクレームが使用できますが、特定の制限があります（「一般的な制限」を参照してください）。名前の衝突を避けるために、名前空間を指定したクレームの使用をお勧めします。衝突が生じた場合、トランザクションは失敗しませんが、カスタムクレームがトークンに追加されません。

以下のように仮定します。

ユーザーがpreferred_contactメソッドにemail、favorite_colorにredをぞれぞれ選択し、ユーザーのuser_metadataの一部として保存しました。
Management APIまたはDashboardを使用して、このユーザーのアプリケーション固有情報を設定しました。

この場合、Auth0に保存されている正規化ユーザープロファイルは以下のとおりです。

{
  "email": "jane@example.com",
  "email_verified": true,
  "user_id": "custom|123",
  "favorite_color": "blue",
  "user_metadata": {
    "preferred_contact": "email"
  }
}

Was this helpful?

このプロファイルでは、Auth0は通常、以下のIDトークンのクレームをアプリケーションに返します。

{
  "email": "jane@example.com",
  "email_verified": true,
  "iss": "https://my-domain.auth0.com/",
  "sub": "custom|123",
  "aud": "my_client_id",
  "iat": 1311280970,
  "exp": 1311281970
}

Was this helpful?

この例では、以下の点に注意してください。

subクレームには、user_idプロパティの値が含まれます。
favorite_colorプロパティもuser_metadataプロパティも存在しません。これは、OpenID Connect (OIDC)がfavorite_colorまたはuser_metadataを表す標準クレームを定義しないためです。

カスタムデータを受け取るには、新しいアクションを作成し、ユーザープロファイルからのプロパティを表すカスタムクレームを使ってトークンをカスタマイズする必要があります。

［Auth0 Dashboard］>［Actions（アクション）］>［Library（ライブラリ）］に移動し、［Build Custom（カスタムビルド）］を選択します。
アクションにわかりやすい名前を入力し（たとえば、「ユーザーメタデータをトークンに追加する」）、［Login / Post Login（ログイン/ログイン後）］トリガーを選択し（アクションをログインフローに追加することになるため）、［Create（作成）］を選択します。
Actions Code Editor（アクションコードエディター）を検索し、以下のJavaScriptコードをコピーし、［Save Draft（下書きを保存）］を選択して内容を保存します。
```
exports.onExecutePostLogin = async (event, api) => {
  const namespace = 'https://myapp.example.com';
  const { favorite_color, preferred_contact } = event.user.user_metadata;

  if (event.authorization) {
    // Set claims 
    api.idToken.setCustomClaim(`${namespace}/favorite_color`, favorite_color);
    api.idToken.setCustomClaim(`${namespace}/preferred_contact`, preferred_contact);
  }
};
```
Was this helpful?
/
［Actions Code Editor（アクションコードエディター）］サイドバーから、［Test（テスト）］（再生アイコン）、［Run（実行）］の順にクリックし、コードをテストします。
アクションを稼働する準備ができたら、［Deploy（導入）］を選択します。

そして、作成したアクションを［Login Flow（ログインフロー）］に追加します。アクションをフローにアタッチする方法については、初めてアクションを作成するの「アクションをフローにアタッチする」セクションをお読みください。

このアクションが有効な場合、Auth0では、IDトークンにfavorite_colorおよびpreferred_contactのカスタムクレームが含まれます。

{
  "email": "jane@example.com",
  "email_verified": true,
  "iss": "https://my-domain.auth0.com/",
  "sub": "custom|123",
  "aud": "my_client_id",
  "iat": 1311280970,
  "exp": 1311281970,
  "https://myapp.example.com/favorite_color": "red",
  "https://myapp.example.com/preferred_contact": "email"
}

Was this helpful?

アクションを作成する場合、追加のクレームを含めるタイミングを決める何らかのロジックを必ず設定してください。カスタムクレームを発行されている各IDトークンに注入することは推奨しません。

この例では、カスタムクレームがapi.idToken.setCustomClaimsメソッドを使用するIDトークンに追加されています。これらのクレームをアクセストークンに追加するには、api.accessToken.setCustomClaimメソッドを使用します。

トリガーのイベントオブジェクトの詳細については、「Actionトリガー：post-login - eventオブジェクト」をお読みください。トークンの詳細については、「トークン」をお読みください。

はじめに

「サンプルユースケース」の「スコープとクレーム」

ユーザーを認可して標準クレームを要求する

カスタムAPIへのアクセスを要求する

ユーザーを認可し、標準クレームとカスタムAPIアクセスを要求します。

カスタムクレームをトークンに追加する

もっと詳しく