Modifying Source of User Principal and Roles

User Principal

By default, the user principal is taken from the SAML NameID value of the SAML response message received by the service provider from the Identity Provider. With a configuration change, the user principal value can be taken from an assertion attribute.
The SAML NameID value is typically one of

LDAP distinguished name listing user location in the Ubisecure Directory
Ubisecure User Mapping
transient identifier
persistent identifier

depending on the Name Mapping table used by the Agent. When no Transient Name Mapping table is used, the LDAP distinguished name is used by default.

For more information regarding Name Mapping, please refer to the SSO Management pages.

To force the use of an attribute for the user principal, set the init-param value username-attribute in the web.xml file to the name of the source attribute. In the example below, email address will be used. This attribute must be present in the authorization policy of the agent in Ubisecure Management and must be marked as a mandatory attribute.

Roles

By default, any roles received, as set in the Authorization Policy, are accessible to applications via the isInRole() helper function of the UbiloginSAMLPrincipal class. All roles defined in an Authorization Policy are added to the SAML response message in a multi-value attribute called "role". Typically no change is required.
In rare cases, it may be desirable to set the roles from the value of a different source attribute. To make the helper function isInRole() use a different source attribute, set the init-param value role-attribute in the web.xml file to the name of the source attribute. In the example below, entitlements attribute will be used. This attribute must be present in the authorization policy of the agent in Ubisecure Management.

Listing 1. Modifying source of User Principal and Roles via web.xml configuration

<servlet>
	<servlet-name>ServiceProviderServlet</servlet-name>
	<servlet-class>com.ubisecure.saml2.sp.servlet.ServiceProviderServlet</servlet-class>
	<load-on-startup>0</load-on-startup>
	<init-param>
		<param-name>listener-class</param-name>
		<param-value>demo.palvelu.PalveluEventListener</param-value>
	</init-param>
	<init-param>
		<param-name>username-attribute</param-name>
		<param-value>email</param-value>
	</init-param>
	<init-param>
		<param-name>role-attribute</param-name>
		<param-value>entitlements</param-value>
	</init-param>
</servlet>

The example code above also shows a defined listener-class value. See Event Handlers.

Network Address Tolerance

The SAML protocol uses the network address of the user for session tracking and message replay detection.

In many deployments however the network address of the user is not reliable because of Network Address Translation (NAT), HTTP Proxy and other network components. Use the netmask setting of the ServiceProviderServlet to adjust how the Service Provider relies on the network address.

Set the value to disabled to completely disable network address validation.

Listing 2. The netmask set to 255.255.255.0 in WEB-INF/web.xml

<servlet>
	<servlet-name>ServiceProviderServlet</servlet-name>
	<servlet-class>com.ubisecure.saml2.sp.servlet.ServiceProviderServlet</servlet-class>
	<init-param>
		<param-name>netmask</param-name>
		<param-value>255.255.255.0</param-value>
	</init-param> 
	<load-on-startup>0</load-on-startup>
</servlet>

Controlling Resource Access

The default ServiceProviderFilter pattern of /* requires authenticated access to all resources of the application. In other words, all initial requests made to the servlet will be redirected to the Ubisecure Authentication SSO Server for a sign in.

Use filter-mapping to specify the resources of your application that require authentication. Note that you may specify more than one filter-mapping setting in the web.xml deployment descriptor. In this way you can enable only certain paths or files to require authentication.

A typical approach is that the landing page of an application is excluded from the filter. On this page there is a link or button that directs the user to another file or path which is protected. In this way, the main page of the application can contain content for anonymous users. In the following example, only the directories /protected and /resources will require the user to have a valid single sign-on session.

Listing 3. Using the filter-mapping setting in WEB-INF/web.xml

<filter-mapping>
	<filter-name>ServiceProviderFilter</filter-name>
	<url-pattern>/protected/*</url-pattern>
</filter-mapping> 
<filter-mapping>
	<filter-name>ServiceProviderFilter</filter-name>
	<url-pattern>/resources/*</url-pattern>
</filter-mapping>

Note that when a page is not protected by the filter, the principal and attribute information is not available. To access principal and attribute information on a page that is available to both signed in and anonymous users, use the not-pattern feature.

The not-pattern setting of the ServiceProviderFilter is used to enable anonymous access to selected resources. This setting is a whitespace separated list of URL patterns.

In the following examples, the root, index.jsp and CSS directories will be accessible to both anonymous and logged in users. If the user has already logged to the application (for example, from another page protected by the filter), the page can display information about the user.

Listing 4. Using the not-pattern setting in WEB-INF/web.xml

<filter>
	<filter-name>ServiceProviderFilter</filter-name>
	<filter-class>com.ubisecure.saml2.sp.servlet.ServiceProviderFilter</filter-class>
	<init-param>
		<param-name>not-pattern</param-name>
		<param-value>
			/
			/index.jsp
			/css/*
		</param-value>
	</init-param> 
</filter>

Listing 5. Checking for a logged in or anonymous user in a jsp page

/* example part of a jsp page */ 

<c:set var="principal" value="${pageContext.request.userPrincipal}" />
<c:set var="authenticated" value="${ !(principal eq null ) && fn:contains(principal.class.name, 'Ubilogin') }"/> 
<c:choose>
<c:when test="${authenticated}">
<style type="text/css"> 
	/* I am an authenticated user and I can display information about the user */ 
</c:when>
<c:otherwise> 
	/* I am either an authenticated user or an anonymous user. */ 
</c:otherwise>
</c:choose>

A SAML SP can check from the IDP if there is an existing session, without requiring a interactive login. Please refer to the API documentation for use of the isPassive function. Alternatively, if the IDP is Ubisecure Authentication SSO Server, a number of resources on the server can be checked to see if the user has a valid active session. Please refer to the document Timeout configuration - SSO Guide for more information on checking of server session status.

Request Wrapper

All authenticated requests passing ServiceProviderFilter are wrapped by the SP to override the getUserPrincipal and other methods.

This is known to cause compatibility issues with some application servers.

Use the disable-request-wrapper setting of the ServiceProviderFilter to disable the wrapper functionality if you experience compatibility issues with your application server.

Listing 6. Using the disable-request-wrapper setting

<filter>
	<filter-name>ServiceProviderFilter</filter-name>
	<filter-class>com.ubisecure.saml2.sp.servlet.ServiceProviderFilter</filter-class>
	<init-param>
		<param-name>disable-request-wrapper</param-name>
		<param-value>true</param-value>
	</init-param> 
</filter>

Attribute Queries

Attribute Queries allow an application to query an Attribute Authority for user attributes at run time, after the initial authentication has been performed. The Attribute Authority may be a different party to the Identity Provider.

Typically Attribute Queries are used in special cases, where the size of the attributes exceeds practical limits of the assertion or where a trust relationship with a different provider is required. Most use cases of SAML SP do not require the use of Attribute Queries.

Attribute queries to an Attribute Authority are done with UbiloginServiceProvider-class. See the API-documentation for details on getting the current instance of UbiloginServiceProvider and using it.

Event Handlers

The Service Provider calls registered event listeners to notify the application of certain events during SAML protocol message processing.

Use the listener-class setting of the ServiceProviderServlet to register event listeners. An example is shown below.

Listing 7. Register an event listener using listener-class parameter in web.xml configuration

<servlet>
	<servlet-name>ServiceProviderServlet</servlet-name>
	<servlet-class>com.ubisecure.saml2.sp.servlet.ServiceProviderServlet</servlet-class>
	<load-on-startup>0</load-on-startup>
	<init-param>
		<param-name>listener-class</param-name>
		<param-value>com.example.listener.ExampleListener</param-value>
	</init-param>
</servlet>

Please refer to the API documentation for details on the event handler interfaces. The API documentation included as a html file in the distribution zip file.

LoginEventListener

This listener receives login, logout and login failure events.

The login event is triggered when a SAML Response message has been received and validated.

The logout event signals end of session for the user, in response to either SAML LogoutRequest or LogoutResponse messages.

Login failures may occur if the IDP sends a SAML Response with an invalid status code. This could happen for an example if the user clicks cancel at the IDP. To handle a failed authentication, the application should implement a LoginEventListener, which handles these errors (for an example by writing the error to log and redirecting the user back to a page that is not protected). See API-documentation for details on LoginErrorEvent.

The status codes that UAS returns are described in the SAML Core Specification, chapter 3.2.2.2. For example, if the user clicks Cancel in the Identity provider, the returned status codes are "urn:oasis:names:tc:SAML:2.0:status:Responder" and "urn:oasis:names:tc:SAML:2.0:status:AuthnFailed".

The LoginErrorEvent handler must be implemented during integration for all end user applications. Without a LoginErrorEvent handler, the application will generate an exception when login errors occur.

AuthnRequestEventListener

This listener receives an event when an AuthnRequest message is being generated. The event handler is allowed to customize certain properties of the AuthnRequest message.

MessageEventListener

This listener receives notifications when SAML messages are sent or received by the Service Provider. The event handler is allowed to reject received messages.

If the application wants to control receiving of SAML un-solicited Response messages then an event handler for the receivedResponse event needs to be implemented.

Listing 8. Rejecting un-solicited Response messages

public void receivedResponse(ResponseEvent event) throws MessageRejectedException {
	if(event.getInResponseTo() == null) {
		throw new MessageRejectedException("Unsolicited response rejected");
	}
}

Localization

An SP application can specify which language the user interface of Ubisecure Authentication SSO Server is displayed in.

The Ubisecure Authentication SSO Server also returns the language that the user has selected during sign in. For best user experience, the returned language should update the application session language.

Setting the Locale of UAS Ubisecure SSO Login Screen

The UAS SSO login screen locale can be set by implementing an AuthnRequestEventListener and overriding the authnRequest method:

Listing 9. Overriding the authnRequest method

@Override
public void authnRequest(AuthnRequestEvent event) {
String locale = "en";
event.getAuthnRequest().setLocale(locale);
}

In the example above, the language is set explicitly to English. Typically however, this value is taken from existing session or environment information.

If an application requires a link that determines the language of the login screen, this override must collect the language information from the link.

If it is desired that the language of the login screen is set based on the user browser language, it must also be set at this point. Read the browser Accept-Language value, parse appropriately to match the languages and defaults available and set the value using setLocale. UAS does not rely on the language settings of the browser for the UAS user interface.

Reading the User Locale After Login

It is possible to change the default language during the login sequence. Application can receive the latest locale selected during UAS SSO login by implementing an LoginEventListener and overriding the login() –method:

Listing 10. Implementing an LoginEventListener and overriding the login method

@Override
public void login(LoginEvent event) {
	HttpServletRequest rq = event.getHttpRequest();
	HttpSession session = rq.getSession(); 
	String locale = rq.getParameter("locale");
	if(null == locale) {
		locale = "en";
	}
	session.setAttribute("locale", locale); 
}

If the user has selected a language during sign in, it is sent to the SP as a two letter code in the locale parameter of the HTTP query string. The SP application should be able to handle the situations when no code is returned or when the language is not supported by the application.

If the user's desired language is stored in a user repository accessible during authentication (LDAP/SQL), this value could be added to the Authorization Policy as an attribute. There is currently no method for UAS to send the user's interactively selected language as an attribute in the Authorization Policy.

Changing Ubisecure SSO UI Template

A Service Provider can specify in authentication request which UI template will be used in Ubisecure SSO user interface screens, provided that the template is permitted in settings of the Web Agent in question.

Allowing Multiple Templates for a Web Agent

To be able to change the template in use, there must be more than one template allowed for the web agent. It can be done in the Ubisecure SSO Management application by listing all allowed template separated by a whitespace in the Template Names –property of the configuration screen of the web agent (see Figure 1).

The default template is always the first one of the allowed templates. The default template will be used in following two occasions (in addition to being specified explicitly in the authentication request):

No template is specified in the authentication request.
A template is specified in the authentication request, but the template is not in the list of allowed templates for the Web Agent.

Note that if the Template Names property is left empty, the default template will be default.

Specifying the Template in Authentication Request

The template specified in the authentication request message can be set by implementing AuthnRequestEventListener and overriding the authnRequest() –method.

Listing 11. Implementing an AuthnRequestEventListener and overriding the authnRequest method

@Override
public void authnRequest(AuthnRequestEvent e) {
	e.getAuthnRequest().setTemplate("template2");
}


Figure 1. Define two allowed templates for Test Service, template1 and template2. The default template is template1.

Browser not supported