Building ASP.NET Relying Party Applications
According to the WS-Federation specification 1.2, this scenario is referred to as a passive requester profile. Browser clients are used to perform the form redirects and no WS-Trust serialization logic is present in the clients. This provides two ways to help secure an ASP.NET Web application that uses passive federation:
Use the FederatedPassiveSignIn control.
<PassiveRedirect>element to the
Microsoft.IdentityModelconfiguration section of your
The second way requires that you enable the WSFederationAuthenticationModule in the Web application. To maintain an authentication session, you will also need the SessionAuthenticationModule. For more information, see WS-Federated Authentication Module Overview.
There are two methods to configure a sign-in page for federation: (1) using the FederatedPassiveSignIn control, and (2) configuring the WS-FAM for passive redirect.
WIF provides the FederatedPassiveSignIn control to enable easy integration of Web applications together with the claims-based identity model and to make Web applications claims-aware. By using this control, you can move the authentication process from the Web application to an STS by specifying the STS address to which the Web application should redirect the user. Upon receiving the response from the STS, the control authenticates the security token presented in the response. If successful, it issues a cookie that the caller uses on any subsequent calls so that they do not have to be redirected back to the STS again. Once the cookie expires, the caller must authenticate to the STS again to obtain a new security token.
If you are using Visual Studio 2005, before starting, make sure that you install the WIF controls into the Visual Studio toolbox. You can do this by opening the toolbox, right-clicking on it and then selecting Choose Items.... In the resulting dialog box, select the .NET Framework Components tab and then click the Browse button in the lower-right corner. Select the
Microsoft.IdentityModel.dll assembly from the Reference Assemblies directory inside the WIF installation folder and then click Open. Then click OK. New controls will appear inside the toolbox windows under the Standard category. One of the controls is called
FederatedPassiveSignIn and that’s the one that you will be using in the following steps.
In Visual Studio, add a
FederatedPassiveSignIncontrol to the page from the toolbox.
Set the Issuer property to the URL of a specific token issuer.
Set the Realm property. This is used by the STS to identify the relying party instance and to select the corresponding token issuance policy and encryption certificate.
You can set event handlers in the markup, such as a handler that will be called when the token is validated. You can also specify whether a cookie is to be returned to the user after the token authentication is successfully performed (set SignInMode to
Session) or whether no cookie is returned. In the latter case, the caller is redirected to the STS again when the user makes a new request (set SignInMode to
Single). The default value is
You can customize the appearance and behavior of the control by setting various properties in the Appearance category. For example, the SignInButtonStyle property determines whether the control appears as a clickable image or as a simple link in the rendered page.
The following sample code shows the markup for a
<wif:FederatedPassiveSignIn id="FederatedPassiveSignIn1" runat="server" Issuer="https://www.contoso.com:441/PassiveIdentityProvider/default.aspx" SignInButtonType="Link" Realm="https://www.contoso.com:441" OnSecurityTokenReceived="FederatedPassiveSignIn1_SecurityTokenReceived"> </wif:FederatedPassiveSignIn>
The WS-FAM offers a
<passiveRedirect> configuration element to enable automatic redirection of unauthenticated user requests to a designated STS. You must add the
federatedAuthentication element to the
Microsoft.IdentityModel section to enable passive redirection. There are two required attributes when automatic passive redirection is enabled. The
issuer attribute specifies the STS that issues the tokens. The
realm attribute provides the relying party identification to the STS. These attributes mean the same things as the
Realm properties on the
FederatedPassiveSignIn control as described in the previous section. The following code sample shows how to add this element:
<federatedAuthentication enabled="true"> <passiveRedirect enabled="true" issuer="https://localhost/SimplePassiveSTS1/default.aspx" realm="https://localhost/ClaimsAwareWebApp1"></passiveRedirect> </federatedAuthentication>
For more information, see How to: Build an ASP.NET Relying Party Application.