SAML SP for ASP.NET application integration
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 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 Windows 2003 : Windows 2008/2012 : |
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. |
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. |
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. |
ServiceProvider.SessionStateBehavior | 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). |
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
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
- 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- define
HttpApplication.Error event handler
(See Listing 9) OR - define error handling with customErrors tag in
web.config
-–file (see Listing 10)
- define
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