API 付与タイプのアクセス・ポリシー

アクセス・ポリシーを適用すると、以下の基本的なビジネス要件が対処されます。

• このアプリケーションにアクセスするためのユーザー認証は十分であったか。
• 認証されたユーザーはこのアプリケーションにアクセスできるか。
• このアプリケーションにアクセスするために使用されるデバイスまたはクライアント・コンテキストは許可されているか。

従来のブラウザー・フローでは、これらの要件が適用されます。 要件が満たされていなければ、ブラウザーが MFA を求めるプロンプトを出すか、ユーザーにエラー・ページを表示してアクセスを停止します。 API 付与タイプでは、こうした機能がすべて提供されるわけではありません。 そのため、以下の問題に対応する必要があります。

• クライアント・デバイスからコンテキストを受け取る。
• MFA チャレンジを返す。これには以下が含まれます。
  • MFA を実行するために必要な API。
  • それらの API にアクセスする方法。

policyauth 付与タイプ

API 専用の OAuth 2.0 フローにアクセス・ポリシーを効果的に適用するために、新しい付与タイプが導入されました。 この付与タイプでは、クライアントが認証の前にアクセス・ポリシーにコンテキストを提示できます。 この機能により、ユーザー・エクスペリエンスを向上させることができます。 例えば、ユーザーがログイン・ボタンを押すと、資格情報の入力を求めるプロンプトが出される前に、関連するポリシーに従ってユーザーが評価されます。 ユーザーがポリシー要件を満たしていない場合は、ポリシー要件が理由でユーザーを認証できないかリソースにアクセスできないことを通知するエラー・メッセージが表示されます。

/token からの MFA チャレンジ応答

API OAuth 2.0 フローにアクセス・ポリシーを適用する場合は、MFA のチャレンジを API 規約に組み込む必要があります。 従来の方法のように、/authorize への要求の一環として OP で MFA ステップを実行することはできません。

/token から MFA チャレンジが返された場合は、以下の動作が行われます。

• スコープが mfa_challenge になり、それ以外のスコープは返されません。
• アクセス・トークンが発行されます。
  • このアクセス・トークンには、必要な認証 API にアクセスする資格が付与されます。 通常の API クライアント・アクセス・トークンではなく、このアクセス・トークンが使用される点が重要です。 このトークンを使用して、既に実行された認証要素と過去のアクションが付与全体で追跡されます。
  • アクセス・トークンにより、要求からの active: true が /introspect に返されます。 リソース・サーバーを保護する API は、MFA チャレンジが使用されるときに、/introspect から返された scope が mfa_challenge と等しくないことを検査する必要があります。
• オプションで、このチャレンジの allowedFactors を満たすために実行できる一連の要素がリストされます。

/token へのコンテキストの提示

/token への要求を実行する API クライアントは、アクセス・ポリシーの評価で使用される明確に定義された任意のコンテキスト情報を /token に提示できます。

必要なコンテキスト情報は以下の 3 つです。

• sessionId - OAuth クライアントが発行して管理する任意のセッション ID。
• ipAddress - OAuth クライアントにはユーザー・エージェントと対話する役割があるため、ユーザーの IP アドレスを明示的に提供する必要があります。
• userAgent - IP アドレスと同様に、ユーザーのユーザー・エージェントを明示的に提供する必要があります。

パラメーターをさらに追加し、その値に対してコンテキスト属性の条件を作成することができます。

コンテキストは、Base64 エンコードされた JSON の形式で /token に提供されます。 コンテキストの JSON ペイロードの例を以下に示します。

{
    "sessionId":"MDNjZmQ3NDM2NjFmMDc5NzVmYTJmMT",
    "ipAddress":"129.42.38.10",
    "userAgent":"Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/83.0.4103.116 Safari/537.36"
}

コンテキスト情報は、セキュアなクライアント資格情報が発行された API クライアントから提示されるため、信頼できると見なされます。 その API クライアントは、使用元のユーザー・エージェントが任意にコンテキストを提示できないようにする必要があります (コンテキストがビジネス制御を免れるために使用される可能性があります)。

すべてのAPIグラントタイプ（、 ROPCJWT BearerpolicyAuth 、、 refresh token）において、アクセスポリシーが呼び出される際は、必ずコンテキストを提示する必要があります。

mfa_challenge への対応

/token エンドポイントから返された MFA チャレンジに対応するには、認証要素 API を使用します。 この API は、第 1 要素と第 2 要素の両方の要件を満たすために使用されます。 該当する要素を要求するために、mfa_challenge 応答で返されたアクセス・トークンが使用されます。 要素が完了すると、JWT が返されます。 この JWT には、いくつかの重要な情報が含まれています。

• 要素 API を要求するために使用されたアクセス・トークンから導出される grant_id。 この ID によって、/token に対する複数の要求間の相関が維持されます。
• 実施された内容 factor および以前に実施された要因。

この JWT は、jwtBearer 付与タイプ・フローの一環として /token に提示されます。 アクセス・ポリシーが再評価され、十分な資格があるトークンまたは新たなチャレンジが発行されます。

各種付与タイプへのアクセス・ポリシーの適用

アプリケーションを構成するときに、特定の付与タイプにアクセス・ポリシーを適用するかどうかを選択できます。

この構成により、grant_type パラメーターの値に基づく /token への要求でアクセス・ポリシーが評価されるかどうかが制御されます。 この評価は、事前に特定の付与で /token が呼び出されたかどうかに関係なく適用されます。