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
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 (184.108.40.206) 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
| ||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, " |
Specifies the path to the Service Provider configuration directory. Paths relative to the application are possible, such as
Windows 2003 :
Windows 2008/2012 :
| ||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 |
| ||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.|
| ||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.|
| ||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.|
Determines whether access to the ASP.Net session state is available during the SAML SP for ASP.Net events. Possible values are
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
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).
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.
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
The inactivity timeout for an application is set in the Forms Authentication settings section of the
web.config configuration file.
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.
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 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.
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.
SingleLogout is available using
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
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)
- Handle errors while processing the SAML Response by defining a
- Other errors and errors when SAML Response error is not handled
In these situations, it is important to
HttpApplication.Error event handler(See Listing 9) OR
- define error handling with customErrors tag in
web.config-–file (see Listing 10)
For complete technical descriptions of the API interface, please refer to the HTML document in the Docs subdirectory. By default, this is installed at: