Customizing the AD FS 2.0 Sign-In Pages Using Web.config

Article
10/19/2016

This topic shows how to customize the Active Directory® Federation Services (AD FS) 2.0 Sign-In Pages by using web.config. Note that the guidance in this topic involves the user experience, not the security of the Sign-In Pages.

Presentation Settings

The presentation settings are under the <appSettings> element. The following settings can be customized:

logo. If this element is present, the specified image is displayed on all pages. You can add this element as follows:
```
<add key="logo" value="logo.png" />  
```
The value attribute specifies the path to the image file. The recommended image size is 600 pixels wide and 100 pixels high.
displayConsent. If this element is present, a SAML consent drop-down list is rendered in the IdpInitiatedSignOn.aspx page. You can add this element as follows:
```
<add key="displayConsent" />  
```
displayExceptions. If this element is present, the error page displays the exception message. You can add this element as follows:
```
<add key="displayExceptions" />  
```
If this element is omitted, the error page displays a generic error message.

Behavior Settings

The behavior settings are under the <microsoft.identityServer.web> element. The following settings can be customized:

Persist Identity Provider Selection. This element specifies how long to save the user’s selection of the Identity Provider STS (IP-STS). By default, the selection is stored in a persistent cookie for 30 days. This saves the user from having to specify the IP-STS every time he or she signs in. The following element saves the selection for 90 days:
```
<persistIdentityProviderInformation enabled="true" lifetimeInDays="90" />  
```
Set the enabled attribute to false to track only the Identity Provider selection for the current browser session. In that case, you do not have to specify the lifetimeInDays attribute.
```
<persistIdentityProviderInformation enabled="false" />  
```
Enable Single Sign On (SSO). This element specifies whether SSO is enabled. By default, it is enabled. When enabled, AD FS 2.0 saves an SSO session cookie with the user’s Web browser. This cookie is used to avoid prompting the user for credentials each time he or she signs in to a different RP application. For an example of why SSO is useful, see Identity Silos (https://go.microsoft.com/fwlink/?LinkId=205505) in the Windows® Identity Foundation (WIF) documentation. The following element disables SSO:
```
<singleSignOn enabled="false" />  
```
Error page. This element specifies the page that handles errors. The following element sets the error page to Error.aspx:
```
<error page="Error.aspx" />  
```
Context. When AD FS 2.0 acts as an RP-STS and sends a request to an IP-STS, this element specifies whether to encode the original request as a cookie or as part of the parameter. For more information about the difference between an IP-STS and an RP-STS, see What is an IP-STS and what is an RP-STS? (https://go.microsoft.com/fwlink/?LinkID=205503). The following element encodes the original request as a cookie, which offers better privacy.
```
<context hidden="true" />  
```
The following element encodes the original request as part of the wctx parameter, which does not require cookies.
```
<context hidden="false" />  
```
Authentication handlers. This element specifies the authentication handlers that AD FS 2.0 uses to authenticate incoming requests. For example, the following configuration accepts only requests that require SSL client certificates, and rejects requests that require other authentication methods:
```
<localAuthenticationTypes>  
  <add name="TlsClient" page="auth/sslclient/" />  
</localAuthenticationTypes>  
```
For more information about how to configure authentication handlers, as well as example configurations, see Authentication Handler Overview.
Common domain cookie. A common domain cookie stores a list of recently visited Claims Providers (also called Identity Providers), as described in Section 4.3.1 of Profiles for the OASIS Security Assertion Markup Language (SAML) V2.0 (https://go.microsoft.com/fwlink/?LinkId=205506). It is recommended that you enable common domain cookies by including the <commonDomainCookie> element in the web.config file.
1. The writer attribute of the <commonDomainCookie> element specifies the address of the writer service that a Claims Provider uses to set the common domain cookie once it has authenticated a user. This address should be a valid URL.
2. The reader attribute of the <commonDomainCookie> element specifies the address of the reader service that a claims-aware service (also called a Service Provider) uses to get the list of Claims Providers that it should present to the user. This address should be a valid URL.
The following configuration enables the use of common domain cookies and specifies writer and reader services as described previously.
```
<commonDomainCookie writer="https://www.contoso.com/writer.aspx" reader="https://www.contoso.com/reader.aspx">  
```
Important

The stock CDC.Web sample does not have access to the policy store. This means that it cannot determine whether a given relying party (RP) is trusted or not, and it might redirect the user to a malicious relying party. To mitigate this issue, encode the list of trusted RPs into the CDC Web site, either by hard-coding the list or by using the PowerShell APIs to programmatically access the list of trusted RPs. For more information about the PowerShell APIs see AD FS 2.0 PowerShell API Overview.
Home realm discovery page. This element points to a home realm discovery page where users select their home realm for the purpose of authentication. The following example specifies “HomeRealmDiscovery.aspx” as the home realm discovery page:
```
<homeRealmDiscovery page="HomeRealmDiscovery.aspx" />  
```
The page attribute is required. If this element is omitted, the home realm is chosen automatically, which depends on a number of factors, such as the persistent Identity Provider cookie or whether local authentication is enabled.
Federation protocol. This element specifies the federation protocols that AD FS 2.0 accepts. Set the saml attribute to enable or disable federation using the SAML V2.0 protocol; set the wsFederation attribute to enable or disable federation using the WS-Federation protocol. By default, both the WS-Federation and the SAML V2.0 protocols are enabled; you can set one of the attributes to false to disable that protocol. Omitting an attribute reverts to the default behavior for that protocol, which is to enable it. Omitting the <acceptedFederationProtocols> element entirely reverts to the default behavior for both protocols, which means that they are both enabled. You can also set one or both of the attributes to true to explicitly enable a protocol. Although this is not necessary, it is good practice as it makes the configuration file more readable. The following example specifies support for both the SAML V2.0 and WS-Federation protocols (this is the default):
```
<acceptedFederationProtocols saml="true" wsFederation="true" />  
```
The following example specifies support for the SAML V2.0 protocol only. This is achieved by disabling the WS-Federation protocol. (The saml attribute can be set to true or it can be omitted as in this example).
```
<acceptedFederationProtocols wsFederation="false" />  
```

Internet Information Services (IIS) Handlers

The <handlers> element under the <system.webServer> element configures the handlers that are loaded by Internet Information Services (IIS) 7 and later versions to process requests. By default, the AD FS 2.0 handlers are configured under this element in the web.config file for the Sign-In Pages. Removing a handler from this configuration will cause authentication to fail for that type of authentication. The following XML shows the default handler configuration for the Sign-In Pages.

<system.webServer>  
    <handlers>  
      <add name="BasicAuthHandler" path="auth/basic/" verb="*" type="Microsoft.IdentityServer.Web.BasicEndpointHandler, Microsoft.IdentityServer, Version=6.1.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35" preCondition="integratedMode,runtimeVersionv2.0" />  
      <add name="PassiveProtocolHandler" path="/adfs/ls/" allowPathInfo="true" verb="*" type="Microsoft.IdentityServer.Web.PassiveProtocolHandler, Microsoft.IdentityServer, Version=6.1.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35" preCondition="integratedMode,runtimeVersionv2.0" />  
      <add name="TlsAuthHandler" path="auth/sslClient/" verb="*" type="Microsoft.IdentityServer.Web.TlsEndpointHandler, Microsoft.IdentityServer, Version=6.1.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35" preCondition="integratedMode,runtimeVersionv2.0" />  
      <add name="WindowsAuthHandler" path="auth/integrated/" verb="*" type="Microsoft.IdentityServer.Web.WindowsEndpointHandler, Microsoft.IdentityServer, Version=6.1.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35" preCondition="integratedMode,runtimeVersionv2.0" />  
    </handlers>  
    <validation validateIntegratedModeConfiguration="false" />  
  </system.webServer>

Customizing the AD FS 2.0 Sign-In Pages Using Web.config

Presentation Settings

Behavior Settings

Internet Information Services (IIS) Handlers

Additional resources