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.
- Add a
<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.
Method 1: Using the FederatedPassiveSignIn Control
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.
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
- 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
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
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>
Method 2: Using the <passiveRedirect> Element to Perform Automatic Caller Sign-In
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
specifies the STS that issues the tokens. The
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
<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.