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 驗證模組 （WSFAM） 的 HTTP 模組。 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 參數會識別 STS 之信賴憑證者 （RP） 應用程式的安全性領域。
您也可以藉由提供 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 |
取得或設定 wauth 參數的值，以用於 WS-Federation 登入要求中 （“wsignin1.0” ）。 |
| FederationConfiguration |
取得或設定目前模組生效的 FederationConfiguration 物件。 (繼承來源 HttpModuleBase) |
| Freshness |
取得或設定 wfresh 參數的值，以用於 WS-Federation 登入要求 （“wsignin1.0” ）。 |
| HomeRealm |
取得或設定 whr 參數的值，以用於 WS-Federation 登入要求中 （“wsignin1.0” ）。 |
| Issuer |
取得或設定 URI，識別安全性令牌的預期簽發者。 |
| PassiveRedirectEnabled |
取得或設定值，指定是否啟用模組來起始 WS-Federation 通訊協定重新導向。 |
| PersistentCookiesOnPassiveRedirects |
取得或設定值，指定是否在成功驗證時發出持續性會話 Cookie。 |
| Policy |
取得或設定要用於 WS-Federation 登入要求中的 wp 參數值 （“wsignin1.0” ）。 |
| Realm |
取得或設定要用於 WS-Federation 登入要求之 wtrealm 參數的值（“wsignin1.0” ）。 |
| Reply |
取得或設定 wreply 參數的值，以用於 WS-Federation 登入要求中 （“wsignin1.0” ）。 |
| Request |
取得或設定 wreq 參數的值，以用於 WS-Federation 登入要求中 （“wsignin1.0” ）。 |
| RequestPtr |
取得或設定 wreqptr 參數的值，以用於 WS-Federation 登入要求 （“wsignin1.0” ）。 |
| RequireHttps |
取得或設定值，指定與安全性令牌服務 （STS） 的通訊是否必須使用 HTTPS 通訊協定。 |
| Resource |
取得或設定 wres 參數的值，以用於 WS-Federation 登入要求 （“wsignin1.0” ）。 |
| SignInContext |
取得或設定要包含在 WS-Federation 登入要求中 wctx 參數的應用程式特定內容值。 |
| SignInQueryString |
取得或設定查詢字串，其中包含 WS-Federation 登入要求中傳送的任何其他參數（“wsignin1.0” ）。 |
| SignOutQueryString |
取得或設定查詢字串，其中包含 WS-Federation 註銷要求中要傳送的任何其他參數（“wsignout1.0” ）。 |
| SignOutReply |
取得或設定在 WS-Federation 註銷要求期間要使用的 wreply 參數值 （“wsignout1.0” ）。 |
| XmlDictionaryReaderQuotas |
取得或設定還原串行化 WS-Federation 登入回應訊息時要使用的 XmlDictionaryReaderQuotas 物件，以取得安全性令牌服務所發出的令牌（STS）。 |
方法
事件
| AuthorizationFailed |
當模組判斷是否應該將使用者重新導向至設定的簽發者進行驗證時發生。 |
| RedirectingToIdentityProvider |
發生於模組將使用者重新導向至識別提供者時。 |
| SecurityTokenReceived |
發生於從安全性令牌服務 （STS） 收到安全性令牌時。 |
| SecurityTokenValidated |
發生在從安全性令牌服務 （STS） 接收的安全性令牌經過驗證之後，但在建立會話安全性令牌之前發生。 |
| SessionSecurityTokenCreated |
發生於從安全性令牌服務 （STS） 收到的安全性令牌建立會話安全性令牌時。 |
| SignedIn |
會在使用者登入之後發生。 |
| SignedOut |
在註銷期間刪除會話之後發生。 |
| SignInError |
登入期間發生錯誤時引發。 |
| SigningOut |
在註銷期間刪除會話之前發生。 |
| SignOutError |
註銷期間發生錯誤時引發。 |
