The Service Provider software package contains a template web.xml deployment descriptor. Use this file as a reference when integrating the SAML Service Provider with your web application.

Listing 1.Reference web.xml deployment descriptor

<?xml version="1.0" encoding="iso-8859-1"?><web-app xmlns="http://java.sun.com/xml/ns/j2ee" version="2.4">
     <filter>
        <filter-name>ServiceProviderFilter</filter-name>
        <filter-class>com.ubisecure.saml2.sp.servlet.ServiceProviderFilter</filter-class>
    </filter>
     <filter-mapping>
        <filter-name>ServiceProviderFilter</filter-name>
        <url-pattern>/*</url-pattern>
    </filter-mapping>
     <servlet>
        <servlet-name>ServiceProviderServlet</servlet-name>
        <servlet-class>com.ubisecure.saml2.sp.servlet.ServiceProviderServlet</servlet-class>
        <load-on-startup>0</load-on-startup>
    </servlet>
     <servlet-mapping>
        <servlet-name>ServiceProviderServlet</servlet-name>
        <url-pattern>/spsso/*</url-pattern>
    </servlet-mapping>
 </web-app>

ServiceProviderServlet

This servlet manages the SAML protocol messaging with the Ubisecure IDP. The name of the servlet is ServiceProviderServlet and the servlet is bound to the path /spsso/*.

Listing 2. ServiceProviderServlet configuration in web.xml

<servlet>
	<servlet-name>ServiceProviderServlet</servlet-name>
	<servlet-class>com.ubisecure.saml2.sp.servlet.ServiceProviderServlet</servlet-class>
	<load-on-startup>0</load-on-startup>
</servlet> 
<servlet-mapping>
	<servlet-name>ServiceProviderServlet</servlet-name>
	<url-pattern>/spsso/*</url-pattern>
</servlet-mapping>

NOTE: Do not use any filters in the URL pattern where the ServiceProviderServlet is bound (/spsso/*).

ServiceProviderFilter

This filter controls access to the resources of the application and requires authenticated access to the controlled resources. The default mapping of the filter is /{*}.

Listing 3. ServiceProviderFilter configuration in web.xml

<filter>
	<filter-name>ServiceProviderFilter</filter-name>
	<filter-class>com.ubisecure.saml2.sp.servlet.ServiceProviderFilter</filter-class>
</filter> 
<filter-mapping>
	<filter-name>ServiceProviderFilter</filter-name>
	<url-pattern>/*</url-pattern>
</filter-mapping>

UbiloginSAMLPrincipal

The application may query information about the authenticated user using the standard Java Servlet API of HttpServletRequest.getUserPrincipal. This method returns an object of type UbiloginSAMLPrincipal for authenticated requests that passed ServiceProviderFilter.

Listing 4. Using HttpServletRequest.getUserPrincipal to access UbiloginSAMLPrincipal

HttpServletRequest request = ...;
if(!(request.getUserPrincipal() instanceof UbiloginSAMLPrincipal)) {
    throw new ServletException("Not authenticated");
}
UbiloginSAMLPrincipal principal = (UbiloginSAMLPrincipal) request.getUserPrincipal();

The UbiloginSAMLPrincipal is also available as a request attribute using the ServletRequest.getAttribute API. The name of the request attribute is "com.ubisecure.saml2.sp.principal.UbiloginSAMLPrincipal.UserPrincipal".
This may be useful for example when request wrapping has been disabled (see Request wrapper ).

Listing 5. Using ServletRequest.getAttribute to access UbiloginSAMLPrincipal

HttpServletRequest request = ...;
UbiloginSAMLPrincipal principal = 
  (UbiloginSAMLPrincipal) request.getAttribute(
	"com.ubisecure.saml2.sp.principal.UbiloginSAMLPrincipal.UserPrincipalcom.ubisecure.saml2.sp.servlet.ServiceProviderFilter.UserPrincipal#ServiceProviderServlet"
  );

Please refer to the API documentation for details on the UbiloginSAMLPrincipal object.

Request Flow of the Service Provider


Figure 1. SAML protocol sequence diagram

A user requests a resource in the web application.
ServiceProviderFilter intercepts the request and attempts to validate the user's authentication session.
ServiceProviderFilter redirects the user to ServiceProviderServlet, which in turn generates an authentication request to the IDP by forwarding the user to the IDP.
The IDP authenticates the user and redirects the user back to ServiceProviderServlet.
ServiceProviderServlet creates an authentication session for the user and redirects the user to the original resource from step 1.
ServiceProviderFilter again intercepts the request and now successfully validates the user's authentication session.
ServiceProviderFilter passes the request through to the resource.

Logout

Logout procedure will start if user is redirected to the Service Providers single logout end point. The single logout end point URL is always /spsso/saml2/SingleLogoutService under the application context path.

A return URL can be passed to the logout service with the request parameter returnurl. After logout is complete, the user will be redirected to the path specified. The return URL must contain the application context if not root. The returnurl should typically be visible to users who are not currently logged in, otherwise the user will be redirected to the identity provider again for authentication.

A logout link can be constructed as a static html link if the context path of the application is fixed and known.

Listing 6. Static logout link

http://www.example.com/app1/spsso/saml2/SingleLogoutService?returnurl=/app1/logoutcompleted.jsp

Listing 7 below shows a sample JSTL code for a logout link.

Listing 7. Sample JSTL code for dynamically generated logout link

<a href="<c:url value='/spsso/saml2/SingleLogoutService'>
<c:param name='returnurl' value='${pageContext.request.contextPath}'/>
</c:url>">Logout</a>

Logout from the application will initiate single logout at the IDP. The IDP will execute the logout process for other active sessions at other SPs.

Disabling Single Logout

To disable single logout from the SP to IDP, remove the SingleLogoutService endpoint(s) from the IDP metadata using a text editor and restart the application.

To disable backchannel logout from the SP to the IDP, use the following –disable SingleLogoutService flag when generating the SP identity using the ubisaml2.jar command.

Listing 8. Disable backchannel SingleLogoutServicelogout at SP

-disable SingleLogoutService

Alternatively, it is possible to disable the single logout service of an existing SP integration from the IDP without access to the application. This is done by removing the SingleLogoutService endpoint(s) from the SP metadata registered on the IDP using a text editor and then reactivating the application at the IDP by uploading the modified SP metadata again.

SOAP Backchannel Logout

Logout using SOAP binding is supported by default if available at the IDP. This enables a faster logout experience without browser redirects.

NOTE: SOAP backchannel logout requires outbound application initiated traffic through firewalls between the SP and IDP. SOAP backchannel logout is enabled by default.

Some SAML deployment profiles do not support backchannel logout. To disable all backchannel logout functionality from the Ubisecure SSO IDP to the SP, the setting LiteNoBackChannel [PS1] must be added to the uas.properties file of the IDP. After modification, the application must be redeployed using tomcat/update.cmd or tomcat/update.sh

Listing 9. Disable backchannel logout at IDP

# ubilogin-sso\ubilogin\webapps\uas\WEB-INF\uas.properties
# saml interoperability features
com.ubisecure.ubilogin.uas.saml2.compatibility = LiteNoBackChannel

To disable SOAP backchannel logout for an individual SAML SP, set the LiteNoBackChannel compatibility flag in the SP’s identity.properties file. Note that in order to fully disable backchannel messages for the individual agent, it is also necessary to configure the SAML SP on the IDP end accordingly. This can be done by generating new SAML SP metadata and uploading it to the SAML SP’s IDP configuration. It is also possible to separately specify compatibility flags in the management application.

Listing 10. Open identity.properties file in a text editor. Add the following line to the file:

com.ubisecure.ubilogin.uas.saml2.compatibility = LiteNoBackChannel

Browser not supported