Introduction

About This Page

NOTE: Ubisecure product names were unified in autumn 2011. All products which started with term "Ubilogin" were renamed to start with term "Ubisecure". In documentation this name change is implemented retroactively, i.e., the new naming practice is used also when referring to old software versions which started with term "Ubilogin" at the time of their release.

This page describes the requirements and tasks for installing the Common Domain Cookie (CDC) Discovery in a Ubisecure Trust. The result of the installation described in this document is a working environment which uses Common Domain Cookies for discovery in a Ubisecure system.

Overview

In a configuration, where you have many SSO Servers (or Identity Providers/IdPs) in your federation network, it may be difficult to achieve a smooth SSO experience. That is because different IdPs don't know about each other and every time you access a Service Provider, which is bound to a different IdP, your Home IdP needs to be defined. Usually this is done by showing a list all IdPs in the federation network out of which the user has to make the selection.

Discovery is a concept where the selection of the Home IdP is delegated to a Discovery Service. Discovery has two profiles, active and passive. In the active profile the Discovery Service may interrupt the discovery procedure and expect the user to make the selection, while in the passive profile the interruption is not allowed.

The Discovery Service may use a saved state for determining the Home IdP. In active discovery it is not necessary, but if saved state is available and it is used, active discovery works without interruption – i.e., just like passive discovery. Without saved states however, the discovery service would show the selection every time an identification is required.

For passive discovery the saved state is more important, as without a saved state it would not be able to return much anything.

One possible method for saving the state is to store the Home IdP in a Common Domain Cookie, which requires that all Discovery Services (if there are many, it is also possible to use a single Discovery Service for all IdPs) share a common domain. The Common Domain Cookie is set by a CDCWrite service, which is called whenever a successful identification is made, provided that the CDCWrite service is set for that particular identification method. Similarly, CDCRemove is a service that removes the cookie and is called whenever you log out from a SSO service. CDCWrite and CDCRemove services need to be located in the same Common Domain as the Discovery Service itself.

CDC Discovery Service is usually configured to use the passive profile, so in case the CDC is not set, the Discovery Service will not interrupt. Discovery Service reads the CDC Cookie and returns the Home IdP which is stored in it. The IdP using the Discovery Service can then use that information and redirect the user agent straight to the Home IdP. The same applies to all IdPs that are configured to use the same CDC Discovery Service.

By using CDC Discovery it is possible to achieve a seamless SSO experience throughout the federation network.

Sample CDC Use Cases

This section describes three simple CDC use cases with two SSO servers.
Use case 1. Initial authentication of user and writing CDC using a dedicated Discovery Service


Figure 1. Initial authentication of user and writing CDC using a dedicated Discovery Service

The steps, illustrated in Figure 1, are as follows:

The user tries to access Service 1.
Service 1 asks for an authentication for the user from SSO Server 1.
SSO Server 1 checks from local CDC Discovery Server whether the user has already been authenticated in a service that the CDC covers.
CDC is not found, i.e., the user is not currently authenticated in any such service.
SSO Server 1 authenticates the user locally (using, e.g., a password, OTP or TUPAS).
SSO Server 1 asks the local CDC Discovery Service to store the authentication into a new CDC.
The CDC is stored successfully.
The user returns to Service 1 as an authenticated user.

Use case 2. User has already been authenticated in SSO Server 1. SSO Server 2 uses Discovery Service for reading the Common Domain Cookie. The CDC indicates that the user has been authenticated in SSO Server 1 and federates the authentication from there.


Figure 2. CDC is set and SSO session exists in the federated server

The steps, illustrated in Figure 2, are as follows:

The user follows a link to Service 2.
Service 2 asks for an authentication for the user from SSO Server 2.
SSO Server 2 checks from local CDC Discovery Server whether the user has already been authenticated in a service that the CDC covers.
CDC is found, set to server1.com.
SSO Server 2 makes an authentication request to SSO Server 1 instead of displaying an authentication menu.
The user has an SSO session active in SSO Server 1. SSO Server 1 returns the user's information to SSO Server 2 according to the SAML protocol.
The user returns to Service 2 as an authenticated user. From Server 2's viewpoint the situation is identical to one where SSO Server 2 had authenticated the user.

Installing the CDC

Before Installation

System requirements

Ubisecure SSO 6.1.1 or newer
Installation according to Installation - SSO Guide.

Installation of Ubisecure CDC Discovery Service

NOTE: These steps are done only for the Identity Provider that is the actual source of the identification.

Ubisecure CDC Discovery Service is a separate application, which is provided with Ubisecure SSO. A separate application is needed, because CDC Discovery Service must have a different DNS name than the Ubisecure SSO itself. The DNS name must be the same for all the discovery services used in the federation network.

Ubisecure CDC Discovery Service provides CDC Cookie handling (i.e., writing and removing the CDC cookie) and SAML passive discovery protocol.

In the example settings below, yourdomain.com has been selected as the common domain for discovery. The name of the common domain should be chosen carefully in cooperation with all participants in the interfederation. In large deployments, it is advisable to use a domain that is not currently in use. If the chosen domain appears in a managed Trusted Sites list for Windows networks, Internet Explorer browser may prevent the CDC cookie from functioning correctly. For more information, please contact Ubisecure Support.

To install the Ubisecure CDC Discovery Service:

Set the domain that is common to all IdPs using a Discovery Service that reads the Common Domain Cookie.
In Windows, go to directory C:\Program Files\Ubisecure\ubilogin-sso\ubilogin\webapps\cdc\WEB-INF\ and open the config.properties file for editing:
notepad "C:\Program Files\Ubisecure\ubilogin-sso\ubilogin\webapps\cdc\WEB-INF\config.properties"
In Linux, go to /usr/local/Ubisecure/ubilogin-sso/ubilogin/cdc/WEB-INF/ and open the config.properties file for editing:
cd /usr/local/Ubisecure/ubilogin-sso/ubilogin/webapps/cdc/WEB-INF/
pico config.properties
In the config.properties file, add the following lines:
cdc.cookie.domain = .yourdomain.com
cdc.cookie.secure = true
Please note that the leading period (.) is required before the domain name as per the SAML specifications.
Save and close the config.properties file.
CDC functionality is enabled separately for each authentication method. In practice this is done by configuring the CDC cookie handling for each method that needs to use the CDC functionality.

To enable CDC functionality for an authentication method:

Select Home → Global Method Settings and select the desired authentication method from the Server Authentication Methods list.
Add the following configuration to the Configuration String field:
CDCWrite = https://subdomain.yourdomain.com:8443/cdc/write.gif
CDCRemove = https://subdomain.yourdomain.com:8443/cdc/remove.gif

Figure 3. Example of enabling the CDC functionality for an authentication method

Taking the Discovery Service Into Use

NOTE: This procedure is done only for the Identity Provider that functions as the Service Provider (SP), i.e., has the IdP Proxy authentication method installed.

Discovery Service is taken into use in Ubisecure SSO in a similar way to authentication methods.

To take the Discovery Service into use in Ubisecure SSO:

Open the Ubisecure Management application.
Select Global Method Settings and click the New Method... button. (In the example pictures, the source for the federated identification is named as EXAMPLE Federation.)
Add New Method window opens.
Give the method a title (external name) and name (name for internal use).
Set the method type to Discovery.
Click OK.

Figure 4. Adding Discovery Service as a new method to Ubisecure SSO
In the Main page of the new method, select the Enabled and Hidden checkboxes.
Add the following lines to the Configuration String field:
DiscoveryService = https://subdomain.yourdomain.com:8443/cdc/DiscoveryService policy.hidden=true
IsPassive=true
Click Update.

Figure 5. Configuring the new authentication method

Test Service

An information page is accessible to show the current status of cookies and allow the removal of individual common domain cookies. The test page is for diagnostics purposes. It is always enabled and can be opened at the address
https://subdomain.yourdomain.com:8443/cdc/info


Figure 6. CDC Test page: No cookie has been set, the user does not have an active session at any IDP.


Figure 7. CDC Test page: A cookie has been set, the user has an active session at `idp1.example.org` and will be redirected to this IDP for authentication and authorization.

Clicking remove.gif next to the IDP cookie will remove the cookie from the browser.

Troubleshooting

If session transfer from one federation to another federation requires the user to authenticate twice, the problem may be caused by browser settings. If Internet Explorer is used, make sure that the browser's trust settings are correct.

Problematic scenario is if CDC domain is part of the SSO1 domain but not SSO2 domain.

You either need to have all CDC discovery federation domains (in this case CDC domain and SSO2 domain) in the trusted sites list or none of them.

Browser not supported