遠端驗證

發行項
01/23/2025

System.Web 配接器的遠端驗證功能可讓 ASP.NET Core 應用程式藉由延遲至 ASP.NET 應用程式來判斷使用者的身分識別（驗證 HTTP 要求）。啟用此功能會將端點新增至 ASP.NET 應用程式，此應用程式會針對對端點發出的任何要求，傳回代表已驗證使用者的序列化 ClaimsPrincipal。接著，ASP.NET Core 應用程式會註冊自定義驗證處理程式，該處理程式會（針對已啟用遠端驗證的端點），藉由在 ASP.NET 應用程式上呼叫該端點，以及從 ASP.NET Core 應用程式收到的原始要求傳遞選取的標頭和 Cookie，以判斷使用者的身分識別。

組態

在已根據 [使用者入門] 設定的解決方案中啟用遠端驗證，只需要一些小的程式碼變更。

首先，請遵循 [遠端應用程式設定] 指示來連線 ASP.NET Core 和 ASP.NET 應用程式。然後，只需要呼叫幾個額外的擴充方法，即可啟用遠端應用程式驗證。

ASP.NET 應用程式設定

ASP.NET 應用程式必須設定為新增驗證端點。藉由呼叫 AddAuthenticationServer 擴充方法來設定 HTTP 模組來監看驗證端點的要求，以新增驗證端點。請注意，遠端驗證案例通常也想要新增 Proxy 支援，讓任何與驗證相關的重新導向正確地路由至 ASP.NET Core 應用程式，而不是 ASP.NET。

SystemWebAdapterConfiguration.AddSystemWebAdapters(this)
    .AddProxySupport(options => options.UseForwardedHeaders = true)
    .AddRemoteAppServer(options =>
    {
        options.ApiKey = ConfigurationManager.AppSettings["RemoteAppApiKey"];
    })
    .AddAuthenticationServer();

ASP.NET Core 應用程式設定

接下來，ASP.NET Core 應用程式必須設定為啟用驗證處理常式，以對 ASP.NET 應用程式提出 HTTP 要求來驗證使用者。同樣地，註冊 System.Web 配接器服務時呼叫 AddAuthenticationClient 即可完成:

builder.Services.AddSystemWebAdapters()
    .AddRemoteAppClient(options =>
    {
        options.RemoteAppUrl = new Uri(builder.Configuration
            ["ReverseProxy:Clusters:fallbackCluster:Destinations:fallbackApp:Address"]);
        options.ApiKey = builder.Configuration["RemoteAppApiKey"];
    })
    .AddAuthenticationClient(true);

傳遞至呼叫的 AddAuthenticationClient 布林值會指定遠端應用程式驗證是否應該是預設驗證結構描述。傳遞 true 會導致使用者透過所有要求的遠端應用程式驗證進行驗證，而傳遞 false 表示只有在特別要求遠端應用程式結構描述時，使用者才會使用遠端應用程式驗證進行驗證 (例如，使用控制器上或動作方法上的 [Authorize(AuthenticationSchemes = RemoteAppAuthenticationDefaults.AuthenticationScheme)])。針對此參數傳遞 false 的優點是只會對原始 ASP.NET 應用程式提出 HTTP 要求，以為需要遠端應用程式驗證的端點進行驗證，但缺點是需要批註所有這類端點，以指出它們將使用遠端應用程式驗證。

除了需要布林值之外，也可以傳遞選擇性回撥給 AddAuthenticationClient 以修改遠端驗證流程行為的一些其他層面:

RequestHeadersToForward: 這個屬性包含在呼叫驗證 API 時，應該從要求轉送的標頭。根據預設，轉送的唯一標頭是 Authorization 和 Cookie。您可以將其他標頭新增至此清單，以轉送其他標頭。或者，如果已清除清單 (因此未指定任何標頭)，則會轉送所有標頭。
ResponseHeadersToForward：此屬性會列出回應標頭，這些響應標頭應該從驗證要求傳播回原始呼叫，以在身分識別受到挑戰的情況下提示驗證。根據預設，這包括 Location、Set-Cookie 和 WWW-Authenticate 標頭。
AuthenticationEndpointPath: 應該在其中提出驗證要求之 ASP.NET 應用程式的端點。這會預設為 /systemweb-adapters/authenticate，且必須符合 ASP.NET 驗證端點設定中指定的端點。

最後，如果 ASP.NET Core 應用程式先前未包含驗證中介軟體，則必須啟用該中介軟體 (路由中介軟體之後，但在授權中介軟體之前):

app.UseAuthentication();

設計

當 ASP.NET Core 應用程式處理要求時，如果遠端應用程式驗證是預設結構描述，或由要求的端點指定，則 RemoteAuthenticationAuthHandler 會嘗試驗證使用者。
1. 處理常式會向 ASP.NET 應用程式的驗證端點提出 HTTP 要求。它會將設定的標頭從目前的要求複製到這個新的標頭，以便轉送與驗證相關的資料。如上所述，預設行為是複製 Authorize 和 Cookie 標頭。此外，也會新增 API 金鑰標頭以達到安全性目的。
ASP.NET 應用程式會為傳送至驗證端點的要求提供服務。只要 API 金鑰相符，ASP.NET 應用程式就會傳回目前使用者的 ClaimsPrincipal 序列化至回應本文，否則會傳回 HTTP 狀態碼 (例如 401 或 302)，以及指出失敗的回應標頭。
當 ASP.NET Core 應用程式的 RemoteAuthenticationAuthHandler 收到來自 ASP.NET 應用程式的回應時:
1. 如果成功返回 ClaimsPrincipal，驗證處理元件將會將其反序列化，並將它用作當前使用者的身分識別。
2. 如果 ClaimsPrincipal 未成功傳回，處理常式將會儲存結果，如果驗證受到挑戰 (例如，因為使用者正在存取受保護的資源)，要求的回應將會以狀態碼，以及從驗證端點的回應中選取的回應標頭進行更新。這可讓挑戰回應 (例如重新導向至登入頁面) 傳播給終端使用者。
  1. 由於來自 ASP.NET 應用程式驗證端點的結果可能包含該端點的特定資料，因此使用者可以向 ASP.NET Core 應用程式註冊 IRemoteAuthenticationResultProcessor 實作，這些實作會在使用之前於任何驗證結果上執行。例如，一個內建 IRemoteAuthenticationResultProcessor 是 RedirectUrlProcessor，它會尋找 Location 個從驗證端點傳回的回應標頭，並確保它們會重新導向回 ASP.NET Core 應用程式的主機，而不是直接到 ASP.NET 應用程式。

已知的限制

此遠端驗證方法有一些已知的限制:

由於 Windows 驗證依賴 Windows 身分識別的控制代碼，因此此功能不支援 Windows 驗證。已計劃未來工作來探索共用 Windows 驗證的運作方式。如需詳細資訊，請參閱 dotnet/systemweb-adapters#246。
這項功能可讓 ASP.NET Core 應用程式使用由 ASP.NET 應用程式驗證的身分識別，但與使用者相關的所有動作（登入、註銷等）仍然需要透過 ASP.NET 應用程式路由傳送。

替代項目

如果 ASP.NET 應用程式中的驗證是使用 Microsoft.OwinCookie 驗證中間件完成，共用身分識別的替代解決方案是設定 ASP.NET 和 ASP.NET Core 應用程式，讓它們能夠共用驗證 cookie。共用驗證 cookie 可啟用:

這兩個應用程式都會從相同的 cookie判斷使用者身分識別。
登入或登出某個應用程式會將使用者登入或登出另一個應用程式。

請注意，因為登入通常取決於特定資料庫，並非所有驗證功能都能在這兩個應用程式中運作:

使用者應該只透過其中一個應用程式登入，無論是 ASP.NET 或 ASP.NET Core 應用程式，只要資料庫設定為使用即可。
這兩個應用程式都可以看到使用者的身分識別和宣告。
這兩個應用程式都能夠將使用者登出。

有關如何在 ASP.NET 與 ASP.NET Core 應用程式之間設定共用驗證 Cookie 的詳細資料，請參閱 cookie 共用文件。 System.Web 配接器 GitHub 存放庫中的下列範例會示範使用共用 cookie 設定進行遠端應用程式驗證，讓兩個應用程式都能登入和登出:

如果下列兩者都成立，則共用驗證是不錯的選擇:

ASP.NET 應用程式已經在使用 Microsoft.Owincookie 驗證。
您可以使用相符的資料保護設定來更新 ASP.NET 應用程式和 ASP.NET Core 應用程式。比對共用資料保護設定包括共用檔案路徑、Redis 快取或 Azure Blob 儲存體來儲存資料保護金鑰。

針對其他案例，本文件先前所述的遠端驗證方法更有彈性，而且可能更適合。

共用方式為

遠端驗證

組態

ASP.NET 應用程式設定

ASP.NET Core 應用程式設定

設計

已知的限制

替代項目

其他資源