在入口網站中使用 OAuth 2.0 隱含授與流程

注意

自 2022 年 10 月 12 日起，Power Apps 入口網站為 Power Pages。 其他資訊：Microsoft Power Pages 現在已推出 (部落格)
我們很快就會遷移並將 Power Apps 入口網站文件與 Power Pages 文件併合。

此功能可讓客戶使用 OAuth 隱含授與流程，對外部 API 進行用戶端呼叫並保護其安全。 其提供端點來取得安全存取權杖。 這些權杖將會包含外部 API 遵循 OAuth 2.0 隱含授與流程用於授權的使用者身分識別資訊。 登入使用者的識別資訊以安全的方式傳遞給外部 AJAX 呼叫，這可協助開發人員傳遞驗證內容，也可協助使用者保護其 API。

OAuth 2.0 隱含授與流程支援用戶端可呼叫取得識別碼權杖的端點。

自訂憑證

使用 OAuth 2.0 隱含授權流程的預設憑證已遭到取代。 使用 OAuth 2.0 端點時，您必須使用自訂憑證。 使用 Power Platform 系統管理中心以上傳自訂憑證。 上傳自訂憑證之後，您需要更新網站設定，如下所示：

1. 移至 入口網站設定 並選取 網站設定。

2. 若要建立新設定，選取 新增。

3. 若要編輯現有設定，選取格線中列出的網站設定。

4. 指定值：

   • 名稱： CustomCertificates/ImplicitGrantflow
   • 網站：關聯的網站
   • 值： 從 管理自訂憑證 畫面複製已上傳之自訂憑證的指紋，並在此處貼上。 該值將指示哪個憑證將用於隱含授與流程。

5. 選取 儲存並關閉。

權杖端點詳細資料

您也可以對 /token 端點提出 post 要求來取得權杖。 權杖端點的 URL 是：<portal_url>/_services/auth/token。 權杖端點支援下列參數：

參數	必要?	描述
client_id	否	對授權端點進行呼叫時所傳遞的字串。 您必須確定用戶端識別碼已註冊於入口網站。 否則會顯示錯誤。 用戶端識別碼是權杖的宣告中加入做為 aud 以及 appid 參數，可由用戶端用來驗證傳回的權杖適用於其應用程式。 長度上限為 36 個字元。 僅支援英數字元和連字號。
redirect_uri	否	可以用來傳送和接收驗證回覆的入口網站 URL。 它必須已針對呼叫中使用的特定 client_id 進行註冊，並且應與註冊的值完全相同。
state	否	包含在同樣會在權杖回覆傳回之要求中的值。 它可以是任何您要使用之內容的字串。 通常會使用隨機產生的唯一值用來防止跨網站要求偽造攻擊。 長度上限為 20 個字元。
nonce	否	用戶端傳送的字串值，包含在產生的識別碼權杖中做為宣告。 用戶端可接著驗證此值，以降低權杖重送攻擊。 長度上限為 20 個字元。
response_type	否	此參數僅支援 token 做為值，可讓應用程式立即從授權端點接收存取權杖，不需要對授權端點進行第二次要求。

注意

即使 client_id、redirect_uri、state 和 nonce 參數是選用，但還是建議使用這些參數來確保您的整合安全。

成功的回覆

權杖端點會傳回 state 及 expires_in 做為回覆標頭，以及在表單本文中傳回 token。

回覆錯誤

以包含下列值的 JSON 文件傳回權杖端點中的錯誤：

• 錯誤識別碼：代表錯誤的唯一識別碼。
• 錯誤訊息：協助您找出驗證錯誤根本原因的特定錯誤訊息。
• 關聯性識別碼：用作偵錯用途的 GUID。 如果您已啟用診斷記錄，則關聯性識別碼會出現在伺服器錯誤記錄中。
• 時間戳記：產生錯誤的日期與時間。

錯誤訊息會以登入使用者的預設語言來顯示。 如果使用者未登入，則顯示登入頁面給使用者登入。 例如，錯誤回覆如下所示：

{"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 要求取得識別碼權杖。]

授權端點的 URL 是：<portal_url>/_services/auth/authorize。 授權端點支援下列參數：

參數	必要?	描述
client_id	是	對授權端點進行呼叫時所傳遞的字串。 您必須確定用戶端識別碼已註冊於入口網站。 否則會顯示錯誤。 用戶端識別碼是權杖的宣告中加入做為 aud 以及 appid 參數，可由用戶端用來驗證傳回的權杖適用於其應用程式。 長度上限為 36 個字元。 僅支援英數字元和連字號。
redirect_uri	是	可以用來傳送和接收驗證回覆的入口網站 URL。 它必須已針對呼叫中使用的特定 client_id 進行註冊，並且應與註冊的值完全相同。
state	否	包含在同樣會在權杖回覆傳回之要求中的值。 它可以是任何您要使用之內容的字串。 通常會使用隨機產生的唯一值用來防止跨網站要求偽造攻擊。 長度上限為 20 個字元。
nonce	否	用戶端傳送的字串值，包含在產生的識別碼權杖中做為宣告。 用戶端可接著驗證此值，以降低權杖重送攻擊。 長度上限為 20 個字元。
response_type	否	此參數僅支援 token 做為值，其可讓應用程式立即從授權端點接收存取權杖，不需要對授權端點進行第二次要求。

成功的回覆

授權端點在回覆 URL 中傳回下列值做為片段：

• token：傳回以入口網站私密金鑰簽署的 JSON Web 權杖 (JWT) 做為權杖。
• state：如果 state 參數包含在要求中，此相同的值應該會顯示在回覆中。 應用程式必須確認要求與回覆中的狀態值完全相同。
• expires_in：存取權杖有效的時間長度 (以秒計)。

例如，成功的回覆如下所示：

GET https://aadb2cplayground.azurewebsites.net/#token=eyJ0eXAiOiJKV1QiLCJhbGciOI1NisIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q&expires_in=3599&state=arbitrary_data_you_sent_earlier

回覆錯誤

以包含下列值的 JSON 文件傳回授權端點中的錯誤：

• 錯誤識別碼：代表錯誤的唯一識別碼。
• 錯誤訊息：協助您找出驗證錯誤根本原因的特定錯誤訊息。
• 關聯性識別碼：用作偵錯用途的 GUID。 如果您已啟用診斷記錄，則關聯性識別碼會出現在伺服器錯誤記錄中。
• 時間戳記：產生錯誤的日期與時間。

錯誤訊息會以登入使用者的預設語言來顯示。 如果使用者未登入，則顯示登入頁面給使用者登入。 例如，錯誤回覆如下所示：

{"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" }

驗證識別碼權杖

只是取得識別碼權杖並不足以驗證使用者。您還必須驗證權杖的簽章，並根據應用程式的需求驗證權杖中的宣告。 公用權杖端點提供入口網站的公開金鑰，這可用來驗證入口網站所提供之權杖的簽章。 公用權杖端點的 URL 是：<portal_url>/_services/auth/publickey。

開啟或關閉隱含授與流程

預設會啟用隱含授與流程。 如果您想要關閉隱含授與流程，請將 Connector/ImplicitGrantFlowEnabled 網站設定的值設定為 False。

如果入口網站沒有提供此網站設定，您必須使用適當的值建立新的網站設定。

設定權杖有效性

根據預設，權杖有效時間是 15 分鐘。 如果您想要變更權杖的有效性，請將 ImplicitGrantFlow/TokenExpirationTime 網站設定的值設定為所需的值。 此值必須以秒為單位來指定。 最大值可以是 1 小時，而最小值則必須是 1 分鐘。 如果指定不正確的值 (例如，英數字元)，則使用 15 分鐘的預設值。 如果指定大於最大值或小於最小值的值，則依預設分別使用最大值與最小值。

例如，若將權杖有效性設定為 30 分鐘，則會將 ImplicitGrantFlow/TokenExpirationTime 網站設定的值設定為 1800。 若要將權杖有效性設定為 1 小時，請將 ImplicitGrantFlow/TokenExpirationTime 網站設定的值設定為 3600。

註冊隱含授與流程的用戶端識別碼

您必須將用戶端識別碼註冊於允許此流程的入口網站。 若要註冊用戶端識別碼，您必須建立下列網站設定：

網站設定	Value
ImplicitGrantFlow/RegisteredClientId	此入口網站允許的有效用戶端識別碼值。 這些值必須以分號分隔，並且可以包含英數字元和連字號。 長度上限為 36 個字元。
ImplicitGrantFlow/{ClientId}/RedirectUri	特定用戶端識別碼允許的有效重新導向 URI。 這些值必須以分號分隔。 提供的 URL 必須是入口網站的有效網頁。

範例指令碼

您可以使用下列範例程式碼，開始搭配 Power Apps 入口網站 API 使用 Oauth 2.0 隱含授與。

將入口網站 Oauth 權杖與外部 Web API 搭配使用

此範例是以 ASP.NET 為基礎的專案，可用來驗證 Power Apps 入口網站所發出的識別碼權杖。 完整範例可在這裡找到：將入口網站 OAuth 權杖與外部 Web API 搭配使用。

權杖端點範例

此範例顯示如何使用 getAuthenticationToken 函數，透過 Power Apps 入口網站中的權杖端點來擷取識別碼權杖。 此範例可在這裡找到：權杖端點範例。

注意

是否能請您告知您偏好的慣用文件語言？ 請填寫問卷。 (請注意，本問卷為英文版)

完成問卷大約需要七分鐘。 本問卷將不會收集個人資料 (隱私權聲明)。