1. What (for) is Unity?

In short Unity is a complete solution for identity, federation and inter-federation management. Or, looking from a different perspective, it is an extremely flexible authentication service.

Unity allows its administrators to enable authentication (or login) using various protocols, with different configurations for many relaying parties. The actual authentication can be performed using the built-in, feature-rich users database or can be delegated to one of supported upstream identity providers (IdPs). The information obtained from upstream IdPs can be flexibly translated and merged with the local database (if needed) and re-exported using other protocols. Those fundamental usage patterns are shown on the following figure:

Unity general function as a versatile authentication platform

What is important to underline here:

Unity is NOT yet another bundle of several, coupled together systems. It is a solution built from the ground up. All pieces perfectly fit together. Startup is fast. Administration of all parts is performed in the same style. And the whole solution is fully web and cloud ready.

Unity is under heavy development. Not all extensions and functions of the engine which are on the presented figures are already available. Even some of the enumerated use-cases are not already fully achievable. We plan to deliver the remaining fundamental (and many other) features soon. For the actual and detailed information on what is currently supported please check the Currently supported features section.

The most important design principles of Unity are:

  • Simplicity There are tons of competitive solutions, but we found most of them terribly difficult to install and maintain. We try hard to make Unity as user friendly as possible.

  • Extensibility There is a plethora of authentication protocols, credential systems, IDM solutions and issues related to their coordination. We can’t support all of them right from the start. But we should be able to seamlessly support most, if not all, of them. Unity is designed to be truly extensible in all places where it makes sense to do so.

  • Security We doesn’t provide inherently insecure solutions in Unity. No, it is not possible to use MD5 or SHA1 password hashes in the local database.

1.1. Use cases

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

  1. Web application developers want to secure it with authentication, provide user accounts with different authorization roles (admin, customer, …) and a couple of personal attributes.

    • Instead of developing the system, this whole functionality can be outsourced to Unity, after a simple step of integration with the protocol of choice as SAML or OpenID. What is more, the increasing user-management requirements will not require any development steps. Registration functionality needed? Yes, it’s here.

  2. University wants to integrate its users with a national educational SAML federation.

    • Unity can be a drop in replacement of other SAML IdP as Shibboleth. And instantly delivers functionality of often needed add-ons (as Internet2 Grouper, authN extensions). It doens’t require installation of an additional user databases (as LDAP) - everything is included. And even better, Unity can still expose the legacy local LDAP instance if needed too.

  3. Commercial company wants to enable an advanced authentication for their suite of cloud applications: multifactor authentication (MFA) for sensitive management applications and social network logins for customer-oriented interfaces. Still with an ability to control who uses what, how often, block unwanted users, with user profile management UI for the users.

    • This is the same situation as in the first use-case: it is only a matter of a different configuration of Unity.

  4. University, which is already integrated with a SAML federation, wants to join also another SAML federation.

    • Instead of setting up (and what is much worse: maintaining) a second instance of IdP service, Unity can expose several SAML endpoints, with different configurations, so the new federation can be joined immediately.

  5. Organization wants to offer its web resources to several SAML federations. At the same time people authenticating with the social logins as Google accounts should be let in to, but only after filling a registration form and after successful vetting by the organization’s staff.

    • Unity allows for arbitrary number of configuration of authentication endpoints and sources. The above task can be simply achieved by using several Unity authentication configurations together and the ability to define and deploy registration forms. Of course registration can be bound only to some designated authentication pipelines.

1.2. Details for IT professionals

Internally Unity is composed of two parts:

  • An orchestration platform, or a container of highly specialized extensions.

  • A rich (and growing) set of extensions providing support for the actual Unity features.

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.

Powerful, built-in Unity identity management subsystem

1.3. Glossary: General Unity concepts

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


Unity provides a portfolio of access modules. Those modules are called endpoint types. Each endpoint type can be deployed multiple times, with different configuration. A deployed and configured endpoint type is called an endpoint instance or just an endpoint for short. Examples: Web Admin UI is an endpoint type providing web browser management access; SAML SOAP authentication is enabled by another endpoint.


It is a configured authentication component which can perform a full authentication using a single credential with a well defined way to obtain it from the principal being authenticated. Authenticators are associated with endpoints.

Authentication Realm

It is a simple group of endpoints, which share login sessions. Client logged to one of realm’s endpoints is immediately logged to all other endpoints of the realm. Authentication realms are used to control login session settings.


Entity is used to describe a principal that can try to authenticate using Unity, have assigned attributes etc. In practice it is a user or software agent. We can say that in the first place, Unity is a tool to manage and authenticate entities.


Each entity can have one or more representations. Each representation is called identity. Identities have its type, as username or X.500 Distinguished Name (DN) which defines its syntax, equality rules etc. If an entity has several identities attached, then all are equivalent. This is used to provide aliases for the same principal, at the same time supporting different authentication systems, which represent principals in different ways.

Credentials (local)

Credentials are associated with entities and are used to perform local authentication of an entity. When authentication is done using a remote IdP, then the local credential is not used. Therefore some entities may have no local credentials, if only the remote authentication is allowed for them. Each credential implementation may be configured differently and each configured credential is called credential type. For example there is a password credential implementation, which can be configured two times: as a secured password which requires 3 character classes and minimal length of 8 characters and as a simple password with less strict requirements.

Credential requirement

Credential requirement is a simple, named set of credential types. Credential requirement is assigned to an entity and defines which credential types make sense and can be used for the entity. Using credential requirements, the ordinary system users may have a simple password credential type assigned, managers a secured password and administrators tuple of secured password and certificate to employ a more secure authentication.

Attributes and attribute types

Attributes are assigned to entities to express their characteristics. For instance a birthDate attribute may be used to express the birth date of an entity. Attributes are always assigned in a concrete group, so the same entity can have different attributes depending on the group. This is very useful in many situations e.g. to provide different user characteristics for different consumers. Attribute can have from zero to many values. Values must have a common syntax, Unity supports several syntaxes as string or JPEG photo. Attribute has its type, which define the rules for the attribute in the system, in the first place its name and values syntax and the cardinality of values.


Groups are nodes in a tree-like structure and contain entities. Groups are hierarchical, i.e. each member of a subgroup must be the member of the parent group. Groups not only are used to logically group/sort members but provide additional automatic content management features as automatic attributes assignment via attribute statements.

Attribute statements

Attribute statements are defined in a group. Attribute statement automatically assigns an attribute to selected members of the group. For instance there is statement which can copy an attribute X for all users who has the X attribute in a parent group to the current group (what enables attributes propagation).

Attribute class

Attribute class defines which attributes (more properly: which attribute types) are allowed and/or mandatory. Attribute class is assigned either to a group (then it governs the settings for all group members) or to a specific group member. Attribute classes can be organized in a hierarchical structure, where more complex classes inherit definitions from basic classes.

Upstream or remote IdP

An external service which is used by Unity to perform authentication. Upstream IdPs can return more information about the authenticated user (besides the fact that the user correctly authenticated with as a given identity). Unity is able to make use of this information: translate it and insert to the local database. This is done with translation profiles.

Translation Profile

See the above point.

2. Installation and operation manual

2.1. Prerequisites

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.

2.2. Fresh installation

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.

In case of RPM installation the standard Linux directory layout is used. This manual uses the names of Unity subdirectories as found in the .tar.gz distribution. The mapping of those folders to locations used in the case of the RPM installation is as follows:











Unity can be started right away, but most probably the default setting should be changed. Please refer to the [quick_start] or General server configuration sections for a short or detailed information how to configure the system.

2.3. Starting and stopping the server

Starting is simple:

$> unity-idm-server-start

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-idm-server-stop

2.4. Notes on redundant installations

It is possible to install Unity in a High Availability (HA) setup. The Unity HA is realized on the database level, and currently it is only supported when using MySQL.

When configuring the system some precautions must be made:

  1. In general only a single instance should be responsible for loading the initial state of the system (endpoints, authenticators etc). Otherwise the servers might have problems during startup and it is hard to keep multiple configurations the same. It is good to set unityServer.core.recreateEndpointsOnStartup=false on the slave nodes.

  2. All instances should use the same unityServer.core.httpServer.advertisedHost value. At the same time DNS entry of the value should be switched when a primary service is detected to be down.

Please note that several runtime features of the system are propagated to other nodes with some latency. For instance a removal of an endpoint on one instance will be reflected in the shared database immediately, however other Unity instances will catch up and undeploy the endpoint with some delay.

If the server is being managed with two instances simultaneously the Refresh buttons are more then handy: the UI state is not updated automatically.

Finally note about login sessions: login sessions are shared between Unity instances, while HTTP sessions are not. Therefore if the web browser is logged to one instance’s endpoint and then the browser is directed to another the session should be preserved (assuming that the browser has the same DNS address associated with both instances as it is suggested above). The same applies to the logout operation.

3. Quick start

This section is fairly standalone and serves as a first-read, hands-on introduction to Unity. It is advised to read the What (for) is Unity? section first. Also installation of Unity is not covered here. While it is simple (download & unpack) you can read the details in Installation and operation manual.

3.1. What is provided in the package?

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.

Let’s start from crucial facts about Unity in general:

  • Unity always uses a single HTTPS port. It must be opened on firewall. The port is configurable.

  • Unity uses RDBMS to store its state. Not only the users and attributes are stored in database: also a nearly complete configuration of the system is.

  • Therefore the most of the Unity configuration which is provided in config files is only loaded on startup and persisted. Many of those settings can be edited in web admin interface. We plan to provide most of the configuration via the web interface.

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

  • The server is configured to run on localhost address on the port 2443. Also the advertised address (i.e. the address which Unity presents as its address to external clients) is localhost. All of those parameters need an update before going into production.

  • The server uses an insecure credential (its private key is well known) issued by an insecure CA, which is the only one trusted CA. A real credential and truststore should be used for production.

  • The server uses an embedded H2 database. Its performance is fine, however it is not recommended in production deployments where DB backups and high availability may easily become a requirement.

  • The server should be started by an unprivileged user. It is not required in case of using the system initialization scripts installed with RPM, which can be run by root (the user will be automatically changed to unity-idm).

  • If one wants to use an a low port (e.g. 443) for Unity, then authbind is the suggested solution. It can be easily enabled in startup.properties

  • The distribution is set up to load some demo contents. If you don’t need it - remove it from the configuration by deleting the unityServer.core.initializers. prefixed lines from the unityServer.conf

3.1.1. The first and subsequent startups

During the startup the server checks if it needs to initialize the various subsystems. This initialization takes place during the first start after installation and also after the Unity database is deleted.

  1. If the database is empty the tables are automatically created. There is no need to invoke any database initialization scripts. The database is populated with the mandatory system contents.

  2. If there is no configured admin user in the database, this user is created, using the configured credentials. The default admin user credential is automatically set to the outdated state, what causes a necessity to change it immediately after the first login.

  3. Subsequently the data structures defined in configuration files are loaded to the database. This functionality is provided to be able to manage of those parts of the Unity engine data/configuration which doesn’t have management GUI (yet). In general those are low-level, rarely changed artifacts as endpoints or authenticators.

  4. Finally the configured content initializers are run. Those initializers are useful to load the default contents for various use-cases.

3.2. What should be reconfigured always before going into production?

Once again, to have a short list:

  • Remove the demo truststore and credential (in pki.properties). Add regular truststore and certificate.

  • Set a desired bind address, port and external address in unityServer.conf.

  • Remove the demo content creation from the unityServer.conf.

  • Consider configuring a MySQL database instead of the default H2.

3.3. How to work with unity

→ make note on what you want to do with Unity, concentrating on -→ what will be the clients, using what protocols -→ whether external authentication services are going to be used, which ones, and with what protocols? -→ → design internal DB schema (attribute types, groups structure, attribute classes)

3.4. Understanding Unity

What are the most important elements of the system to configure? The following diagrams should introduce you to endpoints and authenticators:

The most important components of Unity

A concrete example of the above schema can be as follows:

Example diagram of an endpoint with two authenticators

Endpoints are the modules which are entry points to Unity. Each endpoint has its binding the low level access protocol which can be for instance web (designated for web-browsers) or SOAP (for web service clients). Example of endpoints are SAML IdP endpoint (allows relying services to authenticate their users with SAML) with the web binding or the Admin UI endpoint (again with the web binding) which provides an embedded administration UI.

Each endpoint’s authentication is configured by associating it with authenticator(s). It is possible to set more then one authenticator to provide alternative authentication possibilities. It is also possible to group authenticators together to require providing of several credentials simultaneously.

Authenticator is a pair of credential retrieval and verificator. The retrieval collects the credential in a binding specific way. The verificator checks if it is correct.

The credential verificators can be local or external. Local verificator check the credential against a credential stored in the local database. The only configuration of such verificator is the name of a local credential. On the other hand the external verificator uses an external service to check the credential. Examples are LDAP or remote SAML IdP. In this case a rather complicated configuration of verificator is required.

3.5. Walk through: a simple reconfiguration

Let’s try to use a client-authenticated TLS authentication for the SAML SOAP endpoint. By default this endpoint is enabled (all snippets are from the unityServer.conf, the main configuration file):

unityServer.core.endpoints.5.endpointName=UNITY SOAP SAML service

It uses the (single) authenticator pwdWS:

unityServer.core.authenticators.3.authenticatorType=password with cxf-httpbasic
unityServer.core.authenticators.3.localCredential=Password credential

So lets define a new one, called certWS:

unityServer.core.authenticators.4.authenticatorType=certificate with cxf-certificate
unityServer.core.authenticators.4.localCredential=Certificate credential

The new authenticator uses a certificate verificator with cxf-certificate retrieval. Both are matching as both are working with certificate credentials, so it is fine to use them together. The local credential setting (used by verificator) was set to Certificate credential. Of course such credential must be defined - you can check it in the Schema→Credential types tab of the Admin UI. As the retrieval requires no configuration we used an empty configuration file. The actual names of the retrievals and verificators are listed in Authenticators.

Finally let’s use this authenticator:


To apply changes one can restart the server. However it is more convenient to go to the Server management tab of Admin UI. There are tabs which allow to reload authenticators and endpoints on the fly.

3.6. What to read next

If you want to learn more about integration with external identity systems, the separate SAML HowTo is the best starting point.

It is also good to play with the Admin UI to get familiar with the features offered there.

4. Update

This section covers a general update procedure. Make sure to read version specific update instruction too: Version specific update instructions.

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

  1. Install the updated version in a separate directory as in the case of a fresh installation.

  2. Configure it with the settings of the running instance, however change the port to any other which is free. If using a database server as MySQL, be sure to use another, clean database.

  3. Apply any required changes in configuration, e.g. to enable new features of the updated version.

  4. Create a dump of the server state on the running instance.

  5. Start the new instance (next to the old one).

  6. Load the dumped state to the new instance and test it.

  7. If everything is all right stop it and change its port to the correct port used by the old service.

  8. If needed, create an another, up-to-date dump of the old service state and stop it.

  9. Start the new service and load the latest dump.

  10. If needed reconfigure startup scripts to start the updated service, as well as update the PATH variable to use new Unity binaries location. It is a good practice to have a symbolic link to the actual Unity installation directory that is used in the PATH and startup scripts. Then it is possible to simply change its target to the updated service directory.

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:

  1. Create a dump of the database state.

  2. Stop the old service.

  3. Update the RPM using platform tools (usually yum).

  4. Check if any configuration files needs to be updated (search for .rpmnew files in /etc/unity-idm).

  5. Reconfigure the service to use a new, clean database or clean all the data from the existing one. In case of the embedded database it is needed to remove the files /var/lib/unity-idm/data/unitydb\.*.

  6. Start the new service.

The database dump can be created and loaded from the Web Admin UI, from the Server maintenance tab.
If you plan to clean the database instead of configuring a new one it is always good to have a copy in case an emergency downgrade.

4.1. Version specific update instructions

4.1.1. From 1.0.0 to 1.1.0

In the 1.1.0 version three important changes of configuration subsystem were introduced.

The first change is a new mandatory option which needs to be added to the main configuration file.


The value of this option should contain an external/official address (IP is also allowed) of the server. This option is important whenever server listens on many interfaces ( address) or is behind proxies, DNAT solutions etc.

In the version 1.1.0 a centralized configuration of credentials and truststores was introduced. Therefore all of the credentials and truststores are now configured in a single file and referenced by name in other files. Configuration should be updated as follows:

  1. [Mandatory for the RPM installations; recommended for tar.gz installations] A new property should be added to the main configuration file unityServer.conf, specifying the location of the pki.properties file. Typically unityServer.core.pkiConfigFile=/etc/unity-idm/pki.properties (RPM installation) or unityServer.core.pkiConfigFile=conf/pki.properties (tar.gz installation, this value is also the default one).

  2. All distinct credentials and truststores used in the configuration should be identified. The possible locations are enumerated below:

    1. base server credential and truststore used in the main configuration file,

    2. each SAML endpoint typically have both the credential and truststore defined,

    3. the LDAP authenticator using SSL mode can have a truststore defined.

  3. For each distinct truststore and keystore an name must be chosen, and the configuration of the credential/truststore must be copied to the pki.properties file mentioned in the previous point. The syntax is described in the manual.

  4. Finally in each place where the original configuration of the credential or truststore was provided directly, it should be removed and replaced with a single option referencing the globally defined credential/truststore. This option key (the last part) is respectively .credential or .truststore.

Another configuration format change introduced in 1.1.0 version is located in configuration of (all) SAML endpoints. Besides few new options, the trust settings were changed to facilitate a more rich set of settings.

The update should be performed with the following rules:

Each entry unity.saml.acceptedUriSP should be removed and replaced with a new unity.saml.acceptedSP. entry. The trusted service provider certificate should be defined in pki.properties and only referenced. For instance the following setting:

unity.saml.acceptedUriSP.SP_1=http://sp.example.com/ /certs/sp.pem

should be replaced with:


where SP1_CERT should be defined in pki.properties as follows:


In the similar way the the unity.saml.acceptedDNSP. entries should be updated:


should be replaced with:


where dn is a distinguished name of the Service Provider using X.500 name to identify itself.

4.1.2. From 1.1.0 to 1.2.0

The version 1.2.0 introduces a new important concept: authentication realms. This new feature requires several configuration updates:

  1. Desired authentication realms should be planned (see authentication realms documentation) and configured in the main configuration file unityServer.conf.

  2. The former endpoint specific options: unity.endpoint.ws.blockFor, unity.endpoint.ws.blockAfterUnsuccessfulLogins (both for web service endpoints), unity.endpoint.web .blockAfterUnsuccessfulLogins, unity.endpoint.web.blockFor and unity.endpoint.web.sessionTimeout (web endpoints) are to be removed from endpoint configuration files. Those settings are controlled on the realm level now.

  3. Finally appropriate realm should be assigned to endpoints. This is performed in the unityServer.conf, with the per-endpoint property unityServer.core.endpoints.X.endpointRealm.

Note that endpoints must be reloaded. The endpoints which were not reloaded will belong to a single, default authentication realm.

Another change introduced in the version 1.2.0 is the finalized message templates handling with management feature in the Admin UI. The configuration of message templates from the configuration file is deprecated. It can be still used, however each template must have an additional setting: TEMPLATE_NAME.consumer. This setting controls the intended purpose of the template - what determines the available template variables. The currently possible values are: PasswordResetCode, RegistrationRequestSubmitted, RegistrationRequestUpdated, RegistrationRequestAccepted and RegistrationRequestRejected.

Note: translation profiles and templates are not preserved automatically during upgrade. Therefore the easiest way to preserve them is to edit the templates in the new Admin UI tab (in Server management) and to load the old translation profiles from the unityServer.conf. After that translation profiles can be edited from the Admin UI, and their configuration files can be dropped.

5. General server configuration

The server uses two main configuration files: conf/unityServer.conf and conf/log4j.properties. There is also a third one, conf/startup.properties, which allows for controlling low level Java VM options (as memory or JVM executable) and for changing the location of the main configuration files mentioned above.

The conf/log4j.properties file configures the logging of the server. This is described in the section Logging configuration.

The conf/unityServer.conf file is the main server configuration file. All other additional configuration files are defined in it.

Configuration files are loaded at startup. Most of the files (all except of the logging and mail settings) are quite strictly verified - in case of misconfiguration, syntax errors, or spelling mistakes server prints a loud error message in log file and (if the error is critical) does not start.

Configuration updates at runtime are handled as follows:

  • conf/log4j.properties file is automatically reloaded after it is modified (with few seconds latency). It is recorded in the log file.

  • No other file is automatically reloaded after modification. However,

  • configuration of authenticators and endpoints can be reloaded from the Web Admin UI (in the Server Management tab). It is possible to remove, add or reconfigure existing elements.

  • Reconfiguration of the remaining options from the main configuration file and PKI settings requires server restart. Note that most of the features configured in the files can be managed at runtime from the Web Admin UI.

  • Note however that the directory and openssl truststores which can be configured in PKI settings allows for automatic updates of their content when trusted certificates or CRLs are added or removed.

The table showing all the options is quite long, so here we provide a description of the most important parts of the configuration:

  • The general server settings (it is always good to review them) include:

    • The initial admin username and password. After the server is initialized and admin account(s) are set up those options may be removed and used only in emergency case (i.e. when the last admin user remove itself).

    • Location of the files with configuration of the e-mail subsystem and message templates. More information on this topic is included in the subsection Notifications and e-mail settings.

    • Location of Public Key Infrastructure (PKI) configuration file. This is documented separately in the subsection PKI settings.

    • Database configuration which is described in the section Database configuration.

    • Loaders of example contents, which are useful for a quick start.

    • Configuration of enabled languages.

    • Selection of the server main truststore and credential, mostly used for SSL.

  • HTTP server settings, where there are three important settings: hostname and port where the server listens and the advertised address, which should be an address or IP via which the server should be reached from Internet. The remaining options of the HTTP server are fairly advanced.

  • Definitions of various artifacts of the server to be loaded: credentials, credential requirements, authenticators, endpoints and translation profiles. Note that the credentials, credential requirements and translation profiles can be also managed more conveniently with the Web Admin UI. The configuration of authenticators and endpoints is described in the subsection Authenticators and the translation profiles are covered in Integration of 3rd party Identity Providers.

The general options reference table follows:

Property name Type Default value / mandatory Description

--- General settings ---

unityServer.core .asyncStateUpdateInterval

integer >= 1


Defines the interval of background update tasks in seconds. Those tasks are used to update runtime state of the server (for instance the deployed endpoints) with the data which is stored in database.



mandatory to be set

Name of the credential to be used by the server.




The default locale to be used. Must be one of the enabled locales.

unityServer.core.enabledLocales .<NUMBER>

list of properties with a common prefix


List of enabled locales. Each entry must have a language code as en or pl first, and then, after a space an optional, short name which will be presented in the UI. By default the en locale is installed.


[true, false]


If false then the default admin user is not set to outdated state after creation. Useful only for testbeds.




Password of the administrator to be installed to the empty database.




Username of the administrator to be installed to the database upon startup. Remove the property if no admin should be added.


list of properties with a common prefix


List of identifiers of initialization modules that should be run on the first startup.


filesystem path


A configuration file for the mail notification subsystem.


filesystem path


A file with the configuration of the PKI: credentials and truststores.

unityServer.core .recreateEndpointsOnStartup

[true, false]


If this options is true then all endpoints are initialized from configuration at each startup. If it is false then the previously persisted endpoints are loaded.


filesystem path


A file with the initial message templates. You can have this file empty and manage the templates via the Admin UI.


integer number


Number of threads used by internal processes of the server. HTTP server threads use a separate pool.

unityServer.core.translationProfiles .*

list of properties with a common prefix


List of file paths, where each file contains a definition of a translation profile, used to configure mapping of remote identities to the local representation.



mandatory to be set

Name of the truststore to be used by the server.


filesystem path


Defines a folder where the server will write its internal files.

--- Content initializers: credentials ---


Structured list


List of initially defined credentials

unityServer.core.credentials.<NUMBER> .credentialConfigurationFile


mandatory to be set

Credential configuration file

unityServer.core.credentials.<NUMBER> .credentialDescription


empty string

Credential description

unityServer.core.credentials.<NUMBER> .credentialName


mandatory to be set

Credential name

unityServer.core.credentials.<NUMBER> .credentialType


mandatory to be set

Credential type

--- Content initializers: credential requirements ---

unityServer.core .credentialRequirements.<NUMBER>

Structured list


List of initially defined credential requirements

unityServer.core .credentialRequirements.<NUMBER> .credentialReqContents.*

list of properties with a common prefix

mandatory to be set

Credential requirement contents, i.e. credentials that belongs to it

unityServer.core .credentialRequirements.<NUMBER> .credentialReqDescription


empty string

Credential requirement description

unityServer.core .credentialRequirements.<NUMBER> .credentialReqName


mandatory to be set

Credential requirement name

--- Content initializers: authenticators ---

unityServer.core.authenticators .<NUMBER>

Structured list


List of initially enabled authenticators

unityServer.core.authenticators .<NUMBER>.authenticatorName


mandatory to be set

Authenticator name

unityServer.core.authenticators .<NUMBER>.authenticatorType


mandatory to be set

Authenticator type

unityServer.core.authenticators .<NUMBER>.localCredential



For local authenticator the name of the local credential associated with it.

unityServer.core.authenticators .<NUMBER>.retrievalConfigurationFile



Authenticator configuration file of the retrieval

unityServer.core.authenticators .<NUMBER>.verificatorConfigurationFile



Authenticator configuration file of the verificator

--- Content initializers: authentication realms ---


Structured list


List of authentication realm definitions.

unityServer.core.realms.* .blockAfterUnsuccessfulLogins

integer >= 1


Defines maximum number of unsuccessful logins before the access is temporarely blocked for a client.


integer >= 1


Defines for how long (in seconds) the access should be blocked for theclient reaching the limit of unsuccessful logins.

unityServer.core.realms.* .enableRememberMeFor

integer number


(web endpoints only) If set to positive number, the realm authentication will allow for remeberinging the user’s login even after session is lost due to expiration or browser closing. The period of time to remember the login will be equal to the number of days as given to this option. IMPORTANT! This is an insecure option. Use it only for realms containing only endpoints with low security requirements.

unityServer.core.realms.* .maxInactivity

integer >= 1


Defines after what time of inactivity the login session is terminated (in seconds). Note: the HTTP sessions (if applicable for endpoint) will be couple of seconds shorter to allow for login session expiration warning.

unityServer.core.realms.* .realmDescription



Realm’s description.

unityServer.core.realms.* .realmName


mandatory to be set

Defines the realm’s name. Must contain only alphanumeric letters, and can not exceed 20 characters.

--- Content initializers: endpoints ---


Structured list


List of initially enabled endpoints

unityServer.core.endpoints.<NUMBER> .contextPath


mandatory to be set

Context path of the endpoint

unityServer.core.endpoints.<NUMBER> .endpointAuthenticators


mandatory to be set

Endpoint authenticator names: each set is separated with ; and particular authenticators in each set with ,.

unityServer.core.endpoints.<NUMBER> .endpointConfigurationFile

filesystem path

mandatory to be set

Path of the file with JSON configuration of the endpoint

unityServer.core.endpoints.<NUMBER> .endpointDescription


empty string

Description of the endpoint

unityServer.core.endpoints.<NUMBER> .endpointName


mandatory to be set

Endpoint name

unityServer.core.endpoints.<NUMBER> .endpointRealm


mandatory to be set

Authentication realm name, to which this endpoint belongs.

unityServer.core.endpoints.<NUMBER> .endpointType


mandatory to be set

Endpoint type

--- Other ---


string can have subkeys


Properties starting with this prefix are used to configure Jetty HTTP server settings. See separate table for details.

5.1. Database 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.

Property name Type Default value / mandatory Description




Location of the local H2 database can be controlled with this connection URL.

--- Database ---


[h2, mysql, psql]


Database SQL dialect. Must match the selected driver, however sometimes more then one driver can be available for a dialect.


Class extending java.sql.Driver


Database driver class name. This property is optional - if not set, then a default driver for the chosen database type is used.




Database JDBC URL.



empty string

Database password.




Database username.

5.1.1. MySQL setup

The setup of MySQL requires creation of a database with a separate user which is able to connect to the database. In mysql console (when logged with admin privileges) execute:

GRANT ALL PRIVILEGES ON unitydb.* to 'unity'@'localhost' IDENTIFIED BY 'unitypass';

using the desired database name, username and password. If the database is on a different host then the Unity instance, change to localhost to a proper host of Unity installation or use % to allow connections from any host.

Test if the connection works with:

mysql -p -u unity unitydb

and give the password.

Unity server will setup all tables automatically on startup.

To configure Unity to use the database change the database JDBC URI as well as add the username, password and dialect:


5.2. PKI settings

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.

Property name Type Default value / mandatory Description


Structured list


List of certificates.

unity.pki.certificates.* .certificateFile


mandatory to be set

Certificate file path (PEM format).


Structured list


List of credentials. The subkey defines the credential name.


Structured list


List of truststores. The subkey defines the truststore name.

5.2.1. PKI/X.509 trust settings

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.

  • Keystore trust store - trusted certificates are stored in a single binary file in the JKS or PKCS12 format. The file can be manipulated using a special tool like JDK keytool or openssl (in case of PKCS12 format). This format is a good choice if the trust store should be stored in a single file or when compatibility with other Java solutions is desired.

  • OpenSSL trust store - allows to use a directory with CA certificates stored in PEM format, under precisely defined names: the CA certificates, CRLs, signing policy files and namespaces files are named <hash>.0, <hash>.r0, <hash>.signing_policy and <hash>.namespaces. The hash must be generated using the openssl tool from a trusted certificate. This format is used by many well known servers, Linux distributions often provide tools to help in trust store management. Therefore this format is suggested if reuse of the truststore is needed.

  • Directory trust store - the most flexible and convenient option, suggested for all remaining cases. It allows administrators to use a list of wildcard expressions, concrete paths of files or even URLs to remote files as a set of trusted CAs and corresponding CRLs. With this trust store it is trivial to configure a designated directory(-ies) as a trust store.

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. Note that the prefix of the pki.properties is not shown in the table.

Property name Type Default value / mandatory Description




Controls whether proxy certificates are supported.


[keystore, openssl, directory]

mandatory to be set

The truststore type.


integer number


How often the truststore should be reloaded, in seconds. Set to negative value to disable refreshing at runtime. (runtime updateable)

--- Directory type settings ---


integer number


Connection timeout for fetching the remote CA certificates in seconds.


filesystem path


Directory where CA certificates should be cached, after downloading them from a remote source. Can be left undefined if no disk cache should be used. Note that directory should be secured, i.e. normal users should not be allowed to write to it.




For directory truststore controls whether certificates are encoded in PEM or DER.


list of properties with a common prefix


List of CA certificates locations. Can contain URLs, local files and wildcard expressions. (runtime updateable)

--- Keystore type settings ---




The keystore type (jks, pkcs12) in case of truststore of keystore type.




The password of the keystore type truststore.




The keystore path in case of truststore of keystore type.

--- Openssl type settings ---




In case of openssl truststore, controls which (and in which order) namespace checking rules should be applied. The REQUIRE settings will cause that all configured namespace definitions files must be present for each trusted CA certificate (otherwise checking will fail). The AND settings will cause to check both existing namespace files. Otherwise the first found is checked (in the order defined by the property).

--- Revocation settings ---


integer number


Connection timeout for fetching the remote CRLs in seconds (not used for Openssl truststores).


filesystem path


Directory where CRLs should be cached, after downloading them from remote source. Can be left undefined if no disk cache should be used. Note that directory should be secured, i.e. normal users should not be allowed to write to it. Not used for Openssl truststores.


list of properties with a common prefix


List of CRLs locations. Can contain URLs, local files and wildcard expressions. Not used for Openssl truststores. (runtime updateable)




General CRL handling mode. The IF_VALID setting turns on CRL checking only in case the CRL is present.


integer number


How often CRLs should be updated, in seconds. Set to negative value to disable refreshing at runtime. (runtime updateable)


integer number


For how long the OCSP responses should be locally cached in seconds (this is a maximum value, responses won’t be cached after expiration)


filesystem path


If this property is defined then OCSP responses will be cached on disk in the defined folder.


list of properties with a common prefix


Optional list of local OCSP responders




General OCSP ckecking mode. REQUIRE should not be used unless it is guaranteed that for all certificates an OCSP responder is defined.


integer number


Timeout for OCSP connections in miliseconds.




Controls overal revocation sources order


[true, false]


Controls whether all defined revocation sources should be always checked, even if the first one already confirmed that a checked certificate is not revoked.


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:


5.2.2. Configuring the PKI credential

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.

Do not confuse the PKI credential used by the server to identify itself with the credentials of the entities handled in the Unity’s database.
For production usage, Unity should use a certificate issued by a globally trusted certificate authority.

Credentials might be provided in several formats:

  • Credential can be obtained from a keystore file, encoded in JKS or PKCS12 format.

  • Credential can be loaded as a pair of PEM files (one with private key and another with certificate),

  • or from a pair of DER files,

  • or even from a single file, with PEM-encoded certificates and private key (in any order).

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

Property name Type Default value / mandatory Description


filesystem path

mandatory to be set

Credential location. In case of jks, pkcs12 and pem store it is the only location required. In case when credential is provided in two files, it is the certificate file path.


[jks, pkcs12, der, pem]


Format of the credential. It is guessed when not given. Note that pem might be either a PEM keystore with certificates and keys (in PEM format) or a pair of PEM files (one with certificate and second with private key).




Password required to load the credential.




Location of the private key if stored separately from the main credential (applicable for pem and der types only),




Private key password, which might be needed only for jks or pkcs12, if key is encrypted with different password then the main credential password.




Keystore alias of the key entry to be used. Can be ignored if the keystore contains only one key entry. Only applicable for jks and pkcs12.


Credential as a pair of DER files:

unity.pki.credentials.MAIN.password=SOME PASS

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


5.3. Authenticators

Credential types and credential requirements can be configured in the Web Admin UI, so we skip a description of their configuration in the configuration files.

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:

unityServer.core.authenticators.2.authenticatorType=password with web-password
unityServer.core.authenticators.2.localCredential=secured password

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.

Verificator Exchanges Description



Local verificator.



External verificator, uses LDAP.


X.509 certificate

Local verificator.


SAML assertions

External verificator, interacts via associated retrieval with a remote SAML IdP.

Retrieval Exchanges Compatible binding Description



Web (Vaadin)

Uses textfield to collect a password


X.509 certificate

Web (Vaadin)

Uses client-authenticated TLS/SSL certificate



Web Service (CXF stack)

Uses HTTP BASIC submitted password


X.509 certificate

Web Service (CXF stack)

Uses client-authenticated TLS/SSL certificate


SAML assertions

Web (Vaadin)

Allows to choose remote SAML IdP, redirects the user to authenticate there and collects the received authentication data.

Examples of some of the allowed combinations:

password with web-password
password with cxf-httpbasic
ldap with cxf-basic
certificate with web-certificate
certificate with cxf-certificate

But for instance the combination ldap with web-saml2 is illegal: ldap verificator uses different exchange (Password) then web-saml2. Note that this is logical: LDAP server can not be used to verify a SAML assertion obtained from some remote SAML IdP.

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": "LDAP password",
	"registrationFormForUnknown": "ldapRegistration"

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.

5.4. HTTP server settings

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:

Property name Type Default value / mandatory Description

--- General settings ---

unityServer.core.httpServer .advertisedHost



The hostname or IP address which is advertised externally whenever the server has to provide its address. By default it is set to the listen address, however it must be set when the listen address is and also should be set whenver the server is listening on private interface accessible via DNAT or similar solutions.




The hostname or IP address for HTTPS connections. Use to listen on all interfaces.


integer [0 — 65535]


The HTTPS port to be used. If zero (0) is set then a random free port is used.

--- Advanced settings ---

unityServer.core.httpServer .disabledCipherSuites


empty string

Space separated list of SSL cipher suites to be disabled.


[true, false]


Use insecure, but fast pseudo random generator to generate session ids instead of secure generator for SSL sockets.

unityServer.core.httpServer.gzip .enable

[true, false]


Controls whether to enable compression of HTTP responses.

unityServer.core.httpServer.gzip .minGzipSize

integer number


Specifies the minimal size of message that should be compressed.

unityServer.core.httpServer .highLoadConnections

integer >= 1


If the number of connections exceeds this amount, then the connector is put into a special low on resources state. Existing connections will be closed faster. Note that this value is honored only for NIO connectors. Legacy connectors go into low resources mode when no more threads are available.

unityServer.core.httpServer .lowResourceMaxIdleTime

integer >= 1


In low resource conditions, time (in ms.) before an idle connection will time out.

unityServer.core.httpServer .maxIdleTime

integer >= 1


Time (in ms.) before an idle connection will time out. It should be large enough not to expire connections with slow clients, values below 30s are getting quite risky.


integer >= 1


Maximum number of threads to have in the thread pool for processing HTTP connections.


integer >= 1


Minimum number of threads to have in the thread pool for processing HTTP connections.

unityServer.core.httpServer .requireClientAuthn

[true, false]


Controls whether the SSL socket requires client-side authentication.

unityServer.core.httpServer .soLingerTime

integer number


Socket linger time.


[true, false]


Controls whether the NIO connector be used. NIO is best suited under high-load, when lots of connections exist that are idle for long periods.

unityServer.core.httpServer .wantClientAuthn

[true, false]


Controls whether the SSL socket accepts (but does not require) client-side authentication.

5.5. Notifications and e-mail settings

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 message templates. Message templates are configured using Admin UI (Server management→Message templates). It is also possible to configure them with configuration file (by default msgTemplates.properties), but this is much more difficult and not suggested. Currently a template is a named pair of two pieces of text: subject (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. Therefore each template must be associated with a concrete subsystem. This is performed in the template edit screen. The list of available variables for each subsystem is also provided there.

5.6. Authentication realms and login sessions

Unity uses authenticaiton realms to manage shared configuration of login sessions for endpoints. Each endpoint must be associated with exactly one authentication realm.

In authentication realm configuration session expiration and blocking of brute force attacks are defined. It is also possible to enable remember me feature, which is rather insecure as the user must not use it from public computers:


Association of an endpoint with authentication realm is given in the main endpoint’s configuration in unityServer.conf:


Please note that several properties of authentication realms are supported only on web endpoints, as for instance web service (SOAP) endpoints do not use sessions. Still it is important to understand that even for those endpoints the fact whether the endpoint is or is not in the same authentication realm as other endpoint can be significant. The most important case is with all targeted tokens and identities which are generated by Unity. Let’s consider an example.

Two SAML endpoints A (Web) and B (SOAP) are in the same authentication realm R1, while the third endpoint C (SOAP) is in realm R2. If a service provider asks a client to to authenticate it via A endpoint and receives a transient (targeted) identity, this identity will be also valid for the queries to the endpoint B as both are in the same realm, sharing the session context of the logged user. At the same time this transient identity won’t be available at endpoint C.

5.7. Logging configuration

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.

# The default log level and the output (appender)
log4j.rootLogger=INFO, LOGFILE

# What to log

#Configuration of appenders which performs actual logging

# LOGFILE is set to be a file appender using a PatternLayout with daily rolling.
log4j.appender.LOGFILE.layout.ConversionPattern=%d{ISO8601} [%t] %-5p %c %x - %m%n

In Log4j, the log rotation frequency is controlled by the DatePattern. Check http://logging.apache.org/log4j/1.2/apidocs/org/apache/log4j/DailyRollingFileAppender.html for the details.

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.

5.7.1. Logger categories, names and levels

Logger names are hierarchical. In Unity, prefixes are used (e.g. "unity.server.con") to which the Java class name is appended. The most common logging prefixes are:

  • unity.server - general server messages

  • unity.server.config - configuration parsing and loading

  • unity.server.db - database related

  • unity.server.web - web interface related

  • unity.server.saml - SAML subsystem related

  • unity.server.ldap - upstream LDAP IdP related

  • unity.server.ws - SOAP (web service) stack related

  • unity.server.externaltranslation - messages connected with the translation of any upstream IdP data to the Unity format.

Therefore the logging output produced can be controlled in a fine-grained manner. Log levels in Log4j are (in increasing level of severity):

  • TRACE on this level huge pieces of unprocessed information are dumped,

  • DEBUG admin-friendly, verbose information, useful for hunting problems,

  • INFO standard information, not much output,

  • WARN warnings are logged when something went wrong (so it should be investigated), but recovery was possible,

  • ERROR something went wrong and operation probably failed,

  • FATAL something went really wrong - this is used very rarely for critical situations like overall server failure.

For example, to debug a configuration problem, you can set:


The best way to discover what is the name of the interesting category is to turn on the general DEBUG logging for a while. Then interesting events can be seen and subsequently the logging configuration can be fine tuned to only show them.

6. Contents management

The Web Admin UI allows to manage the schema and contents of the server. The initial admin user and its password is defined in the configuration file. The actual address is defined there as well, if unchanged it is https://localhost:2443/admin/admin. After the first login it is required to change the initial password.

The most important features of the Web Admin UI are:

  • Management of attribute types, attribute classes, credential types and credential requirements (Schema management tab).

  • Possibility to manage groups, their attribute classes and attribute statements (Contents management tab).

  • Control over entities and identities and their group membership (Contents management tab).

  • Full attribute control (Contents management tab).

  • Management of registration forms, possibility to fill them instantly from the Web Admin UI and to manage the received requests (Registrations management tab).

  • Possibility to create and load database dumps and to browse and trigger reconfiguration of endpoints, authenticators and translation profiles (Server management tab).

We hope that the UI is easy to use, therefore we limit the description to the following screenshot with some hints. In case of troubles please let us know through the mailing list, we will provide more details.

Unity Web Admin UI

6.1. Authorization

Unity offers a simple but quite powerful authorization control of its own access. It is controlled by a designated attribute: sys:AuthorizationRole. The attribute is of enumeration type, and the type can not be changed.

By assigning this attribute to entities, those entities are granted some roles and therefore are authorized to perform certain operations in Unity. The detailed information on what is allowed for each role holder is provided in attribute type description (see Schema Management→Attribute Types). The two most important roles are:

  1. System manager who is authorized to perform all actions and

  2. Regular user who can perform all the typical operations reserved for users, i.e. read information about itself.

It is possible to create an entity without assigning any authorization role. Such entity will be present in the system, but won’t be able to perform besides authentication. It won’t be even allowed to read its own attributes.

A good approach is to define an attribute statement assigning a default authorization role (e.g. Regular User or Anonymous User) to all members of the / group.

The sys:AuthorizationRole is typically assigned in the root (/) group. However, Unity also supports authorization on the group level: all Unity operations which operate on a particular group (e.g. read attributes in a group, add a member to a group, read group members, create a subgroup, etc) are using the sys:AuthorizationRole attribute which is defined for the user performing the operation in the group in question or in the closest parent where it is defined. Example:

User Joe is a member of /Faculty/Staff group (therefore it is also a member of /Faculty) and no other groups. He has the sys:AuthorizationRole=System Manager attribute defined in the /Faculty/Staff group. What’s more he has sys:AuthorizationRole=Anonymous User defined in / group and sys:AuthorizationRole=Regular User attribute in the /Faculty group.

Joe tries to add an attribute to an entity representing Ann, in the group /Faculty/Students. As he is not a member of this group he has no authorization role defined there. The next group to check is /Faculty, where he has the authorization role defined (Regular User). The role doesn’t allow for managing attributes so the operation will fail. However Joe can modify attributes of any entity in the /Faculty/Staff group as he has System Manager role there.

6.2. Registration forms

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

  1. To collect registration information from prospective users. This can be seen as a classic registration feature use case.

  2. To quickly and conveniently create entities with common characteristics. In this case administrator can define what data needs to be entered for the created user and also automate some of the actions which should be performed for newly added users.

  3. To collect additional information from users who are authenticated by a remote IdP, so the user can be added to the local database.

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

  1. General settings as name, notifications configuration and decision whether the form is publicly available.

  2. Collected information settings, which define what needs to be provided to the form. This information is usually collected interactively by filling a web form, but some data can be also collected from a remote IdP. This latter option is possible only if a form is used for unknown remote users.

  3. Settings which are automatically assigned for each user whose registration request is accepted. For instance this feature may be used to add all users to a specified group.

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:

Definition of registration form in Unity

A simple registration form in action:

Filling of a registration form in Unity

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.

7. Integration of 3rd party Identity Providers

Unity can use external services to authenticate its own clients. This way Unity can act as an authentication hub (many authentication options are offered in a single place) and as an authentication bridge (Unity client can use different authentication protocol then the protocol of the upstream IdP).

External IdPs are configured as specialize authenticators which outsource credential verification to the upstream service. So this section treats about the configuration of external authenticators.

Data from external IdPs is accessed in a protocol specific way. The configuration of this part is described in the following subsections. After the protocol specific part, a common process for all external IdP types take place: translation of the obtained data to the internal Unity representation. This "mapping" can handle both semantical and syntactical differences of the identity-related information. It is configured with so called translation profiles.

7.1. Translation profiles configuration

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 size name to width 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 profiles is done with the Admin UI (Server management→Translation profiles).

Translation profile (both conditions and rules) operate on a data structure which is initially filled by the protocol specific component. The structure can contain:

  1. Identity (or identities) authenticated by the remote IdP.

  2. External attributes encoded with a list of string values.

  3. Groups assigned by the remote IdP.

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

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.

identities[\"john\"] != null

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

Action name Arguments Description


sourceIdentityType targetIdentityType credentialRequirement

Maps a remote identity by type to a local identity with a new type.


attribute identityType credentialRequirement

Maps a remote attribute to a local identity with a given type.


replacedRE replacement credentialRequirement

Convert identity value to local representation & assigns credential requirement.


replacedRE replacement

Converts group to local representation.


replacedRE replacement group

Convert attribute names and assign them to a local group.



If there is a previously mapped identity in the context and it is not available in the local DB it is created. If the argument is true, then also the attributes mapped to the / group are assigned.



Adds the client to the groups which were provided by the remote IdP. Only groups that has been previously mapped to the unity group are considered (other are ignored). A subset of all groups can be selected with parameter.


pattern valuesOnly

Updates selected attributes of the client. Only attributes that has been previously mapped to local name and have assigned group scope can be updated (other are ignored). Can work in two modes: either all attributes are added/updated or only the values are updated for those attributes which are already present locally.

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.

condition: true
action: mapIdentity ((.*), $1, PasswordOnly)

7.2. LDAP

Credential verificator name


Compatible credentials


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.

The typical authenticator’s configuration will look as follows:

unityServer.core.authenticators.x.authenticatorType=ldap with web-password

Let’s consider an (complex) example of a configuration of the LDAP verificator in file conf/authenticators/ldap.properties:


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:

Property name Type Default value / mandatory Description

--- General settings ---


list of properties with a common prefix


List of attributes to be retrieved. If the list is empty then all available attributes are fetched.


[true, false]


If true then the user is only authenticated and no LDAP attributes (including groups) are collected for the user. This is much faster but maximally limits an information imported to Unity.


[plain, SSL, startTLS]


It can be controlled whether a connection to teh server should be made using a plain socket, over SSL socketor over a socket with START TLS after handshake.


list of properties with a common prefix


List of redundant LDAP server ports. The ports must match their corresponding servers.


integer >= 0


Number of referrals to follow. Set to 0 to disable following referrals.


integer number


Amount of time (in seconds) for which a search query may be executed. Note that depending on configuration there might be up to two queries performed per a single authentication. The LDAP server might have more strict limit.


list of properties with a common prefix


List of redundant LDAP server hostnames. Use only one if there is no redundancy.


integer >= 0


Number of milliseconds the network operations (connect and read) are allowed to lasts. Set to 0 to disable the limit.



mandatory to be set

Name of a translation profile, which will be used to map remotely obtained attributes and identity to the local counterparts. The profile should at least map the remote identity.


[true, false]


Used only when TLS mode is enabled. If true then the secured TLS protocol will accept any server’s certificate. If false - then the truststore must be configured.




Truststore name used to configure client’s trust settings for the TLS connections.



mandatory to be set

Template of a DN of the user that should be used to log in. The tempalte must possess a single occurence of a special string: {username} (without quotation). The username provided by the client will be substituted.




Standard LDAP filter of valid users. Even the users who can authenticate but are not matching this filter will have access denied. IMPORTANT: if the authenticateOnly mode is turned on, this setting is ignored.

--- Group retrieval settings ---


Structured list


Group definitions should be defined under this prefix.

ldap.groups.<NUMBER> .matchByMemberAttribute



If this attribute is defined then it is assumed thet the members in the group entry are given with values of a single attribute (e.g. uid), not with their full DNs. This property defines this attribute (should be present on the user’s entry for which groups are searched).



mandatory to be set

Group’s entry attribute with group members. Usually something like member.




Group’s entry attribute with group’s name. If undefined then the whole DN is used.



mandatory to be set

Object class of the group.




Base DN under which all groups are defined. Groups need not to be immediatelly under this DN. If not defined, then groups are not searched for the membership of the user.




User’s attribute name which contains groups of the user, usually something like memberOf. If not defined then groups are not extracted from the user’s entry (but might be retrieved by scanning all groups in the LDAP tree).




If user’s attributes are read from memberOf (or alike) attribute, then this property may be used to extract the actual group name from its DN. If undefined then the DN will be used as group’s name. If defined then the group’s name will be the value of the attribute in the group’s DN with a name defined here.

7.3. External SAML IdP

Credential verificator name


Compatible credentials

SAML tokens

The SAML integration can be very challenging, as the protocol is enormously complex. We advise to read the SAML HOWTO

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:

unity.saml.requester.displayName=Remote SAML authentication

unity.saml.requester.remoteIdp.1.name=Simple SAMLPHP in Rohan

unity.saml.requester.remoteIdp.2.name=Shibboleth IdP in Gondor

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:

Property name Type Default value / mandatory Description

--- Common settings ---

unity.saml.requester.remoteIdp .<NUMBER>

Structured list

mandatory to be set

With this prefix configuration of trusted and enabled remote SAML IdPs is stored. There must be at least one IdP defined. If there are multiple ones defined, then the user can choose which one to use.

unity.saml.requester.remoteIdp .<NUMBER>.address


mandatory to be set

Address of the IdP endpoint.

unity.saml.requester.remoteIdp .<NUMBER>.binding



SAML binding to be used to send a request to the IdP.

unity.saml.requester.remoteIdp .<NUMBER>.certificate


mandatory to be set

Certificate name (as used in centralized PKI store) of the IdP. This certificate is used to verify signature of SAML response and included assertions. Therefore it is of highest importance for the whole system security.

unity.saml.requester.remoteIdp .<NUMBER>.groupMembershipAttribute



Defines a SAML attribute name which will be treated as an attribute carrying group membership information.

unity.saml.requester.remoteIdp .<NUMBER>.name



Displayed name of the IdP. If not defined then the name is created from the IdP address (what is rather not user friendly).

unity.saml.requester.remoteIdp .<NUMBER>.registrationFormForUnknown



Name of a registration form to be shown for a remotely authenticated principal who has no local account. If unset such users will be denied.

unity.saml.requester.remoteIdp .<NUMBER>.requestedNameFormat



If defined then specifies what SAML name format should be requested from the IdP. If undefined then IdP is free to choose, however see the acceptedNameFormats. property. Value is arbitrary string, meaningful for the IdP. SAML specifies several standard formats: urn:oasis:names:tc:SAML:2.0:nameid-format:persistent, urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress, urn:oasis:names:tc:SAML:1.1:nameid-format:X509SubjectName and urn:oasis:names:tc:SAML:2.0:nameid-format:transient are the most popular.

unity.saml.requester.remoteIdp .<NUMBER>.samlId


mandatory to be set

SAML entity identifier of the IdP.

unity.saml.requester.remoteIdp .<NUMBER>.signRequest

[true, false]


Controls whether the requests for this IdP should be signed.

unity.saml.requester.remoteIdp .<NUMBER>.translationProfile


mandatory to be set

Name of a translation profile, which will be used to map remotely obtained attributes and identity to the local counterparts. The profile should at least map the remote identity.

--- SAML validator specific settings ---

unity.saml.requester .acceptedNameFormats.*

list of properties with a common prefix


If defined then specifies what SAML name formatd are accepted from IdP. Useful when the property requestedNameFormat is undefined for at least one IdP.

unity.saml.requester .requesterCredential



Local credential, used to sign requests. If signing is disabled it is not used.



mandatory to be set

SAML entity ID (must be a URI) of the lcoal SAML requester (or service provider).

--- SAML web retrieval specific settings ---



SAML authentication

Name of the SAML authentication GUI component

--- SAML metadata settings ---




Last element of the URL, under which the SAML metadata should be published for this SAML authenticator.Used only if metadata publication is enabled. See the SAML Metadata section for more details.


filesystem path


If undefined then metadata is automatically generated. If this option is defined, then it should contain a file path, to a file with custom metadata document. This document will be published as-is, however it will be checked first for correctness.


[true, false]


Controls whether the SAML Metadata should be published under /metadata path.


[true, false]


Controls whether the SAML Metadata should be automatically signed before publishing it. If a publication of a custom matadata from file is confiured which is already signed, do not turn this option on, as then metadata will be signed twice.

7.3.1. SAML Metadata support

Many SAML services rely on the SAML Metadata format to configure trusted SAML agents. This can be done manually by creating and distributing such data out of bands, but Unity also allows to: - Automatically generate the metadata from the internal configuration. - Publish the metadata (generated or manually provided) so it can be downloaded. - Sign the metadata, both the generated or manually provided, before it is published.

Configuration reference provides the Metadata related settings. The metadata of an authenticator is published under the path /unitygw/saml-sp-metadata/NAME, where NAME is configurable with the unity.saml.requester.requesterCredential property and is used to distinguish the metadata of different SAML authenticators (as it is possible to configure more then one).

7.4. OAuth2

Credential verificator name


Compatible credentials

OAuth2 tokens

The typical authenticator’s configuration will look as follows:

unityServer.core.authenticators.x.authenticatorType=oauth2 with web-oauth2

Let’s consider an example of a configuration of the OAuth2 verificator in file conf/authenticators/remoteOAuth.properties:

unity.oauth2.client.displayName=OAuth2 authentication

unity.oauth2.client.providers.google.scopes=profile openid email


In the above example two providers are configured: Google and Facebook. You can select among several providers for which we have a predefined type, or use the custom type, however in the latter case you will have to provide a lot of complicated settings of the provider (see the reference table below). What’s more we can’t guarantee that each and every provider will work: OAuth2 is only a framework of a standard. There are providers which implement some earlier drafts also some of the providers follows some non-standard extensions.

In the case of a predefined provider one have to register the Unity service as an application at the providers service. Note that in some cases it may require paid account. During the registration a client identifier and secret are generated, which need to be configured in Unity (clientId and clientSecret). What’s more the provider typically should require to enter the client’s callback URL. For Unity it will be:


Links to client management pages of the well known providers:

As with every remote authenticator a translation profile must be provided to translate the remote user attributes to a local representation.

Finally you can override some of the default settings for the provider. The most useful is the scopes setting: it controls how much of the information is requested to be fetched from the provider (of course the user must agree to provide this level of access). Each provider uses different names for scopes so please check up providers documentation to learn the available values.

The complete OAuth options reference follows. First a general table shows what are the options pertaining to the whole authenticator, then a separate table shows the options which can be set for each OAuth2 provider.

Property name Type Default value / mandatory Description



OAuth2 authentication

Name of this authentication option to be displayed in the web interface

unity.oauth2.client.providers .*[.*]

Structured list can have subkeys

mandatory to be set

Prefix, under which the available oauth providers are defined.

Property name Type Default value / mandatory Description

unity.oauth2.client.CLIENT_ID .accessTokenEndpoint



Location (URL) of OAuth2 provider’s access token endpoint. In case of OpenID Connect mode can be discovered, otherwise mandatory.

unity.oauth2.client.CLIENT_ID .accessTokenFormat

[standard, httpParams]


Some providers (Facebook) use legacy format of a response to the access token query. Non standard format can be set here.

unity.oauth2.client.CLIENT_ID .authEndpoint



Location (URL) of OAuth2 provider’s authorization endpoint. It is mandatory for non OpenID Connect providers, in whose case the endopint can be discovered.

unity.oauth2.client.CLIENT_ID .clientAuthenticationMode

[secretPost, secretBasic]


Defines how the client secret and id should be passed to the provider.



mandatory to be set

Client identifier, obtained during Unity’s registration at the provider

unity.oauth2.client.CLIENT_ID .clientSecret


mandatory to be set

Client secret, obtained during Unity’s registration at the provider



mandatory to be set

Name of the OAuth provider to be displayed

unity.oauth2.client.CLIENT_ID .openIdConnect

[true, false]


If set to true, then the provider is treated as OpenID Connect 1.0 provider. For such providers specifying profileEndpoint is not mandatory as the basic user information is retrieved together with access token. However the discovery endpoint must be set.

unity.oauth2.client.CLIENT_ID .openIdConnectDiscoveryEndpoint



OpenID Connect Discovery endpoint address, relevant (and required) only when OpenID Connect mode is turned on.

unity.oauth2.client.CLIENT_ID .profileEndpoint



Location (URL) of OAuth2 provider’s user’s profile endpoint. It is used to obtain additional user’s attributes. It can be autodiscovered for OpenID Connect mode. Otherwise it must be set as otherwise there is no information about the user identity.

unity.oauth2.client.CLIENT_ID .registrationFormForUnknown



Registration form to be shown for the locally unknown users which were successfuly authenticated remotely.




Space separated list of authorization scopes to be requested. Most often required if in non OpenID Connect mode, otherwise has a default value of openid email

unity.oauth2.client.CLIENT_ID .translationProfile


mandatory to be set

Translation profile which will be used to map received user information to a local representation.


[custom, google, facebook, dropbox, github, microsoft]


Type of provider. Either a well known provider type can be specified or custom. In the first case only few additional settings are required: client id, secret and translation profile. Other settings as scope can be additionally set to fine tune the remote authentication. In the latter custom case all mandatory options must be set.

8. Consumer access: the endpoints

Endpoints make Unity features accessible to the outside world. There are several endpoint implementations (or types) and each of them can be deployed multiple times under different addresses with different settings. Such a deployed and configured endpoint type is simply called endpoint or endpoint instance.

Each endpoint supports a binding. Binding defines an access mechanism (e.g. SOAP Web Service or Web browser interface) and a technology in which it is programmed. Endpoints with the same binding share some basic configuration options.

Endpoints are configured in the main configuration file. An example endpoint definition:

unityServer.core.endpoints.1.endpointName=UNITY administration interface

The endpoint instance configuration must specify the endpoint type (in the example it is WebAdminUI), one of the available ones. Each available endpoint has a separate subsection later on, which provide its type name. The endpoint instance must be named (any string) - the name is displayed in various user interfaces.

Endpoint context path defines the first element of a server relative address of an endpoint. E.g. for the above context path /admin all URLs of the endpoint instance will start with the URL https://unity-hostname:unity-port/admin/....

Endpoint configuration file is used to specify endpoint type-specific configuration, including the binding specific settings.

The final configuration element of all endpoints is the configuration of authenticators. Endpoint can have many alternative authenticators enabled. Names of those authenticators must be separated with semicolon. Additionally an endpoint may require simultaneous authentication using more then one authenticator. In such case the required authenticators must be enumerated with a comma as a separator. In the above example the endpoint allows for choosing between two authentication methods: one will use a single authenticator simplePwdWeb and another alternative will require simultaneous authentication using certWeb and simplePwdWeb.

As it was mentioned there are options which are common for all endpoints with the same binding. Those options are presented here, the endpoint sections later on do not contain them.

For the Web Service (CXF) binding the common options are:

Options for all Web (Vaadin) endpoints are:

Property name Type Default value / mandatory Description


[true, false]


Controls if registration option should be allowed for an endpoint.

unity.endpoint.web .enabledRegistrationForms.*

list of properties with a common prefix


Defines which registration forms should be enabled for the endpoint. Values are form names. If the form with given name doesn’t exist it will be ignored.If there are no forms defined with this property, then all public forms are made available.

8.1. Web Admin UI endpoint

Endpoint type



Web (Vaadin)

Exposed paths


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.

8.2. User home endpoint

Endpoint type



Web (Vaadin)

Exposed paths


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.

8.3. Web SAML SSO endpoint

Endpoint type



Web (Vaadin)

Exposed paths

/saml2idp-web, /metadata

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:

Property name Type Default value / mandatory Description

--- SAML subsystem settings ---


Structured list


List of entries defining allowed Service Providers (clients). Used only for validRequester and strict acceptance policies.

unity.saml.acceptedSP.* .certificate



Certificate of the SP. Used only when acceptance policy is strict.




Rarely useful: for SPs which use DN SAML identifiers as UNICORE portal. Typically entity is used instead. Value must be the X.500 DN of the trusted SP.




Entity ID (typically an URI) of a trusted SAML requester (SP).




Response consumer address of the SP. Mandatory when acceptance policy is validRequester, optional otherwise as SAML requesters may send this addresswith a request.


Structured list


Prefix used to mark attribute filters.

unity.saml.attributeFilter.* .excluded.*

list of properties with a common prefix


List of attributes which should not be included in the SAML response. If this list is empty then no one is excluded. Otherwise all attributes matching any of the expressions are excluded. Those rules are used after inclusion rules.

unity.saml.attributeFilter.* .filteredRequester



Target of the filter. Leave undefined to create a default filter, otherwise add SAML requestor names for which the filter should be used. The first specific filter is used, if there is no spcific filter then the default is used.

unity.saml.attributeFilter.* .included.*

list of properties with a common prefix


List of attributes which should be included in the SAML response. If this list is empty then all are included. Otherwise only those attributes matching any of the expressions are included.


integer >= 1


Defines maximum time (in seconds) after which the authentication in progress is invalidated. This feature is used to clean up authentications started by users but not finished.



mandatory to be set

SAML IdP credential name, which is used to sign responses.



mandatory to be set

Default group to be used for all requesers without an explicite mapping.




Name of the SAML attribute which is used to carry the Unity group membership information.


Structured list


Prefix used to mark requester to group mappings.

unity.saml.groupMapping.* .mappingGroup


mandatory to be set

Group for the requester.

unity.saml.groupMapping.* .serviceProvider


mandatory to be set

Requester for which this entry applies.


[none, all, single, subgroups]


Which Unity groups should be inserted to the SAML group attribute. None disables the group reporting, single reports only the group configured for the requester. It can be also chosen to use all groups or subgroups of the group configured for the requester.



mandatory to be set

This property controls the server’s URI which is inserted into SAML responses (the Issuer field). It should be a unique URI which identifies the server. The best approach is to use the server’s URL. If absent the server will try to autogenerate one.


integer >= 1


Defines maximum validity period (in seconds) of a SAML request. Requests older than this value are denied. It also controls the validity of an authentication assertion.


[true, false]


If true then a single SAML assertion is returned what provides a better interoperability with 3rd party solutions. If false then attributes are returned in a separate assertion, what is required by certain consumers as UNICORE.


[always, never, asRequest]


Defines when SAML responses should be signed. Note that it is not related to signing SAML assertions which are included in response. asRequest setting will result in signing only those responses for which the corresponding request was signed.


[all, validSigner, validRequester, strict]


Controls which requests are authorized. all accepts all, validSigner accepts all requests which are signed with a trusted certificate, validRequester accepts all requests (even unsigned) which are issued by a known entity with a fixed response address, finally strict allows only requests signed by one of the enumerated issuers.




Truststore name to setup SAML trust settings. The truststore is used to verify request signature issuer, if the Service Provider accept policy requires so.


integer >= 1


Controls the maximum validity period of an attribute assertion returned to client (in seconds). It is inserted whenever query is compliant with SAML V2.0 Deployment Profiles for X.509 Subjects, what usually is the case.

--- SAML metadata settings ---


filesystem path


If undefined then metadata is automatically generated. If this option is defined, then it should contain a file path, to a file with custom metadata document. This document will be published as-is, however it will be checked first for correctness.


[true, false]


Controls whether the SAML Metadata should be published under /metadata path.


[true, false]


Controls whether the SAML Metadata should be automatically signed before publishing it. If a publication of a custom matadata from file is confiured which is already signed, do not turn this option on, as then metadata will be signed twice.

8.4. Web Service SAML SOAP endpoint

Endpoint type



Web Service (CXF)

Exposed paths

/saml2idp-soap, /metadata

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.

8.5. UNICORE Web SAML SSO endpoint

Endpoint type



Web (Vaadin)

Exposed paths

/saml2unicoreIdp-web, metadata

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.

8.6. UNICORE Web Service SAML SOAP endpoint

Endpoint type



Web Service (CXF)

Exposed paths

/saml2unicoreidp-soap, metadata

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.

9. Appendix A: Currently supported features

9.1. Core engine features

Feature Status Notes

Identities, entities


Attribute statements

Attribute classes

Updates are not yet implemented


Credential requirements

Upstream IdPs framework

Registration forms



Partially implemented, but not fully integrated.


Not yet available.

9.2. Local credentials

Feature Status Notes



Pseudo credential allowing for X.509 certificate login

One Time Passwords

Not yet available

Other credential/token systems

Not yet available

9.3. Endpoints

Feature Status Notes

SAML 2, Web SSO profile

SAML 2, SOAP binding

Web admin interface

REST admin interface

Not yet available

Web user profile management

Available however more functionality is required

SAML 2, Web binding + UNICORE profile

SAML 2, SOAP binding + UNICORE profile

OpenID Connect

Not yet available

OAuth 2

Not yet available

Other access protocols

Not yet available

9.4. Upstream IdPs

Feature Status Notes


SAML 2, Web SSO profile

OAuth 2

Tested with Facebook and Microsoft Live

OpenID Connect

Tested with Google

OpenID 2

Not yet available

OAuth 1

Not yet available

Other remote authentication protocols

Not yet available

9.5. Attribute syntaxes

Feature Status Notes



Integer number

Floating point number

JPEG image

Other types

Not yet available

9.6. Identity types

Feature Status Notes

User name

X.500 distinguished name (DN)

Persistent (anonymous)

Persistent,targeted (anonymous)

Transient,targeted (anonymous)

Opaque identifier

Other types

Not yet available