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:

When using the .tar.gz the update can be conveniently performed on a single machine, in a safe way:

The above procedure is long but allows for a detailed testing of the service before rolling it out into production. Of course if you want to be quick and unsafe, you can skip the testing phase.

If using the RPM installation method, the safe test drive of the updated system can be only performed with a help of an additional machine: install the updated version there first, upload the dump of the old instance and test it. If everything is all right then the actual update may take place:

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.

Public Key Infrastructure (PKI) trust settings are used to validate certificates, i.e. to check if the certificate are not faked. This is performed, in the first place when a connection with a remote peer is initiated over the network, using the SSL (or TLS) protocol. Additionally certificate validation can happen in few other situations, e.g. when checking digital signatures of various sensitive pieces of data.

Certificates validation is primarily configured using a set of initially trusted certificates of so called Certificate Authorities (CAs). Those trusted certificates are also known as trust anchors and their collection is called a trust store.

Except of trust anchors validation mechanism can use additional input for checking if a certificate being checked was not revoked and if its subject is in a permitted namespace.

Unity allows for different types of trust stores. All of them are configured using a set of properties.

In all cases trust stores can be (and by default are) configured to be automatically refreshed.

The following table provides a reference to settings of all of the trust stores.

Examples

Directory trust store, with a minimal set of options:

Directory trust store, with a complete set of options:

Java keystore used as a trust store:

Unity uses private key and a corresponding certificate (called together as a credential) to identify itself to its clients during TLS connection and sometimes to digitally sign returned documents. This allows clients to be sure that they are talking with the genuine, not faked peer. Note that also clients or users may use certificates to identify themselves to Unity - this is another topic.

Credentials might be provided in several formats:

The following table list all parameters which allows for configuring the credential. Note that nearly all options are optional. If not defined, the format is guessed. However some credential formats require additional settings. For instance if using der format the keyPath is mandatory as you need two DER files: one with certificate and one with the key (and the latter path can not be guessed).

Examples

Credential as a pair of DER files:

Credential as a JKS file (credential type can be autodetected in almost every case):

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:

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 of the SAML HTTP-POST binding. If you do not plan to use SOAP clients, this endpoint can be safely disabled.

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

The options of the endpoint (besides the standard ones for the binding) 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 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, if you don’t integrate Unity with UNICORE portal 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 make 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 not required.

This endpoint is a slightly enhanced 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 Unity with UNICORE don’t use this endpoint.

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 make 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 not required.