API のステップアップ認証を設定する

アクセストークンを確認して、ユーザーが MFA でログインしたかどうかを API が判定する方法を学びます。

ステップアップ認証を使用すると、さまざまな種類のリソースへのアクセスを提供するアプリケーションで、機密情報へのアクセスや特定のトランザクションの実行にあたり、より強力な認証方式をユーザーに要求できます。

たとえば、銀行アプリのユーザーが口座間で送金できるのは、多要素認証 (MFA) で本人確認を完了した後に限るようにできます。

オーディエンス が API の場合、Auth0 ではスコープ、アクセストークン、および Actions を使用してステップアップ認証を実装できます。アプリケーションが API の保護されたリソースにアクセスするには、アクセストークンを提示する必要があります。アクセスできるリソースは、アクセストークンに含まれる権限によって決まります。これらの権限は スコープ として定義されます。

​

MFA 用アクセストークンを検証する

スコープの確認に加えて、API では次の目的のためにアクセストークンを検証する必要があります。

• トークンの署名を検証して、トークンの送信者が正当な送信元であること、およびメッセージが途中で改ざんされていないことを確認します。
• 標準クレームを検証します。

クレーム	説明
exp	トークンの有効期限
iss	トークンの発行者
aud	トークンの想定受信者

​

シナリオ: プッシュ通知による銀行取引

次のシナリオでは、アプリケーションが username とパスワードでユーザーを認証し、その後、口座残高の照会を要求します。口座残高情報を取得する前に、ユーザーは Guardian のプッシュ認証要素で認証する必要があります。

銀行 API は、2 つの異なる認可レベルを受け入れることができます。口座残高の表示 (スコープ view:balance) または資金の振替 (スコープ transfer:funds) です。アプリケーションが API にユーザーの残高の取得を要求する場合、アクセストークンには view:balance スコープが含まれている必要があります。別の口座に送金するには、アクセストークンに transfer:funds スコープが含まれている必要があります。

​

ワークフロー

1. ユーザーは username とパスワード認証を使用してアプリケーションにログインします。通常のログインでは、このユーザーは API を操作して残高を取得できます。つまり、ユーザーの認証後にアプリケーションが受け取るアクセストークンには view:balance スコープが含まれます。
2. アプリケーションは、アクセストークンを認証情報として使用し、残高を取得するリクエストを API に送信します。
3. API はトークンを検証し、ユーザーが残高を表示できるよう、残高情報をアプリケーションに返します。
4. ユーザーは、ある口座から別の口座へ資金を送金しようとします。これは高額トランザクションと見なされ、transfer:funds スコープが必要です。アプリケーションは同じアクセストークンを使用して API にリクエストを送信します。
5. API はトークンを検証し、必要な transfer:funds スコープがトークンに含まれていないため、アクセスを拒否します。
6. アプリケーションは Auth0 にリダイレクトし、そこで Action を使用して、高額なスコープが要求されたためユーザーに MFA による認証を求めます。ユーザーが MFA での認証に成功すると、正しいスコープを含む新しいアクセストークンが生成され、レスポンスの一部としてアプリケーションに送信されます。
7. アプリケーションは、今度は transfer:funds スコープを含む新しいアクセストークンを使用して、再度資金送金のリクエストを送信します。
8. API はトークンを検証し、それを破棄して処理を続行します。

​

前提条件

このシナリオでは、Dashboard で以下の項目を設定する必要があります。

• シングルページ Web アプリを登録する。
• データベース接続を作成する。
• API を登録する。view:balance と transfer:funds の 2 つのスコープを作成します。
• プッシュ通知を使用するには、MFA を有効にする。

​

Action を作成する

transfer:funds スコープが要求されたときに、ユーザーに MFA での認証を求める Action を作成します。Dashboard > Actions > Flows に移動し、次の内容を含む Action を作成します。

{
exports.onExecutePostLogin = async (event, api) => {
  const CLIENTS_WITH_MFA = ['REPLACE_WITH_{yourClientId}'];
  // 指定されたクライアントに対してのみ実行する
  if (CLIENTS_WITH_MFA.includes(event.client.client_id)) {
    // スコープ transfer:funds がリクエストされた場合にのみ MFA を要求する
    if (event.transaction.requested_scopes.indexOf('transfer:funds') > -1)
      api.multifactor.enable('any', { allowRememberBrowser: false });
    }
  }
},

• CLIENTS_WITH_MFA 変数には、この Action を適用したいアプリケーションの クライアントID が含まれます。不要な場合は、これ (および後続の if 条件) を削除できます。
• event.transaction.requested_scopes プロパティには、認証リクエストで要求されたすべてのスコープが含まれます。これに transfer:funds が含まれている場合は、context.multifactor プロパティを適切な値に設定して MFA を要求します。この例では、プッシュ を使用した MFA を要求しています。

​

アプリを設定する

ユーザーが高額取引である資金振替を実行しようとしているかどうかに応じて、適切な認証リクエストをAPIに送信するようアプリを設定します。MFAありとMFAなしの2つの認証リクエストの違いは、スコープだけであることに注意してください。

• MFAあり:

  export const codeExample1 = https://{yourDomain}/authorize? audience=https://my-banking-api& scope=openid%20view:balance%20transfer:funds& response_type=id_token%20token& client_id={yourClientId}& redirect_uri={https://yourApp/callback}& nonce=NONCE& state=OPAQUE_VALUE;

• MFAなし:

  export const codeExample2 = https://{yourDomain}/authorize? audience=https://my-banking-api& scope=openid%20view:balance& response_type=id_token%20token& client_id={yourClientId}& redirect_uri={https://yourApp/callback}& nonce=NONCE& state=OPAQUE_VALUE;

パラメーター	設定
audience	APIのIdentifierに設定します (API Settingsで確認できます) 。ここでは https://my-banking-api を設定しています。
response_type	レスポンスでIDトークンとアクセストークンの両方を取得するため、id_token token に設定します。
client_id	アプリケーションのクライアントIDに設定します (Application Settingsで確認できます) 。
redirect_uri	認証後にAuth0がリダイレクトする、アプリケーション内のURLに設定します (Application Settingsで確認できます) 。
nonce	Auth0からのレスポンスに含まれる、安全な文字列値に設定します。これはトークンリプレイ攻撃の防止に使用され、response_type=id_token token では必須です。
state	アプリケーションへのリダイレクト時にAuth0が含める不透明な値に設定します。この値は、アプリケーションがCSRF攻撃を防ぐために使用する必要があります。

​

API を設定する

受信したトークンを検証し、許可された権限を確認するように API を設定します。

1. API に 2 つのエンドポイントを設定します。 GET /balance: 現在の残高を取得する POST /transfer: 資金を送金する

2. Node.js といくつかのモジュールを使用します。

   1. express: Express Web アプリケーションフレームワークを追加します。
   2. jwks-rsa: JWKS (JSON Web Key Set) エンドポイントから RSA 署名キーを取得します。expressJwtSecret を使用すると、JWT ヘッダー内の kid に基づいて適切な署名キーを express-jwt に提供するシークレットプロバイダーを生成できます。
   3. express-jwt: Node.js アプリケーションで JWT を使用して HTTP リクエストを認証できます。JWT を扱いやすくするための複数の関数が用意されています。
   4. express-jwt-authz: アクセストークンに特定のスコープが含まれているかどうかを確認します。

3. 依存関係をインストールします。 npm install express express-jwt jwks-rsa express-jwt-authz --save

4. API エンドポイントを定義し、アクセストークンを検証するミドルウェア関数を作成して、そのミドルウェアでエンドポイントを保護します。server.js ファイルのコードは、次のサンプルスクリプトのようになります。

API がリクエストを受信するたびに、次の処理が実行されます。

1. エンドポイントが checkJwt ミドルウェアを呼び出します。 2. express-jwt がトークンをデコードし、リクエスト、ヘッダー、ペイロードを jwksRsa.expressJwtSecret に渡します。 3. jwks-rsa が JWKS エンドポイントからすべての署名鍵をダウンロードし、それらのいずれかがアクセストークンのヘッダー内の kid と一致するかを確認します。一致する署名鍵がない場合はエラーがスローされます。一致するものがある場合は、適切な署名鍵を express-jwt に渡します。 4. express-jwt は続いて、独自のロジックに従ってトークンの署名、有効期限、オーディエンス、発行者を検証します。 5. jwtAuthz は、エンドポイントが必要とするスコープがアクセストークンに含まれているかどうかを確認します。指定されたスコープがアクセストークンに含まれていない場合、リクエストは 403 エラーで拒否されます。

​

詳細情報

• アクセストークン
• アクセストークンを検証する
• Actions のユースケース
• API のスコープ
• Web アプリ向けのステップアップ認証を設定する