Compartilhar via

Building ASP.NET Relying Party Applications

  • Artigo

[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.]

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:

  1. Use the FederatedPassiveSignIn control.

  2. Add a <PassiveRedirect> element to the Microsoft.IdentityModel configuration section of your web.config file.

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. 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.

  1. In Visual Studio, add a FederatedPassiveSignIn control to the page from the toolbox.

  2. Set the Issuer property to the URL of a specific token issuer.

  3. 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.

  4. 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 Session.

  5. 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 FederatedPassiveSignIn control:

<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 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 Issuer and 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.