使用例: スコープとクレーム

アプリケーションと API でスコープとクレームを使用する方法について説明します。

これらの例では、Authorization Code Flow を使用してユーザーを認証し、必要な権限 (スコープ) とトークンをリクエストします。リクエストパラメーターの詳細や、このフローを完全に実装する方法については、チュートリアル「Add Login to Regular Web Applications」を参照してください。

​

ユーザーを認証して標準クレームをリクエストする

この例では、ユーザーを認証し、ユーザーインターフェースをパーソナライズするためのユーザー情報を取得します。そのためには、ユーザーの名前、ニックネーム、プロフィール画像、メールアドレスの情報を含むIDトークンを取得する必要があります。

1. ユーザーを認可 URL にリダイレクトして、認証フローを開始します。

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

   • response_type パラメーターには 1 つの値が含まれます。

     • code: 通常の Web アプリケーションフローを使用しているため、最初のリクエストでは認可コードを要求します。この code を使ってトークンをリクエストすると、認証に必要な IDトークンを受け取ります。

   • scope パラメーターには 3 つの値、つまり要求する OIDC スコープが含まれます。

     • openid: アプリケーションが OIDC を使用してユーザーの本人確認を行うことを示します。
     • profile: name、nickname、picture を取得します。
     • email: email と email_verified を取得します。

2. ユーザーが同意した後 (必要な場合) 、Auth0 がアプリにリダイレクトしたら、トークンをリクエストします。

3. レスポンスから IDトークンを抽出し、デコードします。次のクレームが表示されるはずです。

   これでアプリでユーザー属性を取得し、それらを使って UI をパーソナライズできます。

​

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

この例では、カレンダー API に対してカスタムスコープを要求し、呼び出し元のアプリケーションがユーザーの予定を読み取れるように認可します。そのためには、API から予定を読み取るための適切なスコープを含むアクセストークンを取得する必要があります。なお、アクセストークンの要求は、IDトークンの要求とは無関係です。

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

1. ユーザーを認可 URL にリダイレクトして、認可フローを開始します。

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

   • response_type パラメーターには引き続き 1 つの値が含まれます。

     • code: 通常の Web アプリのフローを使用しているため、最初のリクエストでは認可コードを要求します。この code を使ってトークンを要求すると、API の呼び出しに使用できるアクセストークンを受け取ります。

   • scope パラメーターには 1 つの値、つまり要求する API のスコープが含まれます。

     • read:appointments: API からユーザーの予定を読み取れるようにします。

   • audience パラメーターは新しく、1 つの値が含まれます。

     • ユーザーの予定を読み取りたい API の一意の識別子です。

2. 前の例と同様に、ユーザーが同意すると (必要な場合) 、Auth0 はアプリにリダイレクトします。その後、トークンを要求します。

3. レスポンスからアクセストークンを取り出し、資格情報としてそのアクセストークンを使用して API を呼び出します。

​

ユーザーを認証し、標準クレームとカスタム API へのアクセスを要求する

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

• 以下を含む IDトークン:

  • ユーザーの名前
  • ニックネーム
  • プロフィール画像
  • メールアドレス情報

• API から予定を読み取るための適切なスコープを含むアクセストークン。なお、アクセストークンの要求は IDトークンの要求に依存しません。

カスタム API を使用する前に、呼び出す API で利用可能なスコープを把握しておく必要があります。カスタム API を自分で管理している場合は、アプリケーションと API の両方を Auth0 に登録し、Auth0 Dashboard を使用して API のスコープを定義する必要があります。定義済みの権限を使用して、ユーザー向けの同意プロンプトをカスタマイズすることもできます。

1. ユーザーを認可 URL に送って、認証フローを開始します。

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

   • response_type パラメーターには、引き続き 1 つの値が含まれます。

     • code: 通常の Web アプリケーションフローを使用しているため、最初のリクエストでは認可コードを要求します。この code を使用してトークンを要求すると、認証に必要な IDトークンと、API の呼び出しに使用できるアクセストークンの両方を受け取れます。

   • scope パラメーターは OIDC のスコープと API のスコープの両方に使用されるため、ここでは 4 つの値が含まれます。

     • openid: アプリケーションが OIDC を使用してユーザーの身元を検証することを示します。
     • profile: name、nickname、picture を取得するために使用します。
     • email: email と email_verified を取得するために使用します。
     • read:appointments: API からユーザーの予定を読み取れるようにします。

   • audience パラメーターには 1 つの値が含まれます。

     • ユーザーの予定を読み取る対象の API の一意の識別子

2. 前の例と同様に、ユーザーが同意した後 (必要な場合) 、Auth0 がアプリにリダイレクトしたらトークンを要求します。

3. レスポンスから IDトークンを抽出してデコードし、ユーザー属性を取得して、UI のパーソナライズに使用します。

4. レスポンスからアクセストークンを抽出し、認証情報としてそのアクセストークンを使用して API を呼び出します。

​

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

この例では、ユーザーのお気に入りの色と希望する連絡方法を IDトークン に追加します。そのために、Action を作成し、これらの クレーム を追加して IDトークン をカスタマイズします。追加後は、/userinfo エンドポイントの呼び出し時にもカスタムクレームを取得できるようになります (ただし、Action が実行されるのは認証プロセス中のみです) 。

Auth0 では名前空間付きクレームと名前空間なしクレームの両方を使用できますが、一定の制限があります (一般的な制限事項 を参照) 。名前の衝突を避けるため、名前空間付きクレームの使用を推奨します。衝突が発生してもトランザクションは失敗しませんが、カスタムクレームはトークンに追加されません。

以下を前提とします。

• ある時点で、ユーザーが preferred_contact の方法として email を、favorite_color として red を選択し、それをユーザーの user_metadata の一部として保存している。
• Management API または Dashboard を使用して、このユーザーのアプリケーション固有の情報を設定している。

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

{
  "email": "[e-mail]",
  "email_verified": true,
  "user_id": "custom|123",
  "favorite_color": "blue",
  "user_metadata": {
    "preferred_contact": "email"
  }
}

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

{
  "email": "[e-mail]",
  "email_verified": true,
  "iss": "https://my-domain.auth0.com/",
  "sub": "custom|123",
  "aud": "my_client_id",
  "iat": 1311280970,
  "exp": 1311281970
}

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

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

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

1. Auth0 Dashboard > Actions > Library に移動し、Build Custom を選択します。

2. Action のわかりやすい 名前 を入力し (例: Add user metadata to tokens) 、この Action を Login フローに追加するため、Login / Post Login トリガーを選択してから Create を選択します。

3. 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) {
       // クレームを設定
       api.idToken.setCustomClaim(`${namespace}/favorite_color`, favorite_color);
       api.idToken.setCustomClaim(`${namespace}/preferred_contact`, preferred_contact);
     }
   };
   

4. Actions Code Editor のサイドバーで Test (再生アイコン) を選択し、Run を選択してコードをテストします。

5. Action を公開する準備ができたら、Deploy を選択します。

最後に、作成した Action を Login Flow に追加します。Actions を Flow にアタッチする方法については、Write Your First Action の「Attach the Action to a flow」セクションを参照してください。

この Action を有効にすると、Auth0 は favorite_color と preferred_contact のカスタムクレームを IDトークン に含めます。

{
  "email": "[e-mail]",
  "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"
}

Action を作成する際は、追加のクレームを含める条件を判断するロジックを必ず設定してください。発行されるすべての IDトークン にカスタムクレームを挿入するのは適切ではありません。

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

トリガーの event オブジェクトについて詳しくは、Actions Triggers: post-login - Event Object を参照してください。トークンについて詳しくは、Tokens を参照してください。

​

詳細

• OpenID Connect のスコープ
• カスタムクレームを作成する
• API スコープ
• 複数の API 向けの Logical API を設定する