スコープとクレームのユースケース例

OAuth 2.0のスコープとJWTクレームが、ユーザーに代わってアプリケーションがアクセスできるデータや実行できる操作をどのように制御するかを、実践的な例を通じて学びます。

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

​

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

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

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

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

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

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

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

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

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

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

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

​

カスタム API へのアクセスをリクエストする

この例では、呼び出し元のアプリケーションがユーザーの予定を読み取れるようにするため、カレンダー API 用のカスタム scope をリクエストします。これを行うには、API から予定を読み取るために必要な scope を含む アクセストークン を取得する必要があります。なお、アクセストークンのリクエストは、ID トークンのリクエストに依存しません。

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

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

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

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

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

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

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

   • audience パラメーターは新たに追加されたもので、1 つの値を含みます。

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

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

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

​

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

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

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

  • ユーザー名
  • ニックネーム
  • プロフィール画像
  • メール情報

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

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

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

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

   • 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 の一意の識別子

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 プロパティの値が含まれています。
• favorite_color と user_metadata のプロパティはどちらも含まれていません。これは、OpenID Connect (OIDC) では、favorite_color や user_metadata を表す標準クレームが定義されていないためです。

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

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

2. Action にわかりやすい Name (たとえば Add user metadata to tokens) を入力し、Login フローに Action を追加するため、トリガーとして 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 に追加します。Action を 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 メソッドを使用します。

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

​

詳細はこちら

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