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. General Unity concepts

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

Endpoint

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.

Entity

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.

Identity

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.

Group

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.

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:
TAR.GZ RPM

bin/

/usr/sbin/

lib/

/usr/share/unity-idm/lib/

logs/

/var/log/unity-idm/

data/

/var/lib/unity-idm/data/

conf/

/etc/unity-idm/

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

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. Update

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.

  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. Start the new service.

The database dump can be created and loaded from the Web Admin UI, from the Server maintenance tab.

2.5. Crucial facts to know before the first start

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

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

  • The server is configured to run on localhost address on the port 2443.

  • The server uses an insecure credential (its private key is well known) issued by an insecure CA, which is the only one trusted CA.

  • 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 an 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).

2.5.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.

The distribution is set up to load demo contents. If you don’t need it - remove it from the configuration (see below how).

3. General server configuration

The server uses two main configuration files: conf/unityServer.conf and conf/log4j.properties. To change their default locations one needs to edit startup scripts.

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.

Currently the configuration is read only at startup so after any change a restart is required. We plan to deliver a better tooling, so the most common configuration updates won’t require the restart.

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.

    • 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.

  • HTTP server settings, where there are two important settings: hostname and port where the server listens. The rest is fairly advanced.

  • Server trust settings and the server credential, mostly used for SSL. This is documented separately in the subsections PKI/X.509 trust settings and Configuring the PKI credential.

  • Definitions of various artifacts of the server to be loaded: credentials, credential requirements, authenticators, endpoints and translation profiles. Note that the credentials and credential requirements 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

60

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.

unityServer.core.defaultLocale

string

en

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.

unityServer.core.initialAdminOutdated

[true, false]

true

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

unityServer.core.initialAdminPassword

string

admin

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

unityServer.core.initialAdminUsername

string

-

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

unityServer.core.initializers.<NUMBER>

list of properties with a common prefix

-

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

unityServer.core.mailConfig

filesystem path

-

A configuration file for the mail notification subsystem.

unityServer.core .recreateEndpointsOnStartup

[true, false]

true

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.

unityServer.core.templatesFile

filesystem path

conf/msgTemplates.properties

A file with the default message templates.

unityServer.core.threadPoolSize

integer number

4

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.

unityServer.core.workspaceDirectory

filesystem path

data/workspace

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

--- Content initializers: credentials ---

unityServer.core.credentials.<NUMBER>

Structured list

-

List of initially defined credentials

unityServer.core.credentials.<NUMBER> .credentialConfigurationFile

string

mandatory to be set

Credential configuration file

unityServer.core.credentials.<NUMBER> .credentialDescription

string

empty string

Credential description

unityServer.core.credentials.<NUMBER> .credentialName

string

mandatory to be set

Credential name

unityServer.core.credentials.<NUMBER> .credentialType

string

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

string

empty string

Credential requirement description

unityServer.core .credentialRequirements.<NUMBER> .credentialReqName

string

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

string

mandatory to be set

Authenticator name

unityServer.core.authenticators .<NUMBER>.authenticatorType

string

mandatory to be set

Authenticator type

unityServer.core.authenticators .<NUMBER>.localCredential

string

-

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

unityServer.core.authenticators .<NUMBER>.retrievalConfigurationFile

string

mandatory to be set

Authenticator configuration file of the retrieval

unityServer.core.authenticators .<NUMBER>.verificatorConfigurationFile

string

-

Authenticator configuration file of the verificator

--- Content initializers: endpoints ---

unityServer.core.endpoints.<NUMBER>

Structured list

-

List of initially enabled endpoints

unityServer.core.endpoints.<NUMBER> .contextPath

string

mandatory to be set

Context path of the endpoint

unityServer.core.endpoints.<NUMBER> .endpointAuthenticators

string

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

string

empty string

Description of the endpoint

unityServer.core.endpoints.<NUMBER> .endpointName

string

mandatory to be set

Endpoint name

unityServer.core.endpoints.<NUMBER> .endpointType

string

mandatory to be set

Endpoint type

--- Other ---

unityServer.core.credential.[.*]

string can have subkeys

-

Properties starting with this prefix are used to configure server’s credential. See separate table for details.

unityServer.core.httpServer.[.*]

string can have subkeys

-

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

unityServer.core.truststore.[.*]

string can have subkeys

-

Properties starting with this prefix are used to configure server’s trust settings and certificate validation. See separate table for details.

3.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

unityServer.db.localDBUrl

string

jdbc:h2:file:data/unity-localdb.bin

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

--- Database ---

unityServer.db.dialect

[h2, mysql, psql]

h2

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

unityServer.db.driver

Class extending java.sql.Driver

org.h2.Driver

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

unityServer.db.jdbcUrl

string

jdbc:h2:file:data/unitydb.bin

Database JDBC URL.

unityServer.db.password

string

empty string

Database password.

unityServer.db.username

string

sa

Database username.

3.2. 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.

In this section we refer to the configuration of the general trust store of the server, which is used to setup its network connection. However several subsystems allow for configuring their separate trust stores (e.g. the LDAP callout may use a different trust store to verify LDAP server certificate). In all the cases the configuration is the same, however the properties prefix may vary.

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.

Property name Type Default value / mandatory Description

unityServer.core.truststore.allowProxy

[ALLOW, DENY]

ALLOW

Controls whether proxy certificates are supported.

unityServer.core.truststore.type

[keystore, openssl, directory]

mandatory to be set

The truststore type.

unityServer.core.truststore .updateInterval

integer number

600

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

--- Directory type settings ---

unityServer.core.truststore .directoryConnectionTimeout

integer number

15

Connection timeout for fetching the remote CA certificates in seconds.

unityServer.core.truststore .directoryDiskCachePath

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.

unityServer.core.truststore .directoryEncoding

[PEM, DER]

PEM

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

unityServer.core.truststore .directoryLocations.*

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 ---

unityServer.core.truststore .keystoreFormat

string

-

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

unityServer.core.truststore .keystorePassword

string

-

The password of the keystore type truststore.

unityServer.core.truststore .keystorePath

string

-

The keystore path in case of truststore of keystore type.

--- Openssl type settings ---

unityServer.core.truststore .opensslNsMode

[GLOBUS_EUGRIDPMA, EUGRIDPMA_GLOBUS, GLOBUS, EUGRIDPMA, GLOBUS_EUGRIDPMA_REQUIRE, EUGRIDPMA_GLOBUS_REQUIRE, GLOBUS_REQUIRE, EUGRIDPMA_REQUIRE, EUGRIDPMA_AND_GLOBUS, EUGRIDPMA_AND_GLOBUS_REQUIRE, IGNORE]

EUGRIDPMA_GLOBUS

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 ---

unityServer.core.truststore .crlConnectionTimeout

integer number

15

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

unityServer.core.truststore .crlDiskCachePath

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.

unityServer.core.truststore .crlLocations.*

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)

unityServer.core.truststore.crlMode

[REQUIRE, IF_VALID, IGNORE]

IF_VALID

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

unityServer.core.truststore .crlUpdateInterval

integer number

600

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

unityServer.core.truststore .ocspCacheTtl

integer number

3600

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

unityServer.core.truststore .ocspDiskCache

filesystem path

-

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

unityServer.core.truststore .ocspLocalResponders.<NUMBER>

list of properties with a common prefix

-

Optional list of local OCSP responders

unityServer.core.truststore.ocspMode

[REQUIRE, IF_AVAILABLE, IGNORE]

IF_AVAILABLE

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

unityServer.core.truststore .ocspTimeout

integer number

10000

Timeout for OCSP connections in miliseconds.

unityServer.core.truststore .revocationOrder

[CRL_OCSP, OCSP_CRL]

OCSP_CRL

Controls overal revocation sources order

unityServer.core.truststore .revocationUseAll

[true, false]

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.

Examples

Directory trust store, with a minimal set of options:

unityServer.core.truststore.type=directory
unityServer.core.truststore.directoryLocations.1=/trust/dir/*.pem
unityServer.core.truststore.crlLocations=/trust/dir/*.crl

Directory trust store, with a complete set of options:

unityServer.core.truststore.type=directory
unityServer.core.truststore.allowProxy=DENY
unityServer.core.truststore.updateInterval=1234
unityServer.core.truststore.directoryLocations.1=/trust/dir/*.pem
unityServer.core.truststore.directoryLocations.2=http://caserver/ca.pem
unityServer.core.truststore.directoryEncoding=PEM
unityServer.core.truststore.directoryConnectionTimeout=100
unityServer.core.truststore.directoryDiskCachePath=/tmp
unityServer.core.truststore.crlLocations.1=/trust/dir/*.crl
unityServer.core.truststore.crlLocations.2=http://caserver/crl.pem
unityServer.core.truststore.crlUpdateInterval=400
unityServer.core.truststore.crlMode=REQUIRE
unityServer.core.truststore.crlConnectionTimeout=200
unityServer.core.truststore.crlDiskCachePath=/tmp

Java keystore used as a trust store:

unityServer.core.truststore.type=keystore
unityServer.core.truststore.keystorePath=src/test/resources/certs/truststore.jks
unityServer.core.truststore.keystoreFormat=JKS
unityServer.core.truststore.keystorePassword=xxxxxx

3.3. 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 well 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 options are optional. If not defined, the format is guessed. However some credential formats require additional settings. For instance if using der format the keyPath is mandatory as you need two DER files: one with certificate and one with the key (and the latter path can not be guessed).

Property name Type Default value / mandatory Description

unityServer.core.credential.path

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.

unityServer.core.credential.format

[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).

unityServer.core.credential.password

string

-

Password required to load the credential.

unityServer.core.credential.keyPath

string

-

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

unityServer.core.credential .keyPassword

string

-

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

unityServer.core.credential.keyAlias

string

-

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.

Examples

Credential as a pair of DER files:

unityServer.core.credential.format=der
unityServer.core.credential.password=SOME PASS
unityServer.core.credential.path=/etc/credentials/cert-1.der
unityServer.core.credential.keyPath=/etc/credentials/pk-1.der

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

unityServer.core.credential.path=/etc/credentials/server1.jks
unityServer.core.credential.password=xxxxxx

3.4. 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.authenticatorName=pwdWeb
unityServer.core.authenticators.2.authenticatorType=password with web-password
unityServer.core.authenticators.2.localCredential=secured password
unityServer.core.authenticators.2.retrievalConfigurationFile=conf/passwordRetrieval-config.json

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

password

Password

Local verificator.

ldap

Password

External verificator, uses LDAP.

certificate

X.509 certificate

Local verificator.

Retrieval Exchanges Compatible binding Description

web-password

Password

Web (Vaadin)

Uses textfield to collect a password

web-certificate

X.509 certificate

Web (Vaadin)

Uses client-authenticated TLS/SSL certificate

cxf-httpbasic

Password

Web Service (CXF stack)

Uses HTTP BASIC submitted password

cxf-certificate

X.509 certificate

Web Service (CXF stack)

Uses client-authenticated TLS/SSL certificate

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.

3.5. 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.host

string

localhost

The hostname or IP address for HTTPS connections.

unityServer.core.httpServer.port

integer [1 — 65535]

2443

The HTTPS port to be used.

--- Advanced settings ---

unityServer.core.httpServer .disabledCipherSuites

string

empty string

Space separated list of SSL cipher suites to be disabled.

unityServer.core.httpServer.fastRandom

[true, false]

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]

false

Controls whether to enable compression of HTTP responses.

unityServer.core.httpServer.gzip .minGzipSize

integer number

100000

Specifies the minimal size of message that should be compressed.

unityServer.core.httpServer .highLoadConnections

integer >= 1

200

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

100

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

unityServer.core.httpServer .maxIdleTime

integer >= 1

200000

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.

unityServer.core.httpServer.maxThreads

integer >= 1

255

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

unityServer.core.httpServer.minThreads

integer >= 1

1

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

unityServer.core.httpServer .requireClientAuthn

[true, false]

false

Controls whether the SSL socket requires client-side authentication.

unityServer.core.httpServer .soLingerTime

integer number

-1

Socket linger time.

unityServer.core.httpServer.useNIO

[true, false]

true

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]

true

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

3.6. 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 templates configuration file. Currently a template is a named pair of two strings: title and message body. What’s more the template can contain several variables which must be formated as:

${VARIABLE_NAME}

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

3.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
log4j.logger.net.sf.ehcache=WARN
log4j.logger.org.springframework=WARN
log4j.logger.org.eclipse.jetty=INFO
log4j.logger.unity.server=DEBUG
log4j.logger.unity.server.config=INFO
log4j.logger.org.apache=INFO
log4j.logger.pl.edu.icm=DEBUG
log4j.logger.pl.edu.icm.unity.db.mapper=INFO


#Configuration of appenders which performs actual logging

# LOGFILE is set to be a file appender using a PatternLayout with daily rolling.
log4j.appender.LOGFILE=org.apache.log4j.rolling.RollingFileAppender
log4j.appender.LOGFILE.RollingPolicy=org.apache.log4j.rolling.TimeBasedRollingPolicy
log4j.appender.LOGFILE.RollingPolicy.FileNamePattern=logs/unity-server.log.%d{yyyy-MM-dd}.gz
log4j.appender.LOGFILE.File=logs/unity-server.log
log4j.appender.LOGFILE.layout=org.apache.log4j.PatternLayout
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.

3.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:

log4j.logger.unity.server.config=DEBUG

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.

4. 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 (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

4.1. 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.

5. Integration of 3rd party Identity Providers

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

Data from external IdPs is accessed in a protocol specific way. The configuration of this part is described in 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.

5.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 height value from inches to centimeters and insert a remotely authenticated user to the local database (to the correct group) if the user is not yet there.

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

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

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

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

{
	"name": "PROFILE NAME",
	"description": "PROFILE DESCRIPTION",
	"rules": [
		{
			"condition": {
				"conditionValue": "RULE CONDITION"
			},
			"action": {
				"name": "ACTION NAME",
				"parameters": [
					ACTION-PARAM1,
					ASTION-PARAM2,
					...
				]
			}
		},

        ... OTHER RULES ...
    ]
}

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.

"conditionValue": "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

mapIdentity

replacedRE replacement credentialRequirement

Convert identity value to local representation & assigns credential requirement.

mapGroup

replacedRE replacement

Converts group to local representation.

mapAttribute

replacedRE replacement group

Convert attribute names and assign them to a local group.

createUser

withAttributes

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.

updateGroups

groupsRE

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.

updateAttributes

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": {
				"conditionValue": "true"
			},
			"action": {
				"name": "mapIdentity",
				"parameters": [
					"(.*)",
					"$1",
					"PasswordOnly"
				]
			}
		}

5.2. LDAP

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

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

Let’s consider an (complex) example:

ldap.servers.1=localhost
ldap.ports.1=389
ldap.userDNTemplate=cn={USERNAME},ou=users,dc=unity-example,dc=com
ldap.attributes.1=cn
ldap.attributes.2=sn
ldap.groupsBaseName=dc=unity-example,dc=com
ldap.groups.1.objectClass=posixGroup
ldap.groups.1.memberAttribute=memberUid
ldap.groups.1.matchByMemberAttribute=cn
ldap.groups.1.nameAttribute=cn
ldap.groups.2.objectClass=groupOfNames
ldap.groups.2.memberAttribute=member
ldap.groups.2.nameAttribute=cn

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 ---

ldap.attributes.*

list of properties with a common prefix

-

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

ldap.authenticateOnly

[true, false]

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.

ldap.connectionMode

[plain, SSL, startTLS]

plain

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.

ldap.ports.<NUMBER>

list of properties with a common prefix

-

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

ldap.referralHopLimit

integer >= 0

2

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

ldap.searchTimeLimit

integer number

60

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.

ldap.servers.<NUMBER>

list of properties with a common prefix

-

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

ldap.socketTimeout

integer >= 0

30000

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

ldap.translationProfile

string

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.

ldap.trustAllServerCertificates

[true, false]

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.

ldap.truststore.[.*]

string can have subkeys

-

Properties starting with this prefix are used to configure clients' trust settings for the TLS connections. See separate documentation for details.

ldap.userDNTemplate

string

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.

ldap.validUsersFilter

string

-

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 ---

ldap.groups.<NUMBER>

Structured list

-

Group definitions should be defined under this prefix.

ldap.groups.<NUMBER> .matchByMemberAttribute

string

-

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).

ldap.groups.<NUMBER>.memberAttribute

string

mandatory to be set

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

ldap.groups.<NUMBER>.nameAttribute

string

-

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

ldap.groups.<NUMBER>.objectClass

string

mandatory to be set

Object class of the group.

ldap.groupsBaseName

string

-

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.

ldap.memberOfAttribute

string

-

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).

ldap.memberOfGroupAttribute

string

-

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.

6. 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.endpointType=WebAdminUI
unityServer.core.endpoints.1.endpointName=UNITY administration interface
unityServer.core.endpoints.1.contextPath=/admin
unityServer.core.endpoints.1.endpointConfigurationFile=conf/webadmin.json
unityServer.core.endpoints.1.endpointAuthenticators=secPwdWeb;simplePwdWeb,certWeb

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:

Property name Type Default value / mandatory Description

unity.endpoint.ws .blockAfterUnsuccessfulLogins

integer >= 1

5

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

unity.endpoint.ws.blockFor

integer >= 1

60

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

Options for all Web Vaadin endpoints are:

Property name Type Default value / mandatory Description

unity.endpoint.web .blockAfterUnsuccessfulLogins

integer >= 1

5

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

unity.endpoint.web.blockFor

integer >= 1

60

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

unity.endpoint.web.enableRegistration

[true, false]

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.

unity.endpoint.web.sessionTimeout

integer >= 1

600

Defines maximum validity period (in seconds) of a web session.

6.1. Web Admin UI endpoint

Endpoint type

WebAdminUI

Binding

Web (Vaadin)

Exposed paths

/admin

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.

6.2. User home endpoint

Endpoint type

UserHomeUI

Binding

Web (Vaadin)

Exposed paths

/home

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.

6.3. Web SAML SSO endpoint

Endpoint type

SAMLWebIdP

Binding

Web (Vaadin)

Exposed paths

/saml2idp-web

This endpoint exposes the SAML 2 authentication interface, implementing the SSO profile of the SAML HTTP-POST binding. If you do not plan to use SOAP clients, this endpoint can be safely disabled.

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

The options of the endpoint (besides the standard ones for the binding) are:

Property name Type Default value / mandatory Description

unity.saml.credential.[.*]

string can have subkeys

-

Properties starting with this prefix are used to configure SAML IdP credential, which is used to sign responses. See separate documentation for details.

unity.saml.trustedIssuers.[.*]

string can have subkeys

-

Properties starting with this prefix are used to configure SAML trust settings. See separate documentation for details.

--- SAML subsystem settings ---

unity.saml.acceptedDNSP.<NUMBER>

list of properties with a common prefix

-

List of Service Providers which are allowed to redirect its clients for authentication and retrieval of ETDs and users attributes from this server. This property is used to configure SPs which use DN SAML identifiers as UNICORE portals. Each value must be a path to a file with certificate (in PEM format) of the SP.

unity.saml.acceptedUriSP.<NUMBER>

list of properties with a common prefix

-

List of Service Providers which are allowed to redirect its clients for authentication and retrieval of ETDs and users attributes from this server. This property is used to configure SPs which use URI SAML identifiers as Shibboleth SP. Each entry must contain two space separated tokens. The first token must be a URI of SAML service provider. The second token must be a path to a file with certificate (in PEM format) of the SP.

unity.saml.attributeFilter.*

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

string

-

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.

unity.saml.authenticationTimeout

integer >= 1

600

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.

unity.saml.defaultGroup

string

mandatory to be set

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

unity.saml.groupAttribute

string

memberOf

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

unity.saml.groupMapping.*

Structured list

-

Prefix used to mark requester to group mappings.

unity.saml.groupMapping.* .mappingGroup

string

mandatory to be set

Group for the requester.

unity.saml.groupMapping.* .serviceProvider

string

mandatory to be set

Requester for which this entry applies.

unity.saml.groupSelection

[none, all, single, subgroups]

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.

unity.saml.issuerURI

string

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.

unity.saml.requestValidityPeriod

integer >= 1

600

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.

unity.saml.signResponses

[always, never, asRequest]

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.

unity.saml.spAcceptPolicy

[all, validSigner, strict]

all

Controls which requests are authorized. All accepts all, validSigner accepts all requests which are signed with a trusted certificate, finally strict allows only requests signed by one of the enumerated issuers.

unity.saml.validityPeriod

integer >= 1

14400

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.

6.4. Web Service SAML SOAP endpoint

Endpoint type

SAMLSoapIdP

Binding

Web Service (CXF)

Exposed paths

/saml2idp-soap

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

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

6.5. UNICORE Web SAML SSO endpoint

Endpoint type

SAMLUnicoreWebIdP

Binding

Web (Vaadin)

Exposed paths

/saml2unicoreIdp-web

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

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

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

6.6. UNICORE Web Service SAML SOAP endpoint

Endpoint type

SAMLUnicoreSoapIdP

Binding

Web Service (CXF)

Exposed paths

/saml2unicoreidp-soap

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

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

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

7. Appendix A: Currently supported features

7.1. Core engine features

Feature Status Notes

Identities, entities

Groups

Attribute statements

Attribute classes

Updates are not yet implemented

Credentials

Credential requirements

Upstream IdPs framework

Registration forms

Preferences

Notifications

Partially implemented, but not fully integrated.

Auditing

Not yet available.

7.2. Local credentials

Feature Status Notes

Password

Certificate

Pseudo credential allowing for X.509 certificate login

One Time Passwords

Not yet available

Other credential/token systems

Not yet available

7.3. Endpoints

Feature Status Notes

SAML 2, Web SSO binding

Full metadata support is missing

SAML 2, SOAP binding

Full metadata support is missing

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 2

Not yet available

OAuth 1

Not yet available

OAuth 2

Not yet available

Other access protocols

Not yet available

7.4. Upstream IdPs

Feature Status Notes

LDAP

SAML 2, Web SSO binding

Not yet available

OpenID 2

Not yet available

OAuth 1

Not yet available

OAuth 2

Not yet available

Other remote authentication protocols

Not yet available

7.5. Attribute syntaxes

Feature Status Notes

String

Enumeration

Integer number

Floating point number

JPEG image

Other types

Not yet available

7.6. Identity types

Feature Status Notes

User name

X.500 distinguished name (DN)

URI

Not yet available

Other types

Not yet available