Establishing Trust from an ASP.NET Relying Party Application to an STS using the FederatedPassiveSignIn Control

[Starting with the .NET Framework 4.5, Windows Identity Foundation (WIF) has been fully integrated into the .NET Framework. The version of WIF addressed by this topic, WIF 3.5, is deprecated and should only be used when developing against the .NET Framework 3.5 SP1 or the .NET Framework 4. For more information about WIF in the .NET Framework 4.5, also known as WIF 4.5, see the Windows Identity Foundation documentation in the .NET Framework 4.5 Development Guide.]

Using the FederatedPassiveSignIn control, you can extend your Web site to redirect users to a federated security token service (STS), and to process security tokens issued by that STS.

In this exercise, you create a claims-aware ASP.NET relying party application. Then you use the FederatedPassiveSignIn to redirect users to a local STS. Finally, you use FedUtil to create the local STS.

Note

You must run Visual Studio in Elevated mode for FedUtil to work correctly.

In Visual Studio, open the File menu and select New, Web Site. Select Claims-aware ASP.NET Web Site.

Right-click the login.aspx file in your project and select View Designer:

Open the Toolbox, open the section Windows Identity Foundation Controls, and find the FederatedPassiveSignIn control:

Drag the FederatedPassiveSignIn control to the login.aspx page in the designer:

If the FederatedPassiveSignIn control does not appear in the Toolbox, open the Tools menu and select Choose Toolbox Items.... In the .NET Framework Components tab, make sure that the FederatedPassiveSignIn control is checked:

After you add the FederatedPassiveSignIn control to the login.aspx page, you can remove the existing login form:

In the Designer, select the FederatedPassiveSignIn control and look at the Properties window. Set the UseFederationPropertiesFromConfiguration property to true. You cannot run FedUtil on the control while this property is false. While the property is true, the control will ignore any passive federation properties set on the control itself.

Right-click the FederatedPassiveSignIn control and select Invoke Fed Util.... In FedUtil, follow the steps shown in the “Use an Existing STS” section of Establishing Trust from an ASP.NET Relying Party Application to an STS using FedUtil.

If you have multiple FederatedPassiveSignIn controls on the same login page, and you want each control to use a different authentication method and redirect users to a different STS, you must set the UseFederationPropertiesFromConfiguration property for each control to false, and set the passive federation properties on the controls themselves, rather than using FedUtil.

When the FederatedPassiveSignIn control receives a federated passive sign-in response (RSTR), it expects the wctx property to contain a control ID that matches the control on the Web page. This is to address the scenario in which you have multiple FederatedPassiveSignIn controls on the same login page, and the control that initiated the federated passive sign-in request (RST) needs to process the response (RSTR). If the STS sends a token via federated passive response (RSTR) but drops the wctx property, the FederatedPassiveSignIn control will not successfully process the response.

Running FedUtil from the FederatedPassiveSignIn control is different from running FedUtil by right-clicking on a project in Visual Studio. Running FedUtil from the control means that the fields in the Application Information page are not pre-populated. Also, in the Security Token Service page, the only option available is to use an existing STS. It is advised that you first create an STS as described in How to: Build an ASP.NET STS or How to: Build a WCF STS. After you create the STS, you can then run FedUtil from the FederatedPassiveSignIn control and establish trust from your application to the STS.