Unity Manual

We believe that the amount of Unity use-cases is endless. Here are some:

Internally Unity is composed of two parts:

Unity extensibility is the the core concept, and there are no exceptions to this rule. For instance each and every supported credential type is an extension, there are no hardcoded ones.

The core platform provides persistence of the service state (i.e. managed entities, attributes, groups, etc), extensions management, orchestration and several cross cutting features. Such core features are preferences management, notifications, registrations support etc.

Unity is written solely in Java 7, which is the single, hard installation requirement. All used technologies are as lightweight as possible. Unity works as set of services available via an embedded HTTP server (Jetty). Therefore there is no need to install it on top of an existing HTTP or servlet server, or even worse to setup a JEE container.

The most of the Unity functionality is controlled via its rich Web Admin interface. Some, rather low-level subsystems need to be set up in configuration files.

Below a glossary of key terms which are used throughout this manual is presented.

Unity is tested on the Linux platform. Also other variants of Unix should be fine to run Unity.

Unity theoretically can be run on Windows server, however we neither provide startup scripts for windows nor test it. If you would love to run Unity on Windows machine, write to the support mailing list.

Unity is distributed with everything needed to install and run the system except of Java. Java Runtime Environment 7 must be installed, both OpenJDK and Oracle distributions are supported. It is strongly advised to use the latest, updated version of the JRE.

If the .tar.gz version is used, it must be simply downloaded and unpacked. A directory with Unity version number is included. Typically the start script should be created or integrated with the startup system of the machine. The distribution’s extra/ folder may provide a suitable script. It is also a good idea to add the INSTALLATION_DIRECTORY/bin/ folder to the PATH environment variable, so the scripts are instantly available. This is assumed later on in all examples.

If the .rpm version is used it should be installed with the package manager. The only dependency is Java JRE, which will be installed automatically if not yet available on the machine. The startup scripts are also installed automatically.

Unity can be started right away, but most probably the default setting should be changed. Please refer to the Crucial facts to know before the first start or General server configuration sections for a short or detailed information how to configure the system.

Starting is simple:

It is always good to check the log files. The log/unity-startup.log should contain only few lines saying that the server started successfully. If there are any errors there, it means that a very low level problem happened, for instance the JRE is not available. The log/unity-server.log should provide a more detailed information, which should be also checked. There should be no ERROR and no WARN entries.

Stopping the server is simple as well:

Unity server can be started right after installation. By default the server is configured to listen on the localhost (loopback) network interface and uses absolutely insecure credentials for the TLS protocol. Therefore you can play around but before going into any real usage some reconfiguration is mandatory.

Here we list the most important facts about the default configuration:

Unity uses two databases. The primary one is used to store the complete state of the system. The second one, called as local database, is used to record a stream of events which happen in the system. The purpose of the separate databases is that the primary database can be replicated and/or shared between multiple instances of Unity server, while the local database should not be replicated/shared. Of course backups of both databases can and should be performed.

Note that the Admin UI provides a possibility to create a dump of the primary database and to restore the system from such dump.

The following table enumerates all options which are used to configure both databases. Only one option pertains to the local database, the rest is for the primary one. This is because the local database is always handled by the H2 database engine, so only the database storage location can be changed.

Unity uses a centralized management of all Public Key Infrastructure (PKI) settings in a file defined in the main configuration. By default the configuration file is called pki.properties.

In the file three types of objects can be defined: PKI credentials (i.e. pairs consisting of an X.509 certificate and an associated private key), truststores (sets of trusted CA certificates with many additional settings as CRLs) and individual certificates of external entities.

It is possible to define many objects of each type. For instance one can define two credentials: one for SSL server and another one for the SAML IdP endpoint to sign issued SAML assertions.

All of the artifacts are named and the names are used in other parts of the Unity configuration to refer to a configure instance. The main configuration reference is presented below. The subsequent sections cover in more details the configuration of truststores and credentials which can be configured in many different ways.

Authenticators and endpoints as of now can be configured only in the configuration file. Endpoints are covered in a separate section Consumer access: the endpoints.

Authenticator is a pair of two configured elements: credential verificator and credential retrieval. The credential retrieval collects a credential in a binding specific way, for instance it may gather it from a SOAP header (in case of the web service binding) or present a text field and allow a user to enter it (in case of the web binding). The verificator is not binding-specific and is only responsible for validation of a presented credential. For example the passowrd verificator can be used with any retrieval which is collecting a password from a client.

Authenticators are added to endpoints and manage endpoint’s authentication. The endpoint must have at least one authenticator associated (and can have more when alternative or multi-credential authentication scenarios are implemented).

Example configuration:

The name of the authenticator is an arbitrary, unique string. The type is the most important part: it defines the name of the credential verificator and retrieval, both names must be separated with the string with. The following table lists allowed credential verificators and retrievals. Any combination can be used, assuming the same credential is exchanged.

Both credential verificator and credential retrieval can require a separate configuration in external files, in the example only the credential retrieval has it configured. Finally all local verificators must be associated with the existing local credential (the secured password in the example).

Configuration of external verificators is covered in the section Integration of 3rd party Identity Providers. Configuration of retrievals and local verificators is either not needed or trivial. Currently only the web-password allows for it, offering two options:

Name is used in the web interface. The registration form parameter is used only for cases when the retrieval is used with a remote authenticator: then the given registration form is presented automatically to the users who properly authenticated against the upstream IdP but doesn’t have a local account.

The embedded HTTP server is using sensible default values of HTTP settings. There are only two properties which always needs to be properly set: hostname and port. However in some cases it may be necessary to fine tune also the advanced settings. The complete reference is included below:

Notifications and other messages are sent by Unity in several cases, for instance as an optional verification step during password reset or to notify an administrator about a new registration request.

Currently the only notification channel available is the e-mail channel. It can be disabled by removing or commenting the e-mail configuration property in the main configuration file. If enabled it is configured in a separate properties file. The default file provides a detailed information on the available options so should be easy to edit.

The actual contents of the messages being sent is governed by the templates configuration file. Currently a template is a named pair of two strings: title and message body. What’s more the template can contain several variables which must be formated as:

Variables are replaced dynamically with concrete values when a message is prepared to be sent. Naturally each subsystem sending messages provides different variables. The example configuration file contains default forms for all currently implemented notifications with variables included so it should be easy to update them.

Unity uses the Log4j logging framework in version 1.2.x (note that the latest version 2.x is much different). What is more the log4j-extras package is included so additional logging features are enabled. Logging is configured in the conf/log4j.properties file.

By default, log files are written to the the logs/ directory.

The following example config file configures logging so that log files are rotated daily, and the old log files are compressed.

For more info on controlling the logging we refer to the log4j documentation:

Log4j supports a very wide range of logging options, such as date based or size based file rollover, logging different things to different files and much more. For full information on Log4j we refer to the publicly available documentation, for example the Log4j manual.

Unity allows its administrators to define and deploy so called registration forms. A registration form can be used in three cases:

The first step is to define a registration form. The form definition consists of three parts:

After creation a registration form can be tested and also filled (use case no 2 above) directly from the Admin Web UI. If the form is public it can be associated with any endpoint with the Web (Vaadin) binding. Then a link to register a new account will appear on the login screen of the endpoint. Finally a form can be associated with a remote authenticator as a "handler" for unknown users who were correctly authenticated remotely.

An example of registration form creation:

A simple registration form in action:

Note that the above screenshot is showing the form as activated from the Web Admin UI; the form launched other way will not allow for automatic acceptance.

Translation profile is a named, ordered list of conditional rules. The rules are used to modify the remotely obtained data and/or to perform automatic modifications of the Unity’s database. For instance translation profile can change remote attribute height value from inches to centimeters and insert a remotely authenticated user to the local database (to the correct group) if the user is not yet there.

Translation profile is associated with a remote authenticator in its configuration. The definition of the profile itself is given in a separate JSON file and the list of profile files is specified in the Unity main configuration file.

Translation profile (both conditions and rules) operate on a data structure which is initially filled by the protocol specific component. The structure can contain: * Identity (or identities) authenticated by the remote IdP. * External attributes encoded with a list of string values. * Groups assigned by the remote IdP.

What data is actually returned is dependent on the protocol, upstream server and callout configuration.

The overall syntax of the translation profile file is as follows:

The rule condition is given as a MVEL expression language. The documentation can be found here http://mvel.codehaus.org/Language+Guide+for+2.0 and the quick start is here http://mvel.codehaus.org/Getting+Started+for+2.0 The context of the expression language contains three map objects named identities, groups and attributes, indexed with identity, group and attribute names respectively.

For instance the following condition tests whether the authenticated user name is john.

The actions and their arguments are documented in the following table. Where argument is ended with RE a regular expression can be used.

The following example rule maps all (the true condition) remote identities to local representation without any identity change (the original identity is replaced with itself) and assigns it the PasswordOnly credential requirement.

LDAP based authentication allows for outsourcing credential verification to a server talking with the LDAP protocol, as OpenLDAP or Active Directory.

To configure LDAP authentication a server address must be provided as well as some information regarding the LDAP directory schema. The amount of options varies depending on the amount of information that should be retrieved from LDAP.

Let’s consider an (complex) example:

In this example a single LDAP server is configured (also alternative addresses may be added to take advantage of LDAP high availability deployment if it is set up): localhost:389. The login name which is presented for authentication is converted to an LDAP DN using a template expression. Thanks to it the user needs not to enter the full DN. The two attributes (cn and sn) are going to be retrieved for the user. Finally there are two group definitions, configuring how to extract group membership from LDAP. In this case the LDAP server stores groups as separate tree nodes which contains group members as values of a designated attribute.

In the both cases the groups are searched under the LDAP tree node dc=unity-example,dc=com. In the first case the group objects have the class posixGroup. Members are listed as values of the memberUid attribute. What is more the values are not the full DNs of the members but only their cn attributes. The group’s short name is in its cn attribute. The 2nd group definition is similar but another object class is used (groupOfNames), members are in other attribute (members) and are given with their full DNs.

The complete LDAP options reference follows:

External SAML authentication module allows for authenticating the Unity’s client with the external SAML identity provider as Shibboleth IdP or any other SAML 2 compliant service. Attributes of the authenticated user can be as well obtained and mapped to the local database.

Currently only the two most popular SAML2 SSO bindings are supported: HTTP Post and HTTP Redirect. This means that this authentication can be used only for the web endpoints, to authenticate web browser clients.

The remote SAML callout is configured with a list of trusted SAML identity providers. If more then one trusted provider is defined, then a user can select his/her home provider. As each provider features can be different nearly all settings are specified per provider.

Let’s consider an example with two remote IdPs:

The first part of the configuration provides the general settings: metadata (see below), credential used to sign contents, accepted name formats and the displayed name of the authentication option for the user interface. A configuration of two IdPs follows.

Both IdPs shares the same translation profile (common approach when the IdPs are from a single federation with agreed attributes profile), however the first IdP is configured to use HTTP Redirect binding, while the later the HTTP POST. The certificates are mandatory to verify responses, and are the fundamental element of the whole authentication to ensure proper trust and therefore security.

The first IdP has also two advanced options set: it is defined which attribute is used as a group attribute and a requested name format is fixed (in the latter case the IdP is free to choose).

The complete SAML authenticator configuration reference follows:

Web Admin UI is the first place to visit after server installation and startup as it offers a administrator oriented management interface. By default it is accessible under the link: https://localhost:2443/admin/admin

The features of the Web Admin interface are covered in the Contents management section.

The endpoint offers only the standard options of the Web binding.

Web User Home UI provides a simple profile management interface for the ordinary Unity members. It is possible to change preferences, update credentials and check information stored in the Unity database about the user.

By default it is accessible under the link: https://localhost:2443/home/home

Note that the Web Admin endpoint incorporates all the features of the of the Home endpoint (accessible after switching the view with the profile button).

The endpoint offers only the standard options of the Web binding.

This endpoint exposes the SAML 2 authentication interface, implementing the SSO profile with the support for the SAML HTTP-POST and HTTP-Redirect bindings.

The endpoint first authenticates the redirected client, then presents a confirmation screen where a user can review and alter a returned information and, after acceptance, redirects the user to the SAML Service Provider with a SAML response.

The metadata related features and configuration is the same as in the case of remote SAML authenticator (SAML Metadata support) with the exception that the metadata is published under the endpoint’s address with the constant /metadata suffix.

The options of the endpoint (besides the standard options for all Web endpoints) are:

This endpoint exposes the SAML 2 authentication interface, exposing the functionality of the Attribute Query and Authentication SAML protocols over the SAML SOAP binding.

The SAML options and metadata notes are the same as in the case of the Web SAML SSO endpoint.

This endpoint is a slightly enhanced Web SAML SSO endpoint, with the UNICORE 7 Grid middleware support. It is useful for UNICORE portal SAML authentication, so if you don’t integrate UNICORE portal with Unity don’t use this endpoint.

The endpoint is configured in the same way as the Web SAML SSO endpoint, the only functional difference is that it allow to generate and return UNICORE 7 trust delegations made for the relaying party.

Only the users with the X.500 identity (among others identities) may use this endpoint. However neither authentication with certificate nor possession of a X.509 certificate is required.

This endpoint is a slightly enhanced version of Web Service SAML SOAP endpoint, with the UNICORE 7 Grid middleware support. It is useful for UNICORE standalone client (e.g. UCC) SAML authentication, if you don’t integrate UNICORE with Unity this endpoint is useless.

The endpoint is configured in the same way as the Web Service SAML SOAP endpoint, the only functional difference is that it generates and return UNICORE 7 trust delegations made for the client.

Only the users with the X.500 identity (among others identities) may use this endpoint. However neither authentication with certificate nor possession of a X.509 certificate is required.