Federated Authentication Configuration

  • Article

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

The following elements configure federation for a Windows® Identity Foundation (WIF) RP application.

federatedAuthentication Element

The settings contained in this element are used to configure the WSFederationAuthenticationModule (FAM) and the SessionAuthenticationModule (SAM). The FederatedAuthentication class contains properties that reference the ASP.NET modules.

Syntax:

<microsoft.identityModel>
    <service>
        <federatedAuthentication enabled=Boolean>
            <wsFederation authenticationType=String
                          freshness=String
                          homeRealm=String(URI)
                          issuer=String(URI)
                          passiveRedirectEnabled=Boolean
                          persistentCookiesOnPassiveRedirects=Boolean
                          policy=String(URI)
                          realm=String(URI)
                          reply=String(URI)
                          request=String(URI)
                          requestPtr=String(URI)
                          resource=String(URI)
                          requireHttps=Boolean
                          signInQueryString=String
                          signOutQueryString=String
                          signOutReply=String(URL) />
            <cookieHandler mode="Chunked||Custom||Default"
                           domain=String
                           hideFromScript=Boolean
                           name=String
                           path=Path
                           requireSsl=Boolean
                           persistentSessionLifetime=TimeSpan">
                <chunkedCookieHandler size=Integer />
                <customCookieHandler type="MyNamespace.MyCustomCookieHandler, MyAssembly" />
            </cookieHandler>
        </federatedAuthentication>
    </service>
</microsoft.identityModel>

Parent Element: <Service>

Child Elements:

  • <wsFederation>

  • <cookieHandler>

Attributes:

Attribute Name Type Description

enabled

Boolean

Controls whether the module added to the ASP.NET pipeline is enabled so that it actively processes each request. The specific task each module performs depends on the module that is added in the pipeline. The default is “false”.

Example:

    <federatedAuthentication enabled="true">
        <wsFederation authenticationType="wauth"
                      freshness="45"
                      homeRealm="http://homeRealm"
                      issuer="i"
                      passiveRedirectEnabled="true"
                      persistentCookiesOnPassiveRedirects="true"
                      policy="http://policy"
                      realm="http://realm"
                      reply="http://reply"
                      request="http://request"
                      requestPtr="http://requestPtr"
                      resource ="http://resource"
                      requireHttps="true"
                      signInQueryString="abc=xyz"
                      signOutQueryString="def=uvw"
                      signOutReply="http://signoutreply" />
        <cookieHandler mode="Default"
                       domain="example.com"
                       hideFromScript="true"
                       name="FedAuth"
                       path="/"
                       requireSsl="true"
                       persistentSessionLifetime="60"/>
    </federatedAuthentication>

wsFederation Element

Defines parameter settings for a WS-Federation protocol security token service (STS). Configures settings for the WSFederationAuthenticationModule class.

Syntax:

<microsoft.identityModel>
    <service>
        <federatedAuthentication>
            <wsFederation authenticationType=String
                          freshness=String
                          homeRealm=String(URI)
                          issuer=String(URI)
                          passiveRedirectEnabled=Boolean
                          persistentCookiesOnPassiveRedirects=Boolean
                          policy=String(URI)
                          realm=String(URI)
                          reply=String(URI)
                          request=String(URI)
                          requestPtr=String(URI)
                          resource=String(URI)
                          requireHttps=Boolean
                          signInQueryString=String
                          signOutQueryString=String
                          signOutReply=String(URL) />
        </federatedAuthentication>
    </service>
</microsoft.identityModel>

Parent Element: <federatedAuthentication>

Child Elements: none

Attributes:

Attribute Name Type Description

authenticationType

String

The request wauth type. The default is an empty string.

freshness

String

The value of the required freshness. The default is an empty string.

homeRealm

String

The home realm of the Identity Provider. The default is an empty string.

issuer

String

The URI of the token issuer. The default is an empty string.

policy

String

The URI of the relevant policy. The default is an empty string.

realm

String

The URI of requesting realm. The default is an empty string.

reply

String

The URI of the address to reply to. The default is an empty string.

request

String

The URI of WS-Federation request. The default is an empty string.

requestPtr

String

The URI of the WS-Federation request pointer. The default is an empty string.

resource

String

The URI of the WS-Federation resource value. The default is an empty string.

requireHttps

Boolean

Controls whether the module will only redirect a secure URL for the STS. The default is “true”.

passiveRedirectEnabled

Boolean

Controls whether the module is enabled to automatically redirect unauthorized requests to an STS. The default is “false”.

persistentCookiesOnPassiveRedirects

Boolean

Specifies whether persistent cookies are issued when the module is enabled to initiate WS-Federation passive protocol redirects. The default is “false”.

signInQueryString

String

Specifies application defined parameters for the sign in request URL. The default is an empty string.

signOutQueryString

String

Specifies application defined parameters for the sign out request URL. The default is an empty string.

signOutReply

String

Specifies the URL to return to following sign out.

Example:

    <wsFederation authenticationType="wauth"
                  freshness="45"
                  homeRealm="http://homeRealm"
                  issuer="i"
                  passiveRedirectEnabled="true"
                  persistentCookiesOnPassiveRedirects="true"
                  policy="http://policy"
                  realm="http://realm"
                  reply="http://reply"
                  request="http://request"
                  requestPtr="http://requestPtr"
                  resource ="http://resource"
                  requireHttps="true"
                  signInQueryString="abc=xyz"
                  signOutQueryString="def=uvw"
                  signOutReply="http://signoutreply" />

cookieHandler Element

Configures the CookieHandler that is responsible for reading and writing raw cookies at the HTTP protocol level. The SessionAuthenticationModule uses the cookie handler to read and write cookies. You can configure either a ChunkedCookieHandler or a custom cookie handler derived from the CookieHandler class. This element sets the CookieHandler property.

Syntax Element:

<microsoft.identityModel>
    <service>
        <federatedAuthentication>
            <cookieHandler mode="Chunked||Custom||Default"
                           domain=String
                           hideFromScript=Boolean
                           name=String
                           path=Path
                           requireSsl=Boolean
                           persistentSessionLifetime=TimeSpan">
                <chunkedCookieHandler size=Integer />
                <customCookieHandler type="MyNamespace.MyCustomCookieHandler, MyAssembly" />
            </cookieHandler>
        </federatedAuthentication>
    </service>
</microsoft.identityModel>

Parent Element: <federatedAuthentication>

Child Elements:

  • <chunkedCookieHandler>

  • <customCookieHandler>

Attributes:

Attribute Name Type Description

mode

CookieHandlerMode

Controls the kind of cookie handler used by the SAM. The following values may be used:

  • “Default” — The same as “Chunked”.

  • “Chunked” — Uses an instance of the ChunkedCookieHandler class. This cookie handler ensures that individual cookies do not exceed a set maximum size. It accomplishes this by potentially "chunking" one logical cookie into a number of cookies on-the-wire.

  • “Custom” — Uses an instance of a custom class derived from CookieHandler. This class is referenced by the <customCookieHandler> element.

The default is “Default”.

domain

String

The domain value for any cookies written. The default is “”.

hideFromScript

Boolean

Controls whether the "HttpOnly" flag is emitted for any cookies written. Certain web browsers honor this flag by keeping client-side script from accessing the cookie value. The default is “true”.

name

String

Specifies the base name for any cookies written. The default is “FedAuth”.

path

String

Specifies the path value for any cookies written. The default is “HttpRuntime.AppDomainAppVirtualPath”.

requireSsl

Boolean

Specifies whether the "Secure" flag is emitted for any cookies written. If this value is set, the sign-in session cookies will only be available over HTTPS. The default is “true”.

persistentSessionLifetime

TimeSpan

Specifies the lifetime of persistent sessions. If zero, transient sessions are always used. The default value is 30 days. For more information about how to specify a TimeSpan value, see Timespan Values.

Example:

    <cookieHandler mode="Default"
                   domain="example.com"
                   hideFromScript="true"
                   name="FedAuth"
                   path="/"
                   requireSsl="true"
                   persistentSessionLifetime="60"/>

chunkedCookieHandler Element

Configures the ChunkedCookieHandler. This element may only be present if the mode attribute of the <cookieHandler> element is “Default” or “Chunked”.

Syntax:

<microsoft.identityModel>
    <service>
        <federatedAuthentication>
            <cookieHandler mode="Chunked||Default">
                <chunkedCookieHandler size=Integer />
            </cookieHandler>
        </federatedAuthentication>
    </service>
</microsoft.identityModel>

Parent Element: <cookieHandler>

Child Elements: none

Attributes:

Attribute Name Type Description

chunkSize

Int32

The maximum size, in characters, of the HTTP cookie data for any one HTTP cookie. Care must be taken when adjusting the chunk size. Web browsers have different limits on the size of cookies and number allowed per domain. For example, the original Netscape specification stipulated these limits: 300 cookies total, 4096 bytes per cookie header (including metadata, not just the cookie value), and 20 cookies per domain.

Example:

    <cookieHandler mode="Chunked">
        <chunkedCookieHander size=2000/>
    </cookieHandler>

customCookieHandler Element

References a custom cookie handler type. This type must be derived from the CookieHandler class. This element may only be present if the mode attribute of the <cookieHandler> element is “Custom”.

Syntax:

<microsoft.identityModel>
    <service>
        <federatedAuthentication>
            <cookieHandler mode="Custom">
                <customCookieHandler type="MyNamespace.MyCustomCookieHandler, MyAssembly" />
            </cookieHandler>
        </federatedAuthentication>
    </service>
</microsoft.identityModel>

Parent Element: <cookieHandler>

Child Elements: none

Attributes:

Attribute Name Description

type

A custom type that derives from the CookieHandler class. For more information about how to specify the type attribute, see Custom Type References.

Example:

    <cookieHandler mode="Custom">
        <customCookieHander type="MyNamespace.MyCustomCookieHandler, MyAssembly" />
    </cookieHandler>

See Also

Reference

FederatedAuthentication
WSFederationAuthenticationModule
SessionAuthenticationModule

Concepts

WS-Federated Authentication Module Overview