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.

...

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 Configurationservice provider configuration 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 Customizationcustomization.

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

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

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

...

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.

Code Block

language	text
theme	RDark
title	Listing 1. Address for SAML SP Metadata in XML format

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

Expand

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

Code Block

language	text	theme	RDark
title	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>

...

Expand

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

Code Block

language	text
theme	RDark
title	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.

Code Block

language	text	theme	RDark
title	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);
}

Code Block

language	text
theme	RDark
title	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.

Code Block

language	text
theme	RDark
title	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>

...

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.

Code Block

language	text
theme	RDark
title	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>

...

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

...

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.

...

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.

...

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

Code Block

language	text
theme	RDark
title	Listing 8. LoginError event handler in file global.asax

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

Code Block

language	text
theme	RDark
title	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");
	}

Code Block

language	text
theme	RDark
title	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:

httphttps://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:

Code Block

language	text	theme	RDark

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

Versions Compared

Old Version 1

New Version Current

Key

Configuring web.config

IAssertionIdentity

Inactivity Timeout

Logout

REMOTE_USER style integrations

Protecting Static Resources

Error handling in ASP.NET application

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

Examples

More information

API Documentation

Page Comparison

Versions Compared

Old Version 1

New Version Current

Key

Configuring web.config

IAssertionIdentity

Inactivity Timeout

Logout

REMOTE_USER style integrations

Protecting Static Resources

Error handling in ASP.NET application

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

Examples

More information

API Documentation