SAML 2.0 based federated authentication

Unica Platform implements a SAML 2.0 based Identity Provider (IdP) that enables a single sign-on federation among Unica products or between Unica products and third party applications.

A federation is a group of IdPs and applications that works together in a trusted environment and provides services to each other using SAML 2.0 (Security Assertion Markup Language) based standards.

Applications that are members of a federation are called Service Providers (SPs). The IdP server and the SPs can be hosted on premises or on cloud.

A SAML 2.0 federation supports a variety of authentication mechanisms for single sign-on. For example, a user can be authenticated in an SP using that application’s authentication mechanism (for example, in-house, OAuth, OpenId, SAML, Kerberos), and then the user can access other SPs using federated single sign-on, provided the applications are part of same federation and the user is mapped appropriately.

The IdP server creates, validates, or deletes tokens based on user mappings. Data access objects are implemented for the supported database types, and are included in the IdP server.

An administrator maps user IDs between SPs to provide single sign-on access to mapped users. For example, suppose SP_A and SP_B are both members of a federation. User1 is an account in SP_A, and User2 is an account in SP_B. The User1 account is mapped to the User2 account in the federation. When a user logs in to SP_A with User1 credentials, that user has single sign-on access to SP_B. Also, when a user logs in to SP_B with User2 credentials, that user has single sign-on access to SP_A.


The following diagram illustrates the federation.

Components of the HCL implementation

The implementation of SAML 2.0 based federated single sign-on consists of the following components.

These components are located in the tools/lib directory under your Unica Platform installation.

  • A SAML 2.0 based IdP server, delivered as a WAR file: idp-server.war
  • A client façade: idp-client.jar

    The IdP client facade is Java implementation with an API that works with security tokens. It is delivered as a JAR file. Javadoc documentation for the API is included with the Unica Platform Javadoc.

    The IdP client facade enables Java SPs to quickly integrate with the IdP server and become part of the federation.

Supported use cases

The current implementation enables SPs to work with security tokens to establish single sign-on authentication among the SPs.

Generating a new SAML token

The implementation can generate a new SAML token for a user who initiates a single sign-on authentication request. This user must be mapped on the IdP server. Based on the trusted party's credentials and user mapping, the IdP server creates a new security token and issues it using a SAML 2.0 assertion.

For example, if User1 from SP_A is mapped with User2 from SP_B on the IdP server, and User1 tries to access SP_B resources, the IdP server generates a security token for User1 as a trusted party.

Validating an existing SAML token

The implementation can validate an existing SAML token presented by an SP that receives the access request from a user from another SP. The SP first validates the security token and client mapping with the IdP server to identify the mapped user in its own domain.

For example, when SP_A tries to access SP_B resources on behalf of User1 and presents the IdP security token, SP_B takes this token to the IdP server. If the token is valid and User1 is mapped to an SP_B user, the IdP server resolves the SP_B user in the SP_B domain and returns the assertion.

Deleting an existing SAML token

The implementation can delete an existing SAML token for an SP user when a user logs out from the system or the session times out due to inactivity. Based on the trusted party's credentials and user mapping, the IdP server deletes the token and resets the last accessed timestamp when it receives the logout request. This does NOT delete the user's mapping.


The current implementation does not support the following use cases.

  • Creating a new user mapping between SP users via a user interface or API
  • Updating an existing user mapping between SP users via a user interface or API
  • Deleting an existing user mapping between SP users via a user interface or API

Federated authentication and partitions

If your Unica environment has multiple partitions, you can set up separate SAML 2.0 based federated authentication per partition. To implement this, on the Settings > Configuration page, you must create a new set of properties in the Unica Platform | Security | Federated Authentication | partitions | partition[n] category for each partition.