Power Pages サイトで OAuth 2.0 の暗黙的な許可フローを使用する

2024-08-27

この機能により、顧客はクライアント側で外部 API を呼び出して、OAuth の暗黙的な許可フローを使用してそれらを保護できます。エンドポイントを提供して安全な ID トークンを取得します。これらのトークンには、OAuth 2.0 の暗黙的な許可フローに続く、承認のために外部 API によって使用されるユーザー ID 情報が含まれます。サインインしたユーザーの ID 情報は、安全な方法で外部 AJAX 呼び出しに渡されます。これは、開発者が認証コンテキストを渡すのに役立ち、ユーザーが API を保護するのにも役立ちます。

カスタム証明書

Power Platform 管理センターを使用して、カスタム証明書をアップロードします。カスタム証明書をアップロードした後、以下のようにサイト設定を更新する必要があります。

ポータル管理アプリの Web サイト セクションで、サイト設定を選択します。
新しい設定を作成する場合、新規を選択します。
既存設定を編集する場合は、CustomCertificates/ImplicitGrantflowを選択します。
値の指定:
- 名前: CustomCertificates/ImplicitGrantflow
- Web サイト: 関連する Web サイト
- 値: アップロードされたカスタム証明書のサムプリントを、カスタム証明書の管理画面からコピーしてここに貼り付けます。この値は、暗黙的な許可フローに使用される証明書を示します。
保存して閉じる を選択します。

トークンエンドポイントの詳細

また、<portal_url>/_services/auth/token エンドポイントに POST 要求することで、トークンを取得することもできます。トークンエンドポイントは次のパラメーターをサポートします:

パラメーター	必須?	説明
client_id	いいえ	承認エンドポイントへの呼び出し時に渡される文字列。クライアント ID は登録されている必要があります。そうでない場合はエラーが表示されます。クライアント ID はトークンのクレームに `aud` や `appid` パラメータとして追加され、返されたトークンが自分のアプリ用であることを検証するためにクライアントが使用できます。最大長は 36 文字です。英数字とハイフンのみがサポートされます。
州	いいえ	トークン応答にも返される要求に含まれる値。使用したいどんなコンテンツの文字列でも構いません。通常はランダムに生成された一意の値が、クロスサイトリクエストフォージェリ攻撃を防ぐために使用されます。最大長は 20 文字です。
その場合	いいえ	クライアントから送信された文字列値で、結果の ID トークンに要求として含まれます。そしてクライアントはこの値を検証してトークンリプレイ攻撃を軽減できます。最大 20 文字までです。
response_type	いいえ	このパラメーターは、`token` のみを値としてサポートし、エンドポイントに 2 回目の要求を作成せずに、アプリがすぐにエンドポイントから ID トークンを取得できるようになります。

注意

client_id、state、nonce パラメータはオプションですが、統合の安全を確実にするために使用することをお勧めします。

正常な応答

トークンエンドポイントは状態と expires_in を応答ヘッダーとして返し、トークンをフォームの本文に返します。

エラー応答

トークンエンドポイントのエラーは、次の値の JSON ドキュメントとして返されます:

エラー ID: エラーの一意の識別子です。
エラーメッセージ: 認証エラーの根本原因を特定するのに役立つ特定のエラーメッセージ。
関連付け ID: デバッグ目的に使用される GUID。診断ログを有効にすると、関連付け ID はサーバーエラーログに表示されます。
Timestamp: エラーが発生した日時。

エラーメッセージはサインインしたユーザーの既定言語で表示されます。ユーザーがサインインしていない場合は、ユーザーにサインインを促すサインインページが表示されます。たとえば、エラー応答は次のようになります:

{"ErrorId": "PortalSTS0001", "ErrorMessage": "Client Id provided in the request is not a valid client Id registered for this portal. Please check the parameter and try again.", "Timestamp": "4/5/2019 10:02:11 AM", "CorrelationId": "aaaa0000-bb11-2222-33cc-444444dddddd" }

ID トークンの検証

ID トークンを取得するだけではユーザーの認証に十分ではありません; トークンの署名を検証し、アプリの要件に基づいてトークン内の要求を確認する必要もあります。公開トークンエンドポイントはサイトの公開鍵を提供し、それを Web サイトが提供したトークンの署名を検証するために使用できます。公開トークンエンドポイントの URL は: <portal_url>/_services/auth/publickey。

暗黙的な許可フローをオンまたはオフにする

既定で、暗黙的な許可フローは有効です。暗黙的な許可フローをオフにしたい場合は Connector/ImplicitGrantFlowEnabled サイト設定の値を False にします。

このサイト設定が Web サイトで利用できない場合は、適切な値で新しいサイト設定を作成する必要があります。

トークンの有効性を構成する

既定では、トークンは15分間有効です。トークンの有効性を変更する場合は ImplicitGrantFlow/TokenExpirationTime サイト設定の値を必要な値に設定してください。値は秒単位で指定する必要があります。最大値で 1 時間が可能で、最小値は 1 分にする必要があります。不正な値 (たとえば英数字) が指定されると、既定値の 15 分が使用されます。最大値より大きい値や最小値より小さい値を指定した場合、既定では最大値と最小値がそれぞれ使用されます。

たとえばトークンの有効期間を 30 分に設定するには ImplicitGrantFlow/TokenExpirationTime サイト設定の値を 1800 にします。トークンの有効期間を 1 時間に設定するには ImplicitGrantFlow/TokenExpirationTime サイト設定の値を 3600 にします。

暗黙的な許可フローにクライアント ID を登録する

このフローが許可された Web サイトにクライアント ID を登録する必要があります。クライアント ID を登録するには、次のサイト設定を作成する必要があります:

サイト設定	Value
ImplicitGrantFlow/RegisteredClientId	このサイトで許可されている有効なクライアント ID 値。値はセミコロンで区切る必要があり、英数字とハイフンを使用できます。最大長は 36 文字です。

サンプルコード

以下のサンプルコードを使用することで、Power Pages API で OAuth 2.0 の暗黙的な許可を利用することができます。

外部Web API で Power Pages OAuth トークンを使用する

このサンプルは、ASP.NET ベースのプロジェクトで、Power Pages が発行する ID トークンの検証に使用されます。完全なサンプルは、外部 Web API で Power Pages OAuth トークンを使用するで確認することができます。

トークンエンドポイントのサンプル

このサンプルは、getAuthenticationToken 関数と Power Pages のトークンエンドポイントを使用した ID トークンをフェッチする方法を示しています。このサンプルは、トークンエンドポイントのサンプルで確認することができます。

次の方法で共有