<federationConfiguration>

Article
03/30/2017

Configures the WSFederationAuthenticationModule (WSFAM) and the SessionAuthenticationModule (SAM) when using federated authentication through the WS-Federation protocol. Configures the ClaimsAuthorizationManager when using the ClaimsPrincipalPermission or the ClaimsPrincipalPermissionAttribute class to provide claims-based access control.

<configuration>
<system.identityModel.services>
<federationConfiguration>

Syntax

<system.identityModel.services>  
  <federationConfiguration name=xs:string identityConfigurationName=xs:string>  
  </federationConfiguration>  
</system.identityModel.services>

Attributes and Elements

The following sections describe attributes, child elements, and parent elements.

Attributes

Attribute	Description
name	The name of this federation configuration element. This attribute primarily provides an extensibility point for future protocols. Optional.
identityConfigurationName	The name of the identity configuration section as specified in an <identityConfiguration> element to use. If this attribute is not specified, the default identity configuration section is used. Optional.

Child Elements

Element	Description
<cookieHandler>	Configures the cookie handler used by the SAM. Optional.
<serviceCertificate>	Configures the certificate that is used to encrypt and decrypt tokens. Optional.
<wsFederation>	Configures the WS-Federation Authentication Module (WSFAM). Optional.

Parent Elements

Element	Description
<system.identityModel.services>	Configuration section for authentication using the WS-Federation protocol.

Remarks

The <federationConfiguration> element provides settings in two different scenarios:

When using WS-Federation in a passive Web application, the element contains settings that configure the WSFederationAuthenticationModule (WSFAM) and the SessionAuthenticationModule (SAM). It also references the identity configuration to be used to configure security token handlers and certificates, and components like the claims authorization manager and the claims authentication manager.
When using the ClaimsPrincipalPermission or the ClaimsPrincipalPermissionAttribute class to provide claims-based access control in your code, the element references the identity configuration that configures the claims authorization manager and policy that is used to make authorization decisions. This is true, even in scenarios that are not passive Web scenarios; for example, Windows Communication Foundation (WCF) applications or an application that is not Web-based. If the application is not a passive Web application, the <claimsAuthorizationManager> element (and its child policy elements, if present) of the identity configuration referenced by the <federationConfiguration> element are the only settings applied. All others are ignored.

Regardless of the scenario, the runtime loads the default federation configuration. The behavior is defined as follows:

If there is no <federationConfiguration> element present, the runtime creates a federation configuration and populates it with default values. This default federation configuration will reference the default identity configuration.
If a single <federationConfiguration> element is present, it is the default federation configuration regardless of whether it is named or unnamed. If its identityConfiguration attribute is specified, the named identity configuration is referenced; otherwise, the default identity configuration is referenced.
If an unnamed <federationConfiguration> element is present, it is the default federation configuration. If its identityConfiguration attribute is specified, the named identity configuration is referenced; otherwise, the default identity configuration is referenced.
If multiple named <federationConfiguration> elements are present and no unnamed <federationConfiguration> element is present, an exception is thrown.

Typically, only a single <federationConfiguration> section is defined. This section is the default federation configuration. You may specify multiple, uniquely-named <federationConfiguration> elements; however, in this case, if you want to load a federation configuration other than the unnamed one, you must provide a handler for the. FederationConfigurationCreated event and set the FederationConfigurationCreatedEventArgs.FederationConfiguration property inside the handler to a FederationConfiguration object initialized with values from the appropriate <federationConfiguration> element in the configuration file.

The <federationConfiguration> element is represented by the FederationConfigurationElement class. The configuration object itself is represented by the FederationConfiguration class. A single FederationConfiguration instance is set on the FederatedAuthentication.FederationConfiguration property and provides federated configuration for the application.

Example

The following XML shows a <federationConfiguration> element that specifies settings for the WSFAM and specifies that the default cookie handler (an instance of the ChunkedCookieHandler class) be used by the SAM.

Warning

In this example, neither the cookie handler nor WSFAM are required to use HTTPS. This is because the requireHttps attribute on the <wsFederation> element and the requireSsl attribute on the <cookieHandlerElement> are false. These settings are not recommended for most production environments as they may present a security risk.

<system.identityModel.services>  
  <federationConfiguration>  
    <wsFederation passiveRedirectEnabled="true"
      issuer="http://localhost:15839/wsFederationSTS/Issue"
      realm="http://localhost:50969/" reply="http://localhost:50969/"
      requireHttps="false"
      signOutReply="http://localhost:50969/SignedOutPage.html"
      signOutQueryString="Param1=value2&Param2=value2"
      persistentCookiesOnPassiveRedirects="true" />  
    <cookieHandler requireSsl="false" />  
  </federationConfiguration>  
</system.identityModel.services>

Share via