WSFederationAuthenticationModule 類別
定義
重要
部分資訊涉及發行前產品，在發行之前可能會有大幅修改。 Microsoft 對此處提供的資訊，不做任何明確或隱含的瑕疵擔保。
WSFederationAuthenticationModule是 HTTP 模組，用來藉由對連入要求強制執行同盟驗證設定來保護 ASP.NET 應用程式。 WSFederationAuthenticationModule 是 WIF 現成提供的主要模組，用於處理 ASP.NET 應用程式中的宣告式識別存取。
WSFederationAuthenticationModule會引發數個事件，它可讓 ASP.NET 開發人員變更預設行為，並控制驗證和宣告處理發生方式的詳細資訊。 WSFederationAuthenticationModule功能會分為特定工作的方法。
public ref class WSFederationAuthenticationModule : System::IdentityModel::Services::HttpModuleBasepublic class WSFederationAuthenticationModule : System.IdentityModel.Services.HttpModuleBasetype WSFederationAuthenticationModule = class
inherit HttpModuleBasePublic Class WSFederationAuthenticationModule
Inherits HttpModuleBase- 繼承
範例
void Application_Start(object sender, EventArgs e)
{
// Code that runs on application startup
//SUBSCRIBE TO WSFAM EVENTS
FederatedAuthentication.WSFederationAuthenticationModule.AuthorizationFailed += new EventHandler<AuthorizationFailedEventArgs>(WSFederationAuthenticationModule_AuthorizationFailed);
FederatedAuthentication.WSFederationAuthenticationModule.RedirectingToIdentityProvider += new EventHandler<RedirectingToIdentityProviderEventArgs>(WSFederationAuthenticationModule_RedirectingToIdentityProvider);
FederatedAuthentication.WSFederationAuthenticationModule.SecurityTokenReceived += new EventHandler<SecurityTokenReceivedEventArgs>(WSFederationAuthenticationModule_SecurityTokenReceived);
FederatedAuthentication.WSFederationAuthenticationModule.SecurityTokenValidated += new EventHandler<SecurityTokenValidatedEventArgs>(WSFederationAuthenticationModule_SecurityTokenValidated);
FederatedAuthentication.WSFederationAuthenticationModule.SessionSecurityTokenCreated += new EventHandler<SessionSecurityTokenCreatedEventArgs>(WSFederationAuthenticationModule_SessionSecurityTokenCreated);
FederatedAuthentication.WSFederationAuthenticationModule.SignedIn += new EventHandler(WSFederationAuthenticationModule_SignedIn);
}
void WSFederationAuthenticationModule_SignedIn(object sender, EventArgs e)
{
//Anything that's needed right after succesful session and before hitting the application code goes here
System.Diagnostics.Trace.WriteLine("Handling SignIn event");
}
void WSFederationAuthenticationModule_SessionSecurityTokenCreated(object sender, SessionSecurityTokenCreatedEventArgs e)
{
//Manipulate session token here, for example, changing its expiration value
System.Diagnostics.Trace.WriteLine("Handling SessionSecurityTokenCreated event");
System.Diagnostics.Trace.WriteLine("Key valid from: " + e.SessionToken.KeyEffectiveTime);
System.Diagnostics.Trace.WriteLine("Key expires on: " + e.SessionToken.KeyExpirationTime);
}
void WSFederationAuthenticationModule_SecurityTokenValidated(object sender, SecurityTokenValidatedEventArgs e)
{
//All vlidation SecurityTokenHandler checks are successful
System.Diagnostics.Trace.WriteLine("Handling SecurityTokenValidated event");
}
void WSFederationAuthenticationModule_SecurityTokenReceived(object sender, SecurityTokenReceivedEventArgs e)
{
//Augment token validation with your cusotm validation checks without invalidating the token.
System.Diagnostics.Trace.WriteLine("Handling SecurityTokenReceived event");
}
void WSFederationAuthenticationModule_AuthorizationFailed(object sender, AuthorizationFailedEventArgs e)
{
//Use this event to report more details regarding the ahorization failure
System.Diagnostics.Trace.WriteLine("Handling AuthorizationFailed event");
}
void WSFederationAuthenticationModule_RedirectingToIdentityProvider(object sender, RedirectingToIdentityProviderEventArgs e)
{
//Use this event to programmatically modify the sign-in message to the STS.
System.Diagnostics.Trace.WriteLine("Handling RedirectingToIdentityProvider event");
}
備註
類別 WSFederationAuthenticationModule 會實作稱為「WS-Federation 驗證模組」的 HTTP 模組， (WSFAM) 。 WSFAM 是由 Windows Identity Foundation (WIF) 實作。 WSFAM 會在 web.config 檔案中建立專案，以新增至 ASP.NET 管線。 它衍生自 HttpModuleBase，其會實作 IHttpModule。 它會向 ASP.NET 運行時間註冊以接 EndRequest 聽 和 AuthenticateRequest 事件。 接 EndRequest 聽事件，讓 WSFAM 將用戶端重新導向至安全性令牌服務， (STS) ，以在要求的資源授權失敗時取得安全性令牌。 接 AuthenticateRequest 聽事件可讓 WSFAM 監視來自包含所要求令牌之 STS 回應的 HTTP 要求。 當這類令牌存在且有效時，它會使用令牌中存在的宣告，為已驗證的使用者建立的實例 ClaimsPrincipal 。
使用 WSFAM 時，會話管理是由會話驗證模組提供， (SAM) ，這是 類別的 SessionAuthenticationModule 實例，或衍生自它的類別。 SAM 也會新增至組態檔中的 ASP.NET 管線。 SAM 會監視 (工作階段) Cookie 的驗證要求。 當這些 Cookie 存在且有效時，模組會從 SessionSecurityToken 中擷取ClaimsPrincipal已驗證使用者的 ，並設定 HttpContext.User 屬性和線程主體Thread.CurrentPrincipal屬性。
WSFAM 提供：
ASP.NET 應用程式使用 WS-Federation 通訊協定，將驗證外包給安全性令牌服務 (STS) 的能力。 身分識別可以跨一或多個身分識別領域建立同盟，並涉及多個 STS。
ASP.NET 應用程式的宣告型身分識別。 在驗證期間，WSFAM 會從 STS 所傳送的安全性令牌中的宣告建置主體，並將此宣告主體設定為線程主體。 然後，您可以使用此主體來進一步對程式代碼中代表的使用者進行授權、呈現和邏輯決策。
WSFAM 會公開數個屬性，以提供預設訊息參數，以用於 WS-Federation 登入和註銷要求。 這些屬性通常會從 <組態檔中的 wsFederation> 元素初始化。 這些屬性最重要的包括：
Issuer屬性，指定要傳送 WS-Federation 登入和註銷要求的 STS) 安全性令牌服務位址 (。
Realm屬性，指定要在 WS-Federation 登入要求中使用的 wtrealm 參數。 wtrealm 參數會識別信賴憑證者 (RP) 應用程式的安全性領域至 STS。
您也可以藉由為事件提供事件處理程式委派 RedirectingToIdentityProvider ，以依要求變更登入訊息參數。
兩個屬性控制模組的行為。 這兩個屬性通常也會從 <wsFederation> 組態中的 元素初始化。
屬性 PassiveRedirectEnabled 會指定模組是否應該執行被動重新導向至 STS 以進行驗證。
屬性 PersistentCookiesOnPassiveRedirects 會指定會話是否應該是持續性的。 如果此屬性設定為 true，SAM 會用來將會話 Cookie 寫入用戶端。 在客戶端的後續要求上，SAM 會使用保存在會話 Cookie 中的令牌來提供驗證。
WSFAM 會在登入和註銷期間引發數個事件，這可讓 ASP.NET 開發人員變更模組的預設行為，並控制驗證和宣告處理方式的詳細數據。
下列事件會在 WS-Federation 登入要求傳送至 STS 之前引發：
AuthorizationFailed：啟用被動重新導向且授權在要求的資源上失敗時引發。
RedirectingToIdentityProvider：在 WSFAM 將 WS-Federation 登入要求傳送至 STS 之前引發。 您可以使用此事件來變更登入要求中的參數。
從 STS 收到登入回應 (發行的安全性令牌) 時，就會引發下列事件：
SecurityTokenReceived：從回應讀取 STS 傳送的安全性令牌之後引發。
SecurityTokenValidated：在驗證令牌之後引發。 您可以使用此事件來篩選、轉換或新增宣告至從安全性令牌建立的宣告主體 (ClaimsPrincipal) 。
SessionSecurityTokenCreated：在會話令牌 (SessionSecurityToken) 從宣告主體建立的會話令牌之前引發，會用來設定線程主體和目前使用者，並寫入會話 Cookie。 讓您有機會修改會話令牌，或啟用或停用寫入會話 Cookie。
SignedIn：在設定線程主體和目前用戶之後，在驗證結束時引發。
SignInError：如果在登入期間發生例外狀況，就會引發。 您可以取消要求，並防止例外狀況傳回給呼叫端。
註銷會話或處理 WS-Federation 註銷清除要求 (wsignoutcleanup1.0) 時，會引發下列事件：
SigningOut：在刪除會話之前引發，可讓您執行任何可能相依於會話或取消註銷的清除。
SignedOut：在刪除會話之後引發。
SignOutError：註銷期間發生例外狀況時引發。您可以取消註銷，並防止例外狀況傳回給呼叫端。
注意
透過呼叫 FederatedSignOut 方法在 STS 註銷時，不會引發註銷事件。
有兩種方式可以使用 WSFAM 登入 STS。 第一個是透過 屬性啟用被動重新 PassiveRedirectEnabled 導向。 在此情況下，當要求的資源授權失敗，而不是傳回 401:Access Denied 對用戶端的回應時，WSFAM 會從其屬性建置 WS-Federation 登入要求訊息，並將用戶端重新導向至 STS 以擷取安全性令牌。 第二種方式是從應用程式中的網頁或自定義控件呼叫 SignIn 方法，明確地將用戶端重新導向至 STS。 方法 SignIn 也會使用 WSFAM 的屬性來建構登入要求。
任何多載 SignOut 方法都可以用來註銷會話。 這會刪除用戶端上的會話 Cookie。 它不會將 WS-Federation 註銷訊息 (“wsignout1.0”) 傳送至 STS。 若要註銷 STS，您必須使用 FederatedSignOut 方法。
WSFAM 會藉由刪除用戶端的會話，來處理 WS-Federation 註銷清除要求 (“wsignoutcleanup1.0”) 。 如果未設定註銷清除訊息中的 wreply 參數，WSFAM 會將綠色複選標記的影像傳回至傳送訊息的 STS。 STS 可以使用這項功能作為 RP 已完成註銷的通知。
WSFAM 會公開其功能，例如，其要求處理管線 -- 透過數個工作特定的方法。 您可以在衍生類別中覆寫這些方法，以改變 WSFAM 的行為。
若要使用，模組必須新增至管線，如下列 XML 所示：
<configuration>
<system.webServer>
<modules>
<add name="WsFederationAuthenticationModule" type="System.IdentityModel.Services.WSFederationAuthenticationModule, System.IdentityModel.Services, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089"/>
</modules>
</system.webServer>
</configuration>
設定之後，會在 WSFederationAuthenticationModule 處理 HTTP 要求的各種階段引發事件。 ASP.NET 開發人員可以在 global.asax 檔案中處理這些事件。
建構函式
| WSFederationAuthenticationModule() |
由衍生類別的建構函式呼叫，以初始化 WSFederationAuthenticationModule 類別。 |
屬性
| AuthenticationType |
取得或設定要在 WS-同盟登入要求 ("wsignin1.0") 中使用的 wauth 參數值。 |
| FederationConfiguration |
取得或設定目前模組的作用中 FederationConfiguration 物件。 (繼承來源 HttpModuleBase) |
| Freshness |
取得或設定要在 WS-同盟登入要求 ("wsignin1.0") 中使用的 wfresh 參數值。 |
| HomeRealm |
取得或設定要在 WS-同盟登入要求 ("wsignin1.0") 中使用的 whr 參數值。 |
| Issuer |
取得或設定 URI，識別想要的安全性權杖簽發者。 |
| PassiveRedirectEnabled |
取得或設定值，指定此模組是否已啟用來啟始 WS-Federation 通訊協定重新導向。 |
| PersistentCookiesOnPassiveRedirects |
取得或設定值，指定是否要在成功驗證時發出永續性工作階段 cookie。 |
| Policy |
取得或設定要在 WS-同盟登入要求 ("wsignin1.0") 中使用的 wp 參數值。 |
| Realm |
取得或設定要用於 WS-同盟登入要求 ("wsignin1.0") 的 wtrealm 參數值。 |
| Reply |
取得或設定要在 WS-同盟登入要求 ("wsignin1.0") 中使用的 wreply 參數值。 |
| Request |
取得或設定要在 WS-同盟登入要求 ("wsignin1.0") 中使用的 wreq 參數值。 |
| RequestPtr |
取得或設定要在 WS-同盟登入要求 ("wsignin1.0") 中使用的 wreqptr 參數值。 |
| RequireHttps |
取得或設定值，指定安全性權杖服務 (STS) 通訊是否必須使用 HTTPS 通訊協定。 |
| Resource |
取得或設定要在 WS-同盟登入要求 ("wsignin1.0") 中使用的 wres 參數值。 |
| SignInContext |
取得或設定要包含在 WS-同盟登入要求之 wctx 參數中的應用程式專屬內容值。 |
| SignInQueryString |
取得或設定查詢字串，包含 WS-同盟登入要求 ("wsignin1.0") 中要傳送的任何其他參數。 |
| SignOutQueryString |
取得或設定查詢字串，包含 WS-同盟登出要求 ("wsignout1.0") 中要傳送的任何其他參數。 |
| SignOutReply |
取得或設定要在 WS-同盟登出要求 ("wsignout1.0") 期間使用的 wreply 參數值。 |
| XmlDictionaryReaderQuotas |
取得或設定 XmlDictionaryReaderQuotas 物件，以用於還原序列化 WS-Federation 登入回應訊息時，取得安全性權杖服務 (STS) 所發出的權杖。 |
方法
事件
| AuthorizationFailed |
當模組正在判斷它是否應該將使用者重新導向至已設定的簽發者進行驗證時發生。 |
| RedirectingToIdentityProvider |
當模組要將使用者重新導向到識別提供者時發生。 |
| SecurityTokenReceived |
已經從安全性權杖服務 (STS) 收到安全性權杖時發生。 |
| SecurityTokenValidated |
從安全性權杖服務 (STS) 接收到的安全性權杖經過驗證之後，但在建立工作階段安全性權杖之前發生。 |
| SessionSecurityTokenCreated |
根據從安全性權杖服務 (STS) 接收到的安全性權杖，已經建立工作階段安全性權杖時發生。 |
| SignedIn |
使用者已登入之後發生。 |
| SignedOut |
登出期間刪除工作階段之後發生。 |
| SignInError |
當登入發生錯誤時引發。 |
| SigningOut |
登出期間刪除工作階段之前發生。 |
| SignOutError |
當登出發生錯誤時引發。 |
適用於
意見反應
即將登場：在 2024 年，我們將逐步淘汰 GitHub 問題作為內容的意見反應機制，並將它取代為新的意見反應系統。 如需詳細資訊，請參閱：https://aka.ms/ContentUserFeedback。
提交並檢視相關的意見反應