在 Azure App Service 驗證中使用 OAuth 權杖

發行項
03/20/2024

本文說明在 App Service 中使用內建驗證和授權時，如何利用 OAuth 權杖。

在應用程式程式碼中取出權杖

提供者專屬權杖會從伺服器程式碼插入到要求標頭，以供您輕鬆地存取。下表顯示可能的權杖標頭名稱：

Provider	標頭名稱
Microsoft Entra ID	`X-MS-TOKEN-AAD-ID-TOKEN` `X-MS-TOKEN-AAD-ACCESS-TOKEN` `X-MS-TOKEN-AAD-EXPIRES-ON` `X-MS-TOKEN-AAD-REFRESH-TOKEN`
Facebook 權杖	`X-MS-TOKEN-FACEBOOK-ACCESS-TOKEN` `X-MS-TOKEN-FACEBOOK-EXPIRES-ON`
Google	`X-MS-TOKEN-GOOGLE-ID-TOKEN` `X-MS-TOKEN-GOOGLE-ACCESS-TOKEN` `X-MS-TOKEN-GOOGLE-EXPIRES-ON` `X-MS-TOKEN-GOOGLE-REFRESH-TOKEN`
Twitter	`X-MS-TOKEN-TWITTER-ACCESS-TOKEN` `X-MS-TOKEN-TWITTER-ACCESS-TOKEN-SECRET`

注意

這些應用程式程式碼的標題可能會因不同的語言架構，而以不同的格式呈現，例如小寫或標題字體。

從用戶端程式碼 (例如行動應用程式或瀏覽器內的 JavaScript) 將 HTTP GET 要求傳送至 /.auth/me (必須啟用權杖存放區)。傳回的 JSON 具有提供者專屬權杖。

注意

存取權杖是用於存取提供者資源，因此僅在您使用用戶端密碼設定您的提供者時，這些權杖才會出現。若要了解如何取得重新整理權杖，請參閱「重新整理存取權杖」。

重新整理驗證權杖

當提供者的存取權杖 (而非工作階段權杖) 到期時，您必須於再次使用該權杖之前重新驗證使用者。您可以向應用程式的 /.auth/refresh 端點發出 GET 呼叫，以避免權杖到期。一經呼叫，App Service 就會自動重新整理已驗證使用者在權杖放區中的存取權杖。您應用程式程式碼的後續權杖要求會取得重新整理過的權杖。不過，若要進行權杖重新整理，權杖存放區必須包含您提供者的重新整理權杖。每個提供者會記載其重新整理權杖的取得方法，而下列清單僅為簡短摘要：

Google：將 access_type=offline 查詢字串參數附加至您的 /.auth/login/google API 呼叫。如需詳細資訊，請參閱 Google 重新整理權杖。
Facebook：不提供重新整理權杖。長時間執行的權杖會在 60 天內到期 (請參閱 Facebook 到期和存取權杖的擴充功能)。
Twitter：存取權杖不會到期 (請參閱 Twitter OAuth 常見問題集)。
Microsoft：在 https://resources.azure.com 中，請執行下列步驟：
1. 在頁面的頂端，選取 [讀取/寫入]。
2. 在左側瀏覽器中，巡覽至 subscriptions><subscription_name>>resourceGroups><resource_group_name>>providers>Microsoft.Web>sites><app_name>>config>authsettingsV2。
3. 按一下 [編輯] 。
4. 修改下列屬性。
```
"identityProviders": {
  "azureActiveDirectory": {
    "login": {
      "loginParameters": ["scope=openid profile email offline_access"]
    }
  }
}
```
5. 按一下 [放置]。
注意

該範圍能讓您重新整理 offline_access 的權杖。請參閱此教學課程：在 Azure App Service 中端對端驗證和授權使用者如何使用該範圍。 App Service 已預設要求其他範圍。如需這些預設範圍的資訊，請參閱 OpenID 連線範圍。

設定好提供者之後，您可以在權杖存放區中尋找重新整理權杖和存取權杖的到期時間。

若要隨時重新整理您的存取權杖，只要以任何語言呼叫 /.auth/refresh。下列程式碼片段會使用 jQuery 來重新整理 JavaScript 用戶端的存取權杖。

function refreshTokens() {
  let refreshUrl = "/.auth/refresh";
  $.ajax(refreshUrl) .done(function() {
    console.log("Token refresh completed successfully.");
  }) .fail(function() {
    console.log("Token refresh failed. See application logs for details.");
  });
}

如果使用者將授予您應用程式的權限撤銷，您對 /.auth/me 的呼叫可能會失敗，並出現 403 Forbidden 回應。若要診斷錯誤，請檢查您的應用程式記錄以取得詳細資訊。

延長工作階段權杖到期寬限期

經過驗證的工作階段會在 8 小時後過期。已驗證的工作階段到期之後，依預設會有 72 小時的寬限期。在此寬限期內，您可以使用 App Service 重新整理工作階段權杖，而無須重新驗證使用者。當您的工作階段權杖失效時，您只需要呼叫 /.auth/refresh，而不必自行追蹤權杖到期日。一旦 72 小時寬限期結束後，使用者必須重新登入，才能取得有效的工作階段權杖。

如果 72 小時的時間不夠您使用，您可以延長此到期時間範圍。將到期日延長超過一段很長的期間可能會造成重大的安全性影響 (例如，當驗證權杖外洩或遭竊時)。因此，請將它保留為預設的 72 小時，或將延長期間設為最小值。

若要延長預設的到期時間範圍，請在 Cloud Shell 中執行下列命令。

az webapp auth update --resource-group <group_name> --name <app_name> --token-refresh-extension-hours <hours>

注意

寬限期僅適用於 App Service 的已驗證工作階段，而不適用於識別提供者的權杖。已過期的提供者權杖沒有任何寬限期。

下一步

教學課程：端對端驗證和授權使用者

在 Azure App Service 驗證中使用 OAuth 權杖

在應用程式程式碼中取出權杖

重新整理驗證權杖

延長工作階段權杖到期寬限期

下一步

其他資源