Configuring web.config

The Service Provider software package contains a example template web.config ASP.NET web application configuration files. Use these files as reference when integrating the SAML Service Provider with your web application. The files are located by default at C:\Program Files\Ubisecure\Ubisecure.SAML2.ServiceProvider\Samples\WebApplication*\web.config.

Listing 2 presents an example configuration for IIS5 or IIS7/7.5/8 running in Classic Mode.

Listing 3 presents an example configuration for IIS7/7.5/8 running in Pipeline Mode.

Please check the version numbers listed below (1.3.0.0) match the version number of the SAML SP installation package Release Notes document.

The following application settings are available in the web.config file under <appSettings> section:

Setting	Definition
`ServiceProvider.EntityID`	Contains the SAML Service Provider entity ID. This value is shown in Figure 3 in SAML SP for ASP.NET service provider configuration - SSO must be used at this point. In our example settings, " `urn:uuid:54dd7c51-75f5-3d16-e319c757dd09` " will replace the text "Insert entityID".This value is OPTIONAL, however, if `ServiceProvider.EntityID` has not been specified, `ServiceProvider.StorePath` must be set.
`ServiceProvider.ApplicationData`	Specifies the path to the Service Provider configuration directory. Paths relative to the application are possible, such as `~/App_Data/sp`. This value is OPTIONAL. It is only read if `ServiceProvider.EntityID` has been specified. If no value is defined, by default, the following value is used: Windows 2003 : `%ALLUSERSPROFILE%\Application Data\Ubisecure\Ubisecure.SAML2.ServiceProvider` Windows 2008/2012 : `C:\ProgramData\Ubisecure\Ubisecure.SAML2.ServiceProvider`
`ServiceProvider.StorePath`	Contains a path to folder containing configuration information. It is only used when it is desirable to store all application configuration information outside of an application – for example to enable the same application to be used in different environments (development, test, production). This value specifies the path to folder containing a single `identity.properties` file. Paths relative to the application are possible, such as `~/App_Data/sp`. This value is OPTIONAL, however, if `ServiceProvider.StorePath` is specified then `ServiceProvider.EntityID` and `ServiceProvider.ApplicationData` are ignored.
`ServiceProvider.UsernameAttribute`	Contains the name of a SAML Attribute which will be used for the principal name. By default, the SAML NameID value is used. OPTIONAL. See Defining the User Name Attribute in SAML SP for ASP.NET customization - SSO.
`ServiceProvider.Role`	Contains the name of a default role which will be assigned to all authenticated users. OPTIONAL. See Membership and Role Providers in SAML SP for ASP.NET customization - SSO.
`ServiceProvider.Netmask`	Contains the netmask to configure tolerance for user agent address changes during the authentication process. MANDATORY. See Network address tolerance in SAML SP for ASP.NET customization - SSO.
`ServiceProvider.SessionStateBehavior`	Determines whether access to the ASP.Net session state is available during the SAML SP for ASP.Net events. Possible values are Required - Full read-write session state behavior is enabled for the request. Readonly - Read-only session state is enabled for the request. This means that session state cannot be updated. This value is OPTIONAL. Please note capitalization of the first character. Without this setting, access to the session state is not available. Changes to this value may be required if an application needs to save some custom session state using the HTTP session before authentication. The custom state information can be saved during the `AuthnRequestEvent` and then retrieved during the `LoginEvent`. NOTE: The SAML2 RelayState value is used internally by SAML SP for ASP.Net for session state between the IDP and SP. Applications cannot set or read this RelayState. Application session management should be done using the ASP.Net HTTP session or other session management techniques (e.g. cookie).

When the web.config file has been correctly configured, attempts to access the web application result in a browser redirection to the IDP.

The SAML SP Metadata is available publicly in XML format from the address /spsso.ashx/saml2/metadata.xml. See Listing 1 for the example address.

Listing 1. Address for SAML SP Metadata in XML format

https://sp.example.com/webapp/spsso.ashx/saml2/metadata.xml

Listing 2. Reference web.config configuration file using IIS6 or IIS7/7.5 Classic Mode

Listing 2. Reference web.config configuration file using IIS6 or IIS7/7.5 Classic Mode

<?xml version="1.0"?>
<!--
	Please Note!
	This web.config file is NOT a complete configuration file for your web application.
	You may however use this file as reference when applying configuration
	settings to your web application.
-->
<configuration>

	<system.diagnostics>
		<switches>
			<add name="Ubisecure.SAML2" value="Information"/>
			<add name="Ubisecure.SAML2.ServiceProvider" value="Information"/>
		</switches>
	</system.diagnostics>

	<appSettings>
		<!-- either ServiceProvider.EntityID or ServiceProvider.StorePath is required -->
		<!-- <add key="ServiceProvider.EntityID" value=" Insert entityID "/> -->
		<!-- <add key="ServiceProvider.StorePath" value=" INSERT PATH TO SETTINGS DIRECTORY "/> -->

		<!-- ServiceProvider.Role specifies a default role for all users -->
		<!-- <add key="ServiceProvider.Role" value=""/> -->

		<!-- ServiceProvider.UsernameAttribute gets the user's name from an attribute -->
		<!-- <add key="ServiceProvider.UsernameAttribute" value=""/> -->

		<!-- ServiceProvider.Netmask adjusts the network address tolerance -->
		<!-- <add key="ServiceProvider.Netmask" value="255.255.255.255"/> -->
	</appSettings>

	<system.web>

		<!-- If Ubisecure.SAML2.ServiceProvider is not already installed in .Net global assembly cache. the
following section is required -->
			<compilation>
			<assemblies>
				<add assembly="Ubisecure.SAML2.ServiceProvider, Version=1.23.0.0, Culture=neutral,
					PublicKeyToken=e76714ff33c956b5"/>
			</assemblies>
		</compilation>

		<authentication mode="Forms" >
			<forms loginUrl="~/spsso.ashx"
					<!-- Inactivity timeout in minutes -->
					timeout="10"
					<!—Set true or false depending on desired inactivity timeout behaviour -->
					slidingExpiration="false"
			/>
		</authentication>

		<authorization>
			<deny users="?"/>
			<allow users="*"/>
		</authorization>

		<httpModules>
			<remove name="FormsAuthentication"/>
			<add name="ServiceProviderAuthentication"
				type="Ubisecure.SAML2.ServiceProvider.Security.ServiceProviderAuthenticationModule,
					Ubisecure.SAML2.ServiceProvider, Version=1.32.0.0, Culture=neutral,
					PublicKeyToken=e76714ff33c956b5"/>
		</httpModules>

	</system.web>

	<location path="spsso.ashx">

		<system.web>
			<httpHandlers>
				<clear/>
				<add verb="" path=""
					type="Ubisecure.SAML2.ServiceProvider.Security.ServiceProviderHandler,
						Ubisecure.SAML2.ServiceProvider, Version=1.23.0.0, Culture=neutral,
						PublicKeyToken=e76714ff33c956b5"/>
			</httpHandlers>
		</system.web>
	</location>
</configuration>

Listing 3. Reference web.config configuration file using IIS7/IIS7.5 integrated pipeline mode

Listing 3. Reference web.config configuration file using IIS7/IIS7.5 integrated pipeline mode

<?xml version="1.0"?>
<!--
	Please Note!
	This web.config file is NOT a complete configuration file for your web application.
	You may however use this file as reference when applying configuration
	settings to your web application.
-->
<configuration>

	<system.diagnostics>
		<switches>
			<add name="Ubisecure.SAML2" value="Information"/>
			<add name="Ubisecure.SAML2.ServiceProvider" value="Information"/>
		</switches>
	</system.diagnostics>

	<appSettings>
		<!-- either ServiceProvider.EntityID or ServiceProvider.StorePath is required -->
		<!-- <add key="ServiceProvider.EntityID" value=" Insert entityID "/> -->
		<!-- <add key="ServiceProvider.StorePath" value=" INSERT PATH TO SETTINGS DIRECTORY "/> -->

		<!-- ServiceProvider.Role specifies a default role for all users -->
		<!-- <add key="ServiceProvider.Role" value=""/> -->

		<!-- ServiceProvider.UsernameAttribute gets the user's name from an attribute -->
		<!-- <add key="ServiceProvider.UsernameAttribute" value=""/> -->

		<!-- ServiceProvider.Netmask adjusts the network address tolerance -->
		<!-- <add key="ServiceProvider.Netmask" value="255.255.255.255"/> -->
	</appSettings>

	<system.web>

		<authentication mode="Forms" >
			<forms loginUrl="~/spsso.ashx" slidingExpiration="true"/>
		</authentication>

		<authorization>
			<deny users="?"/>
			<allow users="*"/>
		</authorization>

	</system.web>

	<system.webServer>
		<modules>
			<remove name="FormsAuthentication"/>
			<add name="ServiceProviderAuthentication"
				type="Ubisecure.SAML2.ServiceProvider.Security.ServiceProviderAuthenticationModule,
					Ubisecure.SAML2.ServiceProvider, Version=1.23.0.0, Culture=neutral,
					PublicKeyToken=e76714ff33c956b5"/>
		</modules>
	</system.webServer>

	<location path="spsso.ashx">
		<system.webServer>
			<handlers>
				<clear/>
				<add name="ServiceProviderHandler"
					verb="" path=""
					type="Ubisecure.SAML2.ServiceProvider.Security.ServiceProviderHandler,
						Ubisecure.SAML2.ServiceProvider, Version=1.23.0.0, Culture=neutral,
						PublicKeyToken=e76714ff33c956b5"/>
			</handlers>
		</system.webServer>
	</location>
</configuration>

IAssertionIdentity

The application may query information about the authenticated user using the standard .NET API of HttpContext.User. This property returns an object of type IPrincipal when an authentication session has been established. If the user has not logged in, the identity will be null. Use the IPrincipal.Identity property to access the IAssertionIdentity object.

Listing 4. Using HttpContext.User to access IAssertionIdentity

IAssertionIdentity identity = HttpContext.Current.User.Identity as IAssertionIdentity;
if(identity == null)
{
	throw new HttpException("Access denied", 403);
}

Listing 5. Using HttpContext.User to access IAssertionIdentity in C#

<%@Page Language="C#"%>
<html xmlns="http://www.w3.org/1999/xhtml" >
<body>
	<p>Request.IsAuthenticated=<%= Request.IsAuthenticated %></p>
	<p>Context.User.Identity.Name=<%= HttpUtility.HtmlEncode(Context.User.Identity.Name) %></p>
	<p>Context.User.Type=<%= Context.User.GetType().FullName %></p>
	<p>Context.User.Identity.Type=<%= Context.User.Identity.GetType().FullName %></p>
	<p>
	[<a href="spsso.ashx/saml2/SingleLogoutService">Logout</a>]
	</p>
</body>
</html>

Inactivity Timeout

The inactivity timeout for an application is set in the Forms Authentication settings section of the web.config configuration file.

Listing 6. Timeout Settings in web.config

<authentication mode="Forms" >
	<forms loginUrl="~/spsso.ashx"
		<!-- Inactivity timeout in minutes. Must be set lower than the value in
		Ubilogin Server Management -->
		timeout="10"
		slidingExpiration="false"
	/>
</authentication>

timeout is used to specify a limited lifetime for the forms authentication session within ASP.NET. The default value is 30 minutes. slidingExpiration is set to true to enforce a sliding session lifetime. This means that the session timeout is periodically reset as long as a user stays active on the site. Both values should be set explicitly, as the default values of each have changed between different versions of IIS.

In general, slidingExpiration should be set to false and the timeout value set to less than the timeout value used in the Ubisecure Server Management application, to ensure that a request is regularly made to Ubisecure Authentication Server.

After this timeout has been reached, a request is made to the Ubisecure Authentication Server via spsso.ashx. If either of the Site's global or Web Application's Single Sign-On Session Timeout (minutes) value has been exceeded, re-authentication of the user is requested. Otherwise, no re-authentication is performed and these inactivity timeouts are also reset.

For more information on session timeouts, please refer to document SSO Timeout Configuration in Identity Server 8.2.

Logout

Logout procedure will start if the user is redirected to the single logout endpoint. The single logout endpoint URL is /spsso.ashx/saml2/SingleLogoutService relative to the applications context path. A relative return URL may optionally be specified with a request parameter ReturnUrl. If no ReturnUrl is specified, the user is returned to the application root.

Listing 7. SingleLogoutService

https://sp.example.com/webapp/spsso.ashx/saml2/SingleLogoutService

[<a href=" [https://sp.example.com/webapp/spsso.ashx/saml2/|https://sp.example.com/webapp/spsso.ashx/saml2/] ^
SingleLogoutService?ReturnUrl=/webapp/loggedout.htm ">Logout</a>

Ensure that the web.config file is configured so that anonymous users have access to the application root, or if a ReturnUrl is specified, to the path used in the ReturnUrl. Failure to allow access to this page for anonymous users will result in a loop.

To disable single logout for this application, remove the SingleLogoutService endpoints from the SP metadata file before registration with the IDP. To disable single logout to other applications, remove the SingleLogoutService endpoints from the IDP metadata file configured in Get the metadata of the Identity Provider in SAML SP for ASP.NET service provider configuration - SSO.

SingleLogout is available using HTTP-Redirect and HTTP-POST bindings.

REMOTE_USER style integrations

SAML SP for ASP.Net can be used to integrate ASP.Net and non- ASP.Net applications that require the REMOTE_USER value to be set to the user principal.

Ensure that the pipeline contains the Ubisecure "ServiceProviderModule". And the setting "Invoke only for requests to ASP.NET applications or managed handlers" is enabled.

The configuration of the source of the REMOTE_USER value is made in the ServiceProvider.username setting of the web.config file.

Protecting Static Resources

ASP.Net is configured by default to serve static resources without requiring authorization. Static resources include html, pdf, doc, image and other non ASP-files. If protection of static resources is required, IIS configuration changes are required.

The first method is to map file extensions for static files to the ASP.NET ISAPI Extension. As a result, requests for those static resources will be handled by ASP.NET.

The second method commonly used involves moving all the static content you wish to protect outside of your Web site and serve it via an ASP page.

Please refer to Microsoft's discussion on Using Forms Authentication to Protect Files at http://technet.microsoft.com/en-us/library/bb878098.aspx (third issue discussed in article).

Error handling in ASP.NET application

Error situations must be handled by the application. At the bare minimum, the application should show a generic error message. All error handling must be configured during the integration.

Examples of situations in which errors are returned from the UAS server:

The UAS is misconfigured
The requested authentication method is not available
The user aborts the login process by pressing the Cancel button
The SAML message is invalid, corrupted or otherwise does not pass validation
Client IP address changes during login in a way that violates the netmask setting

General principles in ASP.NET error handling with SAML SP for ASP.NET

SAML Response errors
- Handle errors while processing the SAML Response by defining a ServiceProviderAuthenticationModule.LoginError event handler (see Listing 8)
Other errors and errors when SAML Response error is not handled
In these situations, it is important to
- define HttpApplication.Error event handler (See Listing 9) OR
- define error handling with customErrors tag in web.config -–file (see Listing 10)

Examples

Listing 8. LoginError event handler in file global.asax

void ServiceProviderAuthentication_LoginError(object sender, Ubisecure.SAML2.ServiceProvider.Event.LoginErrorEventArgs e)
{
	Response.Redirect("~/Error.aspx");
}

Listing 9. Application_Error event handler in file global.asax

HttpApplication.Error event handler global.asax tiedostoon
	void Application_Error(object sender, EventArgs e)
	{
		Response.Redirect("~/Error.aspx");
	}

Listing 10. Generic custom LoginError event handler error configuration in file web.config

<system.web>
	<customErrors mode="On">
		<error statusCode="500" redirect="~/Error.aspx"/>
	</customErrors>
</system.web>

More information

HttpApplication.Error:

http://msdn.microsoft.com/en-us/library/system.web.httpapplication.error.aspx

customErrors Element:

https://msdn.microsoft.com/en-us/library/h0hfz6fc(v=vs.85).aspx

API Documentation

For complete technical descriptions of the API interface, please refer to the HTML document in the Docs subdirectory. By default, this is installed at:

Windows 2003:

C:\Program Files\Ubisecure\Ubisecure.SAML2.ServiceProvider\Docs \Ubisecure.SAML2.ServiceProvider.html

Windows 2008/2012:

C:\ProgramData\Ubisecure\Ubisecure.SAML2.ServiceProvider\Docs\Ubisecure.SAML2.ServiceProvider.html

Browser not supported