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:

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.

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

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

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

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

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

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

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.

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

1. SAML Response errors
   • Handle errors while processing the SAML Response by defining a ServiceProviderAuthenticationModule.LoginError event handler (see Listing 8)
2. 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

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

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

<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