ポータル内で OAuth 2.0 の暗黙的な許可フローを使用する
注意
2022 年 10 月 12 日より、Power Apps ポータルは Power Pages となります。 詳細: Microsoft Power Pages の一般提供が開始されました (ブログ)
Power Apps ポータルのドキュメントは、近日中に Power Pages ドキュメントに移行、統合されます。
この機能により、顧客はクライアント側で外部 API を呼び出して、OAuth の暗黙的な許可フローを使用してそれらを保護できます。 安全なアクセス トークンを取得するためのエンドポイントを提供します。 これらのトークンには、OAuth 2.0 の暗黙的な許可フローに続く、承認のために外部 API によって使用されるユーザー ID 情報が含まれます。 サインインしたユーザーの ID 情報は、安全な方法で外部 AJAX 呼び出しに渡されます。これは、開発者が認証コンテキストを渡すのに役立ち、ユーザーが API を保護するのにも役立ちます。
OAuth 2.0 の暗黙的な許可フローは、クライアントが ID トークンを取得するために呼び出せるトークン エンドポイントをサポートします。
カスタム証明書
OAuth 2.0 の暗黙的な許可フローの既定の証明書の使用は非推奨です。 OAuth 2.0 エンドポイントを使用している間は、カスタム証明書を使用する必要があります。 Power Platform 管理センターを使用して、カスタム証明書をアップロードします。 カスタム証明書をアップロードした後、以下のようにサイト設定を更新する必要があります。
ポータル設定 に移動し、 サイト設定を選択します。
新しい設定を作成する場合、 新規を選択します。
既存の設定を編集する場合は、グリッドに表示されたサイト設定を選択します。
値の指定:
- 名前: CustomCertificates/ImplicitGrantflow
- Web サイト: 関連する Web サイト
- 値: アップロードされたカスタム証明書のサムプリントを、カスタム証明書の管理画面からコピーしてここに貼り付けます。 この値は、暗黙的な許可フローに使用される証明書を示します。
保存して閉じるを選択します。
トークン エンドポイントの詳細
また、/token エンドポイントに POST 要求することで、トークンを取得することもできます。 トークン エンドポイントの URL は: <portal_url>/_services/auth/token です。 トークン エンドポイントは次のパラメーターをサポートします:
| パラメーター | 必須? | 説明 |
|---|---|---|
| client_id | 無効 | 承認エンドポイントへの呼び出し時に渡される文字列。 クライアント ID は ポータルに登録されている 必要があります。 そうでない場合はエラーが表示されます。 クライアント ID はトークンのクレームに aud や appid パラメータとして追加され、返されたトークンが自分のアプリ用であることを検証するためにクライアントが使用できます。最大長は 36 文字です。 英数字とハイフンのみがサポートされます。 |
| redirect_uri | 無効 | 認証応答を送受信できるポータルの URL。 コールで使用された特定の client_id に登録される必要があり、そして登録されたものと全く同じ値である必要があります。 |
| 状態 | 無効 | トークン応答にも返される要求に含まれる値。 使用したいどんなコンテンツの文字列でも構いません。 通常はランダムに生成された一意の値が、クロスサイト リクエスト フォージェリ攻撃を防ぐために使用されます。 最大長は 20 文字です。 |
| その場合 | 無効 | クライアントから送信された文字列値で、結果の ID トークンに要求として含まれます。 そしてクライアントはこの値を検証してトークンリプレイ攻撃を軽減できます。 最大 20 文字までです。 |
| response_type | 無効 | このパラメーターは、値として token のみをサポートしており、アプリが承認エンドポイントに 2 度目の要求を行うことなく、承認エンドポイントからアクセス トークンをすぐに受信できるようにします。 |
注意
client_id、redirect_uri、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": "7464eb01-71ab-44bc-93a1-f221479be847" }
承認エンドポイントの詳細
注意
承認エンドポイントは非推奨です。 トークン エンドポイント POST リクエストを使用して ID トークンを取得します。]
承認エンドポイントの URL は: <portal_url>/_services/auth/authorize です。 承認エンドポイントは次のパラメーターをサポートします:
| パラメーター | 必須? | 説明 |
|---|---|---|
| client_id | あり | 承認エンドポイントへの呼び出し時に渡される文字列。 クライアント ID は ポータルに登録されている 必要があります。 そうでない場合はエラーが表示されます。 クライアント ID はトークンのクレームに aud や appid パラメータとして追加され、返されたトークンが自分のアプリ用であることを検証するためにクライアントが使用できます。最大長は 36 文字です。 英数字とハイフンのみがサポートされます。 |
| redirect_uri | あり | 認証応答を送受信できるポータルの URL。 コールで使用された特定の client_id に登録される必要があり、そして登録されたものと全く同じ値である必要があります。 |
| 状態 | 無効 | トークン応答にも返される要求に含まれる値。 使用したいどんなコンテンツの文字列でも構いません。 通常はランダムに生成された一意の値が、クロスサイト リクエスト フォージェリ攻撃を防ぐために使用されます。 最大長は 20 文字です。 |
| その場合 | 無効 | クライアントから送信された文字列値で、結果の ID トークンに要求として含まれます。 そしてクライアントはこの値を検証してトークンリプレイ攻撃を軽減できます。 最大 20 文字までです。 |
| response_type | 無効 | このパラメーターは、値として token のみをサポートしており、それによりアプリは承認エンドポイントに 2 度目の要求を行うことなく、承認エンドポイントからアクセス トークンをすぐに受信することができます。 |
正常な応答
承認エンドポイントは、以下の値を応答 URL でフラグメントとして返します:
- トークン: トークンはポータルの秘密鍵でデジタル署名された JSON Web トークン (JWT) として返されます。
- 状態: 状態パラメーターが要求に含まれる場合、同じ値が応答に表示されます。 アプリは要求と応答の状態値が同じであることを確認する必要があります。
- expires_in: アクセス トークンの有効期間 (秒単位)。
たとえば、正常な応答は下記のようです:
GET https://aadb2cplayground.azurewebsites.net/#token=eyJ0eXAiOiJKV1QiLCJhbGciOI1NisIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q&expires_in=3599&state=arbitrary_data_you_sent_earlier
エラー応答
承認エンドポイントのエラーは、次の値の 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": "7464eb01-71ab-44bc-93a1-f221479be847" }
ID トークンの検証
ID トークンを取得するだけではユーザーの認証に十分ではありません; トークンの署名を検証し、アプリの要件に基づいてトークン内の要求を確認する必要もあります。 公開トークン エンドポイントはポータルの公開鍵を提供し、それをポータルが提供したトークンの署名を検証するために使用できます。 公開トークン エンドポイントの URL は: <portal_url>/_services/auth/publickey。
暗黙的な許可フローをオンまたはオフにする
既定で、暗黙的な許可フローは有効です。 暗黙的な許可フローをオフにしたい場合は Connector/ImplicitGrantFlowEnabled サイト設定の値を False にします。
このサイト設定がポータルで利用できない場合は、適切な値で新しいサイト設定を作成する必要があります。
トークンの有効性を構成する
既定では、トークンは15分間有効です。 トークンの有効性を変更する場合は ImplicitGrantFlow/TokenExpirationTime サイト設定の値を必要な値に設定してください。 値は秒単位で指定する必要があります。 最大値で 1 時間が可能で、最小値は 1 分にする必要があります。 不正な値 (たとえば英数字) が指定されると、既定値の 15 分が使用されます。 最大値より大きい値や最小値より小さい値を指定した場合、既定では最大値と最小値がそれぞれ使用されます。
たとえばトークンの有効期間を 30 分に設定するには ImplicitGrantFlow/TokenExpirationTime サイト設定の値を 1800 にします。 トークンの有効期間を 1 時間に設定するには ImplicitGrantFlow/TokenExpirationTime サイト設定の値を 3600 にします。
暗黙的な許可フローにクライアント ID を登録する
このフローが許可されたポータルにクライアント ID を登録する必要があります。 クライアント ID を登録するには、次のサイト設定を作成する必要があります:
| サイト設定 | Value |
|---|---|
| ImplicitGrantFlow/RegisteredClientId | このポータルで許可されている有効なクライアント ID 値。 値はセミコロンで区切る必要があり、英数字とハイフンを使用できます。 最大長は 36 文字です。 |
| ImplicitGrantFlow/{ClientId}/RedirectUri | 特定のクライアント ID に許可された有効なリダイレクト URI。 値はセミコロンで区切る必要があります。 提供された URL はポータルの有効なWeb ページである必要があります。 |
サンプル コード
以下のサンプルコードを使用することで、Power Apps ポータル API で OAuth 2.0 の暗黙的な許可を利用することができます。
外部Web API でポータル OAuth トークンを使用する
このサンプルは、ASP.NET ベースのプロジェクトで、Power Apps ポータルが発行する ID トークンの検証に使用されます。 完全なサンプルは、外部 Web API でポータル OAuth トークンを使用するで確認することができます。
トークン エンドポイントのサンプル
このサンプルは、getAuthenticationToken 関数と Power Apps ポータルのトークン エンドポイントを使用した ID トークンをフェッチする方法を示しています。 このサンプルは、 トークン エンドポイントのサンプル で確認することができます。
注意
ドキュメントの言語設定についてお聞かせください。 簡単な調査を行います。 (この調査は英語です)
この調査には約 7 分かかります。 個人データは収集されません (プライバシー ステートメント)。
フィードバック
以下は間もなく提供いたします。2024 年を通じて、コンテンツのフィードバック メカニズムとして GitHub の issue を段階的に廃止し、新しいフィードバック システムに置き換えます。 詳細については、「https://aka.ms/ContentUserFeedback」を参照してください。
フィードバックの送信と表示