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.

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.

Authenticator

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

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.

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:
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 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.ignoreContentsReloadingFromConfiguration=true 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.

  • When a proper certificate is installed it is strongly advised to consider turning on the HSTS mechanism to improve server’s security (with unityServer.core.httpServer.enableHsts=true ).

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

  • After the first start consider commenting out the default admin user creation. You should use it only if you accidentally remove your last user with administrative privileges.

3.3. How to work with unity

  1. Make note on what you want to do with Unity:

    1. what are the planned clients, what protocols are going to be used to access Unity by those clients?

    2. whether external authentication services are going to be used, which ones, and with what protocols?

  2. Design the 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.endpointType=SAMLSoapIdP
unityServer.core.endpoints.5.endpointConfigurationFile=conf/endpoints/saml-webidp.properties
unityServer.core.endpoints.5.contextPath=/soapidp
unityServer.core.endpoints.5.endpointRealm=defaultRealm
unityServer.core.endpoints.5.endpointName=UNITY SOAP SAML service
unityServer.core.endpoints.5.endpointAuthenticators=pwdWS

It uses the (single) authenticator pwdWS:

unityServer.core.authenticators.3.authenticatorName=pwdWS
unityServer.core.authenticators.3.authenticatorType=password with cxf-httpbasic
unityServer.core.authenticators.3.localCredential=Password credential
unityServer.core.authenticators.3.retrievalConfigurationFile=conf/authenticators/empty.json

So lets define a new one, called certWS:

unityServer.core.authenticators.4.authenticatorName=certWS
unityServer.core.authenticators.4.authenticatorType=certificate with cxf-certificate
unityServer.core.authenticators.4.localCredential=Certificate credential
unityServer.core.authenticators.4.retrievalConfigurationFile=conf/authenticators/empty.json

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:

unityServer.core.endpoints.5.endpointAuthenticators=certWS

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. If you are updating with a revision release (change of the version number after the last dot only, e.g. 1.3.0 → 1.3.1 or 9.11.2 → 9.11.5) you can skip to the simplified Revision (bugfix) update instruction.

The update is a potentially dangerous operation, therefore we suggest to take two precautions:

  1. MANDATORY make a full database backup before starting the update.

  2. SUGGESTED make a test drive. To do this you need a separate instance of Unity service, with database copied from the production one. Update it first and only if everything goes OK, proceed with an update of the production instance.

After the precautions are done the update instructions are following.

When using the .tar.gz:

  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. Copy the config files of the old version and (if required) made any version specific modifications which are given below.

  3. Stop the old service.

  4. Start the new instance.

  5. Carefully check log files for any errors or warnings.

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

If using the RPM:

  1. Stop the old service.

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

  3. Check if any configuration files needs to be updated (see below, also search for .rpmnew files in /etc/unity-idm).

  4. Start the new service.

  5. Carefully check log files for any errors or warnings.

The database dump can be created and loaded from the Web Admin UI, from the Server maintenance tab. It can be used to transfer the Unity state between instances, can be also used as a backup tool. However in the upgrade case it is strongly suggested to make a regular database dump.

4.1. Revision (bugfix) update

From time to time a revision version of Unity is released. Such version is marked with a change of the last number in the distribution version only. When installing such revision release a simplified procedure can be taken. Database backup is advised as always, though in revision update the risk is minimal - revision releases typically do not introduce database changes.

When using the .tar.gz:

  1. Unpack the updated release

  2. Stop the server

  3. Replace the contents of the server’s lib/ directory with the contents of the lib/ directory of the updated package.

  4. Start the server

When using RPM distribution it is enough to update the package with your package manager and restart the server.

4.2. Version specific update instructions

The last component in the version string is irrelevant for the following instructions. For instance instructions for the 1.2.0→1.3.0 applies also to 1.2.0→1.3.1 and all other 1.3.x versions.

4.2.1. From pre-1.3.0 version

You should follow instructions and upgrade version by version. The update instructions are always available in the documentation of the version to which you are upgrading.

4.2.2. From 1.3.x to 1.4.0

There were no incompatible database or configuration changes. However to enable some of the new features (as Single Logout on SAML authenticator) additional configuration settings must be added according to documentation.

It can be noted that the maximum memory limit previously set to 256MB in startup.properties should be increased to 512MB.

4.2.3. From 1.4.0 to 1.5.0

There were small database schema changes in this release. The database should be updated automatically at when a new instance is started, however make sure to make a full back up after stopping the old version and before starting the new one.

4.2.4. From 1.5.0 to 1.6.0

Starting from the version 1.6.0 not only the libraries directory (as configured in startup.properties) is scanned for loading jar files, also all its subdirectories are. This feature can be used to load additional plugins, placed in a separate folders.

There were small database schema changes in this release. The database should be updated automatically at when a new instance is started, however make sure to make a full back up after stopping the old version and before starting the new one.

The 1.6.0 version introduces significant changes in user interface. Especially the authentication screen layout is changed and facilitates the new tiles feature, allowing for flexible arrangement of authentication options. The following changes in configuration are necessary:

  • All files served by the server (as images of 3rd party identity providers), set with the file:// URL are resolved against the theme directory used by endpoint. I.e. by default the files should be placed in the web contents directory (e.g. conf/webContents) and paths should be given relative to its VAADIN/themes/unityThemeValo directory. For instance if a file is stored in conf/webContents/VAADIN/themes/common/img/mypic.jpg it must be configured as file://../common/img/mypic.jpg.

  • Icon sizes configuration parameters found in SAML and OAuth authenticators (as width50) are now ignored. Instead scaling mode can be configured per endpoint in its authentication configuration. Scaling is no more fixed, it is using CSS class names (small, tiny, …​) which are controlled by theme and can be customized.

4.2.5. From 1.6.x to 1.7.x

First of all make sure you use Java 8.

Version 1.7.0 introduces one incompatible change wrt previous versions. There is a single redirect URL which can be defined for a registration form. Previously used redirect URL for requests which were auto accepted is not available any more. Instead the same URL is used, but has rich set of query parameters allowing consuming service to present appropriate content.

Starting from the version 1.7.1 an updated H2 DB engine is used (to fix problems with the older version). This change requires that all H2 relative paths are started from ./. E.g. jdbc:h2:file:./data/unitydb.bin;LOCK_TIMEOUT=10000;MVCC=TRUE is a correct path. Please update your configuration file (always for the local DB, and also for the main DB if it is using the H2 database).

In the version 1.7.2 a stricter email validation is implemented. This means that some addresses that were accepted by the previous Unity versions are not valid anymore. For instance some@@email.com or addresses with invalid DNS domain are not accepted. Due this change an import of database dump with invalid email addresses inside will not be loaded. You have to fix invalid addresses before importing, directly in the database dump.

5. Understanding authentication in Unity

Unity offers a LOT in terms of authentication. In this section we give an overview of what is possible and where to search the concrete settings.

First of all, as Unity often acts as authentication proxy it needs to be understood that by authentication in Unity we understand authentication Unity’s client, as performed for internal Unity purposes. This authentication can be (and often is) a part of a larger process, where an external service asks Unity to authenticate its client (e.g. using OAuth or SAML). However such fact is irrelevant: in Unity authentication works in the very same way regardless whether is was initiated by redirection from 3rd party service or directly by a person or agent accessing Unity.

Each Unity endpoint (regardless whether it is WebAdmin UI, web OAuth IdP or SOAP SAML Attribute Authority) requires its client to authenticate itself. Therefore administrator has to configure authentication per endpoint.

Authentication of an endpoint is controlled using two main elements:

  • Authentication realm - controls settings which may be shared by multiple endpoints with similar security requirements. Endpoints in the same realm share login sessions and all their settings. See Authentication realms and login sessions.

  • Assigned authenticators - each authenticator defines a unique authentication option as authentication with locally stored password or remote authentication with a help of a configured remote OAuth AS. See Authenticators.

Each endpoint can have many alternative authentication options. Options are provided by all enabled authenticators. Each authenticator can provide a single option (as the password authenticator) or many of them (as the remote SAML authenticator allowing to use all federation IdPs).

Authentication screen can be configured to organize the authentication options in a desired way. This is especially important if there is many of them. See Configuration of web authentication screen for details.

Unity can be configured to support MFA, however this feature is simplistic as of now. It will be enhanced in upcoming versions, the only currently available option is discussed in Consumer access: the endpoints.

5.1. Local authentication

Local authenticators use a locally stored credential to verify the client’s identity. Local authentication is simple in the sense that it can result only in two states: valid or invalid. Local authenticators have a very simple configuration (usually limited to a displayed name of the authenticator) as are using the configuration of an associated local credential.

Local authentication can be supported by the public registration forms. Each registration form which is marked as public (in the general settings of registration form) can be attached to the endpoint to offer the manual registration. Details on registration forms are given in Registration forms. For information how to configure registration forms for web endpoints (non-web endpoints naturally do not support this feature) see Configuration of web authentication screen.

The lost password reset feature can be configured in password credential configuration.

5.2. Remote authentication

Remote authentication is more complicated then the local authentication. In remote authentication an external authentication server is contacted and asked to authenticate the client. The details are dependent on actual authenticator: some redirect the user’s browser, some are contacting the remote server directly as in LDAP case.

Remote authenticator has a rather complex configuration. The authentication process using a remote authenticator works as follows:

  1. The remote authenticator contacts the remote server in a protocol specific way to obtain an information about the logged user.

  2. If the remote login was successful the remotely provided data is mapped to the local representation (translated, enhanced, filtered…​) using an input translation profile which is assigned to the authenticator. Input translation profiles are discussed in Translation profiles configuration. In effect of translation:

    • The remote user may be mapped to an existing account (at not-the-first login or when it is possible to automatically map remote user to local account using some attribute as email). In such case authentication is finished just after the translation.

    • The remote user may not be mapped to any identity. In such case authentication fails.

    • Finally a user (who is logging for the first time) may be mapped to an identity which does not exist in Unity database. In such case user can have a choice: either to fill a registration form to create a new local account or to associate the remote identity with an existing local account manually.

Registration of unknown users is performed by using a very flexible mechanism of registration forms described in Registration forms. To enable registration of unknown remote users a chosen registration form must be associated with an authenticator. See authenticator’s documentation for details how to do this. Note that some authenticators allow for setting different registration forms per each remote identity provider. Registration forms may be configured to be automatically or manually accepted, also subject to dynamic conditions.

Account association is enabled by default. It requires additional login to the existing account in a popup window. It can be turned off in authenticator settings.

Additionally it can be noted that translation profiles are very powerful. Translation profile can not only map the remote identity to a local representation but also it can be configured to automatically create identities missing locally. In such case neither registration nor association will be used as authentication will always complete.

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

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

[true, false]

false

If false Unity will show its confirmation screen after email verification. If true and a return URL is defined for the confirmation then the screen is not shown and redirect is immediate.

unityServer.core .confirmationRequestLimit

integer number

3

Defines number of confirmation request that can be send to particular address in day

unityServer.core.confirmationUITheme

string

-

Sets the theme used for rendering the confirmation UI (shown after confirming email etc).This setting overrides the default server theme.

unityServer.core.credential

string

mandatory to be set

Name of the credential to be used by the server.

unityServer.core.defaultLocale

string

en

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

unityServer.core .defaultPostConfirmationReturnURL

string

-

If set the value should be a valid URL. The URL is used as a return (redirect) URL to be used after confirmation of a verifiable element as email. Can be overriden for instance in registration form definition, for all confirmations related to the form.

unityServer.core.defaultTheme

string

-

Overrides the default theme name as used for rendering the web endpoints. This setting can be overriden per-endpoint. Applicable only for the web endpoints.

unityServer.core .defaultWebContentDirectory

filesystem path

webContent

Defines a default folder from which the web endpoints will serve static content, configured locally. Also used for the shared endpoint under /unitygw path.

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 .ignoreContentsReloadingFromConfigurat ion

[true, false]

false

If set to true then all configuration settings related to loading of database contents (endpoints, authenticators, credentials, …​) are ignored. This is useful in the case of redundant Unity instance, which should use the database contents configured at the master serevr.

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

[internalOnly, internalAndSyncPeers, internalAndAsyncPeers]

internalAndSyncPeers

Controls the way how the logout operation is performed. internalOnly will perform only a local logout. internalAndSyncPeers will also logout all remote session participants but only using a synchronous binding. Finally internalAndAsyncPeers will logout remote session participants also using asynchronous protocols (with web browser redirects) if needed. This last option is risky as it may happen that a faulty peer won’t redirect the web agent back.

unityServer.core.mailConfig

filesystem path

-

A configuration file for the mail notification subsystem.

unityServer.core.pkiConfigFile

filesystem path

conf/pki.properties

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

unityServer.core.templatesFile

filesystem path

conf/msgTemplates.properties

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

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

string

mandatory to be set

Name of the truststore to be used by the server.

unityServer.core .unityGWWebContentDirectory

filesystem path

-

Defines a folder from which all the web applications operating on the shared unitygw path (e.g. the email confirmation screen) will serve static content as images. Overrides the default webContent path.

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

-

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

-

Authenticator configuration file of the retrieval

unityServer.core.authenticators .<NUMBER>.verificatorConfigurationFile

string

-

Authenticator configuration file of the verificator

--- Content initializers: authentication realms ---

unityServer.core.realms.*

Structured list

-

List of authentication realm definitions.

unityServer.core.realms.* .blockAfterUnsuccessfulLogins

integer >= 1

5

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

unityServer.core.realms.*.blockFor

integer >= 1

60

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

-1

(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

1800

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

string

-

Realm’s description.

unityServer.core.realms.* .realmName

string

mandatory to be set

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

--- 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> .endpointDisplayedName[.*]

string can have subkeys

-

Endpoint displayed name. It is used whenever endpoint’s name is presented to the end-user, e.g. in top bars of web UIs. Localized values can be given with subkeys equal to locale name. If undefined then Unity will use endpointName

unityServer.core.endpoints.<NUMBER> .endpointName

string

mandatory to be set

Endpoint identifier. It is used to refer to this endpoint in other parts of the system.

unityServer.core.endpoints.<NUMBER> .endpointRealm

string

mandatory to be set

Authentication realm name, to which this endpoint belongs.

unityServer.core.endpoints.<NUMBER> .endpointType

string

mandatory to be set

Endpoint type

--- Other ---

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.

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

The primary database can use one of engines: H2 (embedded, no setup required), MySQL or PostgreSQL.

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

CREATE DATABASE unitydb;
GRANT ALTER, CREATE, DELETE, DROP, EXECUTE, INDEX, INSERT, LOCK TABLES,
 SELECT, TRIGGER, UPDATE 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:

unityServer.db.jdbcUrl=jdbc:mysql://localhost/unitydb
unityServer.db.dialect=mysql
unityServer.db.password=unitypass
unityServer.db.username=unity

6.1.2. PostgreSQL setup

The setup of PostgreSQL requires creation of a database with a separate role (user) which is able to connect to the database. Typically on Linux system you have to invoke:

createuser -P unity
createdb -O unity unitydb

using the desired database name, username and password. Of course any other tool can be used to create the user and database. Finally note that Postgres must allow for password authentication for the Unity user. Ensure that in pg_hba.conf you have a lines similar to those two:

host   all         all         127.0.0.1/32          md5
host   all         all         ::1/128               md5

If the database is on a different host then the Unity instance, change IP addresses to a proper ones.

Test if the connection works with:

psql -h localhost unitydb unity

and give the configured password.

Unity server will setup all tables automatically on startup.

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

unityServer.db.jdbcUrl=jdbc:postgresql://localhost/unitydb
unityServer.db.dialect=psql
unityServer.db.username=unity
unityServer.db.password=unitypass

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

unity.pki.certificates.*

Structured list

-

List of certificates.

unity.pki.certificates.* .certificateFile

string

mandatory to be set

Certificate file path (PEM format).

unity.pki.credentials.*

Structured list

-

List of credentials. The subkey defines the credential name.

unity.pki.truststores.*

Structured list

-

List of truststores. The subkey defines the truststore name.

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

.allowProxy

[ALLOW, DENY]

ALLOW

Controls whether proxy certificates are supported.

.type

[keystore, openssl, directory]

mandatory to be set

The truststore type.

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

.directoryConnectionTimeout

integer number

15

Connection timeout for fetching the remote CA certificates in seconds.

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

.directoryEncoding

[PEM, DER]

PEM

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

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

.keystoreFormat

string

-

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

.keystorePassword

string

-

The password of the keystore type truststore.

.keystorePath

string

-

The keystore path in case of truststore of keystore type.

--- Openssl type settings ---

.opensslNewStoreFormat

[true, false]

false

In case of openssl truststore, specifies whether the trust store is in openssl 1.0.0+ format (true) or older openssl 0.x format (false)

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

.opensslPath

filesystem path

/etc/grid-security/certificates

Directory to be used for opeenssl truststore.

--- Revocation settings ---

.crlConnectionTimeout

integer number

15

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

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

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

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

.crlUpdateInterval

integer number

600

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

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

.ocspDiskCache

filesystem path

-

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

.ocspLocalResponders.<NUMBER>

list of properties with a common prefix

-

Optional list of local OCSP responders

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

.ocspTimeout

integer number

10000

Timeout for OCSP connections in miliseconds.

.revocationOrder

[CRL_OCSP, OCSP_CRL]

OCSP_CRL

Controls overal revocation sources order

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

unity.pki.truststores.MAIN.type=directory
unity.pki.truststores.MAIN.directoryLocations.1=/trust/dir/*.pem
unity.pki.truststores.MAIN.crlLocations=/trust/dir/*.crl

Directory trust store, with a complete set of options:

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

Java keystore used as a trust store:

unity.pki.truststores.MAIN.type=keystore
unity.pki.truststores.MAIN.keystorePath=/trust/truststore.jks
unity.pki.truststores.MAIN.keystoreFormat=JKS
unity.pki.truststores.MAIN.keystorePassword=xxxxxx

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

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

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

.password

string

-

Password required to load the credential.

.keyPath

string

-

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

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

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

unity.pki.credentials.MAIN.format=der
unity.pki.credentials.MAIN.password=SOME PASS
unity.pki.credentials.MAIN.path=/etc/credentials/cert-1.der
unity.pki.credentials.MAIN.keyPath=/etc/credentials/pk-1.der

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

unity.pki.credentials.MAIN.path=/etc/credentials/server1.jks
unity.pki.credentials.MAIN.password=xxxxxx

6.2.3. Configuring 3rd party certificates

Some Unity subsystems require an access to a 3rd party service certificate, e.g. to check a digital signature issued by such service. The configuration of such standalone certificates is done as follows:

unity.pki.certificates.SOME-SERVICE-CERT.certificateFile=/etc/credentials/someServiceCert.pem

The certificate must be stored in a PEM file. The above configuration defines a certificate, which can be used in all Unity subsystems with the simple name SOME-SERVICE-CERT.

6.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 define different ways of authentication offered to end users. Each authenticator uses a fixed authentication technology as local password verification or remote OAuth authentication. Authenticator can provide one or more authentication options. This latter situation holds when authenticator allows a user to select among different identity providers. For instance OAuth authenticator can allow for selection of user’s identity provider as Google or Facebook. Sometimes more complex deployments may facilitate several authenticators of a single technology, when different Unity endpoints require different authentication settings (e.g. consumer-oriented endpoint may use SAML authentication in public SAML federation while admin-oriented endpoint may use SAML authentication in corporate federation).

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. This section covers also how to configure authentication screen, i.e. the visual composition of authenticators. This section is covering only functional definitions of authenticators, which can be used with many endpoints in various configurations.

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.

ldap-cert

X.509 certificate

External verificator, uses LDAP to resolve attributes of a given certificate subject.

certificate

X.509 certificate

Local verificator.

saml2

SAML assertions

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

jwt

JWT

Local verificator, not bound to any local credential. Validated tokens are self contained.

oauth2

OAuth tokens

External verificator, using OAuth Authorization Server or OpenID Connect provider.

oauth-rp

OAuth access token

External verificator, using OAuth Authorization Server or OpenID Connect provider.

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

web-saml2

SAML assertions

Web (Vaadin)

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

web-auth2

OAuth tokens

Web (Vaadin)

Allows to choose a remote OAuth Authorization Server redirects the user to authenticate there and collects the received authentication data.

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

cxf-jwt

JWT

Web Service (CXF stack)

Uses HTTP Bearer JWT tokens

cxf-oauth-bearer

OAuth access token

Web Service (CXF stack)

Uses OAuth bearer access token from HTTP Authorization header

rest-httpbasic

Password

RESTful (CXF stack)

Uses HTTP BASIC submitted password

rest-certificate

X.509 certificate

RESTful (CXF stack)

Uses client-authenticated TLS/SSL certificate

rest-jwt

JWT

RESTful (CXF stack)

Uses HTTP Bearer JWT tokens

rest-oauth-bearer

OAuth access token

RESTful (CXF stack)

Uses OAuth bearer access token from HTTP Authorization header

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. The allowed options follow.

The web-password retrieval offers 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.

The jwt verificator must be configured in the very same properties format as the JWT management endpoint uses.

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

unityServer.core.httpServer.gzip .enable

[true, false]

true

Controls whether to enable compression of HTTP responses.

--- General settings ---

unityServer.core.httpServer .advertisedHost

string

-

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 0.0.0.0 and also should be set whenver the server is listening on private interface accessible via DNAT or similar solutions.

unityServer.core.httpServer.host

string

localhost

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

unityServer.core.httpServer.port

integer [0 — 65535]

2443

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

--- Advanced settings ---

unityServer.core.httpServer .disabledCipherSuites

string

empty string

Space separated list of SSL cipher suites to be disabled. Names of the ciphers must adhere to the standard Java cipher names, available here: http://docs.oracle.com/javase/8/docs/technotes/guides/security/SunProviders.html#SupportedCipherSuites

unityServer.core.httpServer.enableHsts

[true, false]

false

Control whether HTTP strict transport security is enabled. It is a good and strongly suggested security mechanism for all production sites. At the same time it can not be used with self-signed or not issued by a generally trusted CA server certificates, as with HSTS a user can’t opt in to enter such site.

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

unityServer.core.httpServer .xFrameAllowed

string

http://localhost

URI origin that is allowed to embed web interface inside a (i)frame. Meaningful only if the xFrameOptions is set to allowFrom. The value should be in the form: http[s]://host[:port]

unityServer.core.httpServer .xFrameOptions

[deny, sameOrigin, allowFrom, allow]

deny

Defines whether a clickjacking prevention should be turned on, by insertionof the X-Frame-Options HTTP header. The allow value disables the feature. See the RFC 7034 for details. Note that for the allowFrom you should define also the xFrameAllowed option and it is not fully supported by all the browsers.

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

${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. 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.

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

unityServer.core.realms.1.realmName=lowSecurityRealm
unityServer.core.realms.1.blockAfterUnsuccessfulLogins=10
unityServer.core.realms.1.blockFor=30
unityServer.core.realms.1.maxInactivity=3600
unityServer.core.realms.1.enableRememberMeFor=3

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

unityServer.core.endpoints.N.endpointRealm=lowSecurityRealm

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.

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

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

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

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

7.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. Such forms are called as public.

  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.

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. Additionally all public forms get its own public address which can be used to directly launch a form. This address is constructed from the form name and can be seen in the form viewer after selecting an existing form in the AdminUI (Registrations management → Registration forms).

Finally a form can be associated with a remote authenticator as a "handler" for unknown users who were correctly authenticated remotely. For this last case typically the form should not be public. It is also crucial to configure the input translation profile of the authenticator so it does not create a local user automatically. Otherwise the configured form won’t ever be launched as the local user will be always present after translation profile execution.

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.2.1. Defining a registration form

The form definition consists of three parts:

  1. General settings as name, notifications configuration, auto accept condition 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.

The most important are the settings of the 2nd point, i.e. the data collected about the user. Each of the identities, group memberships and attributes can be collected in different modes. Some of the modes are only relevant for a case when a registration form is presented to an unknown user who was authenticated by a remote IdP. The modes are as follows:

Collected interactively

A user interface component is displayed to collect the information from a user.

Provided by remote IdP only and is shown in the form

The information must be provided by a remote IdP. It is then shown to a user in the form, but can not be edited.

Provided by remote IdP only and is hidden in the form

As above but the information is not shown on the form filling screen.

Can be provided by remote IdP; if not then collected interactively

In this mode the user can fill the data only if it was not provided by a remote IdP.

Can be provided by remote IdP and is editable

The field is always editable, but if a remote IdP provided a value then it is used as a default.

Additionally all pieces of collected information can be made optional. The other types of collected information: agreements and credentials can be only collected interactively, therefore there is no mode selection in their case.

7.2.2. Automatic request acceptance

Registration request can be automatically accepted after submission, if it meets the Auto accept condition defined in the associated registration form. The Auto accept condition is given as an MVEL expression, which must evaluate to a boolean value (true or false). Condition operates on a data structure filled during registration request creation, which contains:

  1. attr Map indexed with attribute names. Value of each entry is a single value of the attribute. If the attribute is multi-valued then the first value is returned. If the attribute has no value then empty string is returned.

  2. attrs Map indexed with attribute names. Value of each entry is a list of the attribute values.

  3. idsByType Map of identity values indexed by type.

  4. idsByTypeObj Map of identity objects indexed by type. This map is harder to use then idsByType (which holds strings) but offers access to full information stored in identity as its confirmation state.

  5. groups List of selected groups.

  6. agrs List of agreements. Each agreement is boolean type.

The full MVEL documentation can be found here https://en.wikisource.org/wiki/MVEL_Language_Guide

Example of auto accept conditions:

Accept request with email attribute.

attrs["email"][0] == "foo@a.b"

Accept request if contain identity of x500Name type.

idsByType["x500Name"] != null

Accept a request only if the first agreement was accepted.

agrs[0] == true

Accept a request if the first email type identity is confirmed.

idsByTypeObj["email"][0].confirmed == true

7.2.3. Redirections

After filling a registration form a user can be redirected to a given address. This is useful especially in many integration scenarios when registration is launched in a part of bigger process.

When defining a form a single registration URL can be defined. If given a registering user will redirected to this URL after filling a form. Additional query parameters are filled by Unity to inform a target service about the details of the request.

The easiest way to check the resulting redirection URL is to play with filling a form directly from the AdminUI. In such case redirection is not performed but a notification message is presented with a full redirection URL included.

The possible query parameters are:

  1. status one of submitted, submittedAccepted (if auto accept condition triggered request acceptance), submittedWithError, cancelled, elementConfirmed, elementConfirmationError. The last two are used after confirming elements as email of the form.

  2. error_code more detailed information about error in case of error status

  3. form_id identifier of the form, may be missing in rare cases

  4. request_id request identifier, may be missing in rare cases

  5. confirmed_element_type one of identity or attribute

  6. confirmed_element_name

  7. confirmed_element_value

7.3. Identities and entities

Unity represents principals as entities. Entity is a logical element symbolizing, the principal. Each entity must have at least one concrete representation which is called identity.

Identities in Unity have its type, which defines the syntax, comparison rules etc. of the value.

Regular identities can be created manually by administrators, imported from external IdPs with a help of input translation profile or added in effect of registration request acceptance. There is also a special category of identities: dynamic or automatic identities. Those identities are special in this sense that their values are assigned by Unity itself - administrator is able to only see their values and optionally can remove the values.

The following table describes all available identity types:

UNITY identity type Category Description

userName

regular

User name, compared with simple string equality. This type of identity can be used for all password-alike authentications in Unity.

identifier

regular

Generic identifier, compared with string equality. It is useful to represent remotely assigned user identifiers and to match against them during subsequent authentications. It is not possible to directly login with this identity type.

x500Name

regular

X.500 name or a Distinguished Name (DN). Used in case of TLS/SSL authentication. The equality is tested on canonical form of DN.

email

regular

Email address identity, compared with simple string equality. This type of identity can be used for all password-alike authentications in Unity. The value of this identity is subject of confirmation process.

persistent

automatic

An automatically assigned anonymous identifier. Should be constant for each entity for its lifetime (and is unless manually removed).

targetedPersistent

automatic

An automatically assigned anonymous identifier. It is different from the persistent type as for each of Unity clients (targets) a different identifier is maintained.

transient

automatic

An automatically assigned anonymous identifier. It is very similar to targetedPersistent, the only difference is that the identifier is regenerated for each login session.

7.4. E-mail confirmations

Unity provides a powerful support for verifications of e-mail addresses. Both e-mail identities and e-mail attributes can be verified. In case of e-mail attribute each value is confirmed separately.

As this functionality touches many different areas of Unity functionality we group all the related information here.

7.4.1. Confirmations setup

To enable confirmations the following basic elements needs to be configured:

  1. The E-mail notification channel must be configured.

  2. There must be a message template (or templates) suitable for use with confirmation facility. See Notifications and e-mail settings.

  3. To confirm attributes at least one attribute type must be defined which will use the verifiableEmail syntax. What’s more each such attribute type must have confirmations enabled and configured by selecting a proper message template (see below).

  4. To confirm email identities, identity confirmations must be enabled and configured by selecting a proper message template (see below).

The configuration of confirmations (for identities and for each email attribute type) is performed in the Server management → Confirmations configuration tab of the Admin UI. It is rather simplistic as the only really variable property is the template to be used.

Note that Unity contains a convenient content initializer which can be enabled in the unityServer.conf to load default confirmation configurations on startup:

unityServer.core.initializers.3=confirmationsInitializer

Later in this section we assume that the confirmations were set up as was described above.

7.4.2. When confirmations are sent?

Whenever an email attribute or identity is created or changed manually in Unity interface the confirmation message is sent. The sole exception is a change of an attribute by administrator via the Admin UI: it is possible to control whether the attribute value should be added as confirmed or not.

Confirmations are also sent whenever a registration request is submitted, with an e-mail attribute or identity which was collected from the user filling the form. The attributes and identities collected from remote IdPs can be assumed be verified (depending on the input translation profile, see below).

The confirmations are not sent when an attribute is updated and some of the values are preserved. Also already sent confirmations are not repeated during attribute update. E.g. if there is an attribute with two email values a@example.com (confirmed) and b@example.com (unconfirmed, with confirmation request already sent), and a user changes the attribute by adding a new attribute c@example.com only one confirmation request will be sent (for c@example.com), and the confirmed status of a@example.com will be preserved.

Unity also takes care not to resent a confirmation if the same e-mail address was used for both identity and attribute (or multiple attributes). Then only a single confirmation is sent and is used to confirm all elements.

It is also possible to reset a confirmation state by the administrator (from Admin UI) by setting the unconfirmed state of an attribute value.

7.4.3. Registration forms and confirmations

Registration form including e-mail identities and/or attributes will have the confirmations automatically sent on submit. If the request is accepted before the user confirms its e-mail(s) then the confirmations are applied to e-mail/attribute of the already created entity. Otherwise are only recorded in the request. Administrator can always check confirmation status on the request review panel.

It is also possible to use email or identity confirmation status as auto accept condition. This means that the auto-accept condition is evaluated not only after request submission, but also after the request is updated in confirmation effect. The auto acceptance rules for email attribute and identity (respectively) are as follows:

attr["email"].confirmed == true
idsByTypeObj["email"][0].confirmed == true

7.4.4. Special encoding of emails

When setting an email value from translation profile of via REST API it might be necessary to set the email’s metadata.

To control an attribute or identity confirmation state, the regular e-mail value must be followed with the special suffix [CONFIRMED] or [UNCONFIRMED] (case sensitive, without spaces between the last character of email address). The default value is unconfirmed. For instance assuming that the remote IdP provided an attribute emailAddress and we assume that this address should be treated as already confirmed the following expression will produce a proper value for the mapAttribute action:

attr["emailAddress"] + "[CONFIRMED]"

To control whether an address is designated as a main (primary) contact address one can use email tag main in an email value provided to Unity (via REST or in input profile) as follows:

someuser+main@example.com

Of course the tag main can be used together with confirmation. Currently no other email tags are used by Unity.

7.4.5. User control of e-mail address

If the email attribute type is set as self modifiable, the user can edit its value on its own. To enable it also the Home UI must be configured to allow for this.

There is one special rule regarding edit of the e-mail attribute by an ordinary user: if the attribute has at least one confirmed value, then after changing the values also at least one confirmed value must be present.

Currently this rule is hardcoded, but in future we may enable its configuration in attribute type.

7.4.6. Authentication with e-mail identity

Authentication with e-mail identity can be used in the very same way as authentication with a plain username identity. Both identity types works out of the box with the password credential.

The only difference is that a user can not authenticate with e-mail identity if it was not confirmed.

7.5. Internationalization & UI translations

Unity offers internationalization (i18) features out of the box. However the list of available languages is hardcoded and currently includes only English (en), Polish (pl) and German (de) locales. English locale is the default one and all default messages are in this language. The Polish translation is mostly complete with the exception of the Admin UI. German is currently empty. Administrator can configure which of the supported locale are enabled (see unityServer.conf documentation).

If you would like to have other locale supported please contact us via the mailing list - there is no problem to add them.

What is more Unity allows you to provide all names which are configurable by administrator in multiple languages. The user interface shows a small flag on right-top edge of each translatable component. After expanding the component, the translations in all enabled languages can be provided.

Unity allows for translating admin-provided names

8. Web interface branding

Unity interface appearance can be customized to match the owning organization preferences.

Customization is based on SASS http://sass-lang.com/ (a superset of CSS), using its preferred SCSS syntax. Theoretically it is possible to prepare the theme purely in CSS but due to complex requirements in practice SASS usage is mandatory.

Unity themes are placed in a configured directory. Each theme is named and the server is configured with a selected theme as follows (in unityServer.conf):

unityServer.core.defaultWebContentDirectory=webContents
unityServer.core.defaultTheme=unityThemeValo

What is more the theme can be changed per endpoint in endpoint’s configuration. Actually two themes can be set: one for the main user interface and one for the endpoint’s authentication screen. Endpoint can also use a separate directory with theme files and other web resources. For instance:

unity.endpoint.web.mainTheme=customTheme
unity.endpoint.web.authnTheme=customAuthnTheme
unity.endpoint.web.webContentDirectory=webContents-homeEndpoint

There are couple of facts that it might be useful to know:

  • All files (e.g. images) served by Unity must be present in the web content directory used for the endpoint in question.

  • While authentication screen and the main endpoint UI can have different themes the web contents directory is always common.

  • Sandboxed authentication UI (used during account association or during translation profile wizard run) uses the same theme as the endpoint’s main authentication UI.

  • Confirmation screen shown after email confirmation uses the default theme or the one configured separately with the unityServer.core.confirmationUITheme option.

8.1. Preparing a custom theme

Each theme is placed in a separate subdirectory of the VAADIN/themes folder (placed in the web contents directory as described above). Subdirectory must be named as the style. Unity uses the styles.css file in the theme directory as the web interface style. If the styles.css is not found but there is a styless.scss file then it is compiled on the fly to CSS and used. This later scenario is not suggested for production, see below how to compile the theme.

Distribution contains one production theme called unityThemeValo which is based on the Vaadin’s Valo theme (Vaadin is underlying technology of the Unity’s web interface). Usage of the Valo theme as the base is not mandatory, but highly preferred and easiest choice. Valo theme is highly configurable and can be customized to a large degree. Valo theme is documented here is: https://vaadin.com/valo and API is documented https://vaadin.com/api/valo/ .

There is also one example theme called customTheme. Both of them are based on SASS partial placed in the common directory. unityThemeValo is simply reusing the whole partial as-is. customTheme is introducing several small changes as disabling the blue background of the top bar and displaying a Unity logo there.

Strongly suggested structure of a theme is using two SCSS files: styles.scss (this name is mandatory) and STYLE-NAME.scss. The first file should merely include the definitions from the second file allowing to store the style in properly named file.

Typically the custom theme should be created basing on the customTheme example:

  • create a theme folder under VAADIN/themes e.g. myTheme

  • create myTheme/styles.scss, myTheme/favicon.ico and myTheme/myTheme.scss basing on the custom theme as template.

  • introduce changes in the myTheme/myTheme.scss

The exampleTheme contains a lot of comments which should help to understand the structure. In case when large changes are introduced it might be easier to copy the common partial and modify it directly.

8.2. Compiling SASS theme

Manual compilation of a theme is a suggested approach as it improves server performance and allow to detect syntax errors early.

Unity provides a simple command line utility that compiles a given theme.

$> unity-idm-scss-compile conf/VAADIN/themes/myTheme

The sole argument to the utility is a directory with the source styles.scss file.

9. Translation profiles configuration

Translation profile is a named, ordered list of conditional rules. The rules are used to modify the information about a principal being processed by Unity. Such situation occurs when:

  1. Remote user was externally authenticated and its data is consumed by Unity. In this case translation is performed by so called input translation profiles.

  2. Information about Unity’s entity is being exposed to outside world with an IdP-like endpoint as SAML web endpoint. In this case translation is performed by so called output translation profiles.

For instance, an input translation profile can change remote attribute size name to width and insert a remotely authenticated user to the local database (to a desired group) if the user is not yet there. An output profile can return an additional dynamic identity named email with a value of an email attribute.

The following subsections cover both types of translation profiles in details. Though many of the features are common. The profiles are managed with the Admin UI in the Server management→Translation profiles tab. The profile has a name and a list of rules. Each rule has a condition and an action.

Conditions are used to dynamically turn action execution on or off. Conditions (as well as some of the arguments of translation actions have) have to be specified as MVEL expressions. Such expressions allow for a powerful, dynamic functionality.

The full MVEL documentation can be found here: https://en.wikisource.org/wiki/MVEL_Language_Guide

The following example condition:

attr contains 'cn'

will trigger an action whenever the subject has an attribute cn. In the following sections there are additional examples and a complete reference of all variables which are available to write conditions. Nevertheless the most popular condition is simply: true.

Actions are different for each type of the profile. The editor provides you with helpful interface to create them.

9.1. Input translation

An input translation profile is always associated with a remote authenticator in its configuration. It is a mandatory setting, all remote authenticators must have one profile associated. This is because it is typically not possible to provide a sensible default mapping of remote data to the configurable schema used in Unity.

Input 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. Attributes provided by the remote IdP.

  3. Groups assigned by the remote IdP.

What data is actually in this structure is dependent on the upstream protocol, upstream server and callout configuration.

Profile actions map remote data to Unity artifacts. For instance mapped result can be an attribute of type cn with some dynamic value. The value is completely controllable with a MVEL expression and can be anything from a simple direct reuse of remotely provided attribute to a sophisticatedly crafted string. It might be good to take a look at the example profile below.

Each profile should be started from a mandatory identity mapping. It is possible to control whether the remote identity should be matched against the local one and/or automatically created. Note that the identity mapping result decides how the general login process looks like: if a profile maps a user to an existing user (also by creating an new entity) login will proceed automatically. If the profile maps the remote user to some not existing identity then Unity can be configured to present a registration form or account association dialog. Finally if remote user is not mapped to any identity the login fails.

There are several so called identity mapping effects which are important for the remote user mapping process:

  1. CREATE_OR_MATCH if the mapped identity doesn’t exist it is automatically created. If it exists then the remote user is mapped onto this entity what sets the context for all other profile actions.

  2. MATCH The remote user is mapped onto existing entity it it is found. Otherwise nothing happens.

  3. REQUIRE_MATCH The remote user is mapped onto existing entity it it is found. Otherwise authentication is failed.

  4. UPDATE_OR_MATCH is the most tricky option, similar to CREATE_OR_MATCH. The remote user is mapped onto an existing one if it exists. Conversely if the resulting identity does not exist in the system, then it is created but only if additionally the remote user was already mapped onto existing entity by other rules of the profile. This complicated behavior is actually quite useful whenever we want to have new remote identities propagated to the existing user in Unity, but at the same time we don’t want to have a new user (entity) created automatically (what would be CREATE_OR_MATCH effect), so that a registration facility can be used.

Additionally the actions allow for creating Unity’s attributes, assigning the remote user to groups and to change entity status.

One action requires a special attention: removeStaleData. This action, when added to a profile, causes Unity to remove all stale data: attributes, group memberships, identities. The data is assumed to be stale if it was previously created by the same profile, basing on input from the same remote IdP and which was not reproduced during the current invocation of the profile.

9.1.1. Translation profile creation wizard and dry-run

Unity provides two sophisticated features helping in input translation profile management. First of all it is possible to use a translation profile creation wizard.

The wizard can be activated from the Server management→Translation profiles view. Currently the wizard can be used to create a profile basing on an available remote authenticator, so you need to configure it first in a regular way. However any (even empty) translation profile can be initially set for this authenticator.

After launching the wizard a popup window appears allowing you to select any of the remote authenticators available in the system (regardless of their assignment to endpoints). The authentication is performed in a sandbox environment so it is not influencing the running system. After finishing the remote authentication the popup window disappears and a visual translation profile editor is displayed. The whole information received from the remote IdP is shown, and can be dragged into expressions of the profile being created. After the profile is configured it must be saved and can be assigned to the authenticator.

Besides the wizard it is also possible to perform a detailed testing of an already existing translation profile. This dry run feature is available from the same menu as the wizard and begins in the same way: with a sandboxed authentication. However, the last step is different: instead of an editor a detailed information on the profile’s application to the data provided by remote IdP is presented, including even the relevant server’s log.

9.1.2. Reference

MVEL context reference:

  1. idp Name of the IdP which provided the data

  2. attr Map indexed with attribute names. Value of each entry is a single value of the attribute. If the attribute is multi-valued then the first value is returned. If the attribute has no value then empty string is returned.

  3. attrs Map indexed with attribute names. Value of each entry is a list of the attribute values.

  4. id Value of the authenticated identity. If remote IdP returned multiple identities, then a random one is available, though this is a very exotic case.

  5. idType The type of the identity stored in the id variable.

  6. idsByType Map of identity values indexed by type. Rarely useful.

  7. groups List of all remote groups.

Actions as mapGroup, mapIdentity or mapAttribute can be used with an expression returning either a single value or a collection of values.

Example input profile:

1: Condition: true
Action: mapIdentity
Action parameters:
  unityIdentityType = userName
  expression = attr['urn:oid:2.5.4.3']
  credential requirement = Password requirement
  effect = CREATE_OR_MATCH

2: Condition: true
Action: mapAttribute
Action parameters:
  unityAttribute = cn
  group = /
  expression = attr['urn:oid:2.5.4.4']
  visibility = full
  effect = CREATE_OR_UPDATE

3: Condition: groups contains 'student'
Action: mapGroup
Action parameters:
  expression = '/A/B'

The above profile in the first action maps the attribute urn:oid:2.5.4.3 value to Unity identity of userName type. Such identity will be created if doesn’t exist, otherwise all other actions will be performed against the existing local identity with such userName. Subsequently the remote attribute urn:oid:2.5.4.4 value will be mapped to Unity attribute cn and the attribute will be assigned in the root group if it doesn’t exist. If it does, its value will be updated (upon each login). Finally the user will be added to the /A/B group assuming it is in the student group as reported by the remote IdP.

9.1.3. Example expressions

The most often used condition:

true

Condition disabling the action:

false

Condition testing if a principal is a member of the students group (which is a group at the remote IdP):

groups contains 'students'

Condition testing if a principal has the cn attribute:

attr contains 'cn'

When writing expressions in actions, usually we need a string value. For instance here is the first value of the cn attribute:

attr['cn']

All values (list) of the same attribute:

attrs['cn']

It is also possible to glue many values. Let’s create a DN, which can be used to dynamically create an identity:

'CN=' + attr['cn'] + ',O=' + attr['o'] + ',C=NO'

MVEL provides convenient operations on list of values too. The following expression converts a list of groups (as returned by remote IdP, e.g. LDAP) to unity groups. A constant prefix /it/groups/ is added and 3 initial characters are removed from the external group name, but only of the group name has at least 4 characters.

('/it/groups'+$.substring(3) in groups if $.length() > 3)

Finally the value of the identity provided by remote IdP is available as follows:

id

9.2. Output translation

An output translation profile can be associated with an IdP-like endpoint as the SAML endpoints. It can be used to filter the data being exposed (so called attribute release policies can be implemented with output profiles). Also it can dynamically create additional data to be returned. It is even possible to store the dynamically created data back into the local Unity database, so it becomes a regular data.

Configuration of output profiles is optional. If no profile is manually installed on an endpoint, then a so called default output profile is used. The default profile is simplistic: it doesn’t filter anything and anly adds one additional attribute: memberOf with all groups of the principal as value.

Output translation profile operate on a data structure which is initially filled by Unity with all attributes and identities of the queried principal. Attributes are from the group configured in the endpoint.

MVEL context used in conditions and as value of some action parameters can use the following variables:

  1. protocol Name of the protocol being used

  2. protocolSubtype Name of the protocol variant

  3. requester Name of the requester

  4. usedGroup Unity group from which attributes are served

  5. subGroups All sub groups of the Unity group from which attributes are served

  6. attr Map indexed with principal’s attribute names. Value of each entry is a single value of the attribute. If the attribute is multi-valued then the first value is returned. If the attribute has no value then empty string is returned.

  7. attrs Map indexed with attribute names. Value of each entry is a list of the attribute values.

  8. idsByType Map of identity values indexed by type.

  9. groups List of all groups the user is a member.

  10. authenticatedWith List of identities that were used to authenticate the user. If remote authentication was used the list contains a single identity that was used to map the remote user to the local entity (as chosen by the input translation profile). The list can have two elements when MFA was used.

  11. idp Identifier of a remote IdP that was used to authenticate the current user’s session. In case when only a local authentication was used, the value is set to _LOCAL.

Example output profile:

1: Condition: idsByType contains 'userName'
Action: createAttribute
Action parameters:
  attributeName = userid
  expression = idsByType['userName']

2: Condition: true
Action: filterAttribute
Action parameters:
  unityAttribute = email

The above profile in the first action creates a new attribute userid with a value of user’s identity of the userName type. The attribute is added only if the principal has such identity. The second rule hides the email attribute unconditionally.

Additional examples of expressions and conditions can be found in the Input translation above. Note however that only the variables from the output MVEL context can be used.

10. 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 specialized 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. Configuration of this process is described in Input translation.

10.1. LDAP

Credential verificator name

ldap and ldap-cert

Compatible credentials

password and X.509 certificate

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.authenticatorName=ldapWeb
unityServer.core.authenticators.x.authenticatorType=ldap with web-password
unityServer.core.authenticators.x.verificatorConfigurationFile=conf/authenticators/ldap.properties
unityServer.core.authenticators.x.retrievalConfigurationFile=conf/authenticators/passwordRetrieval-ldap.json

LDAP communication can be set up in several different ways:

  1. All operations are performed as the user who is authenticating itself. It is a default mode, the userDNTemplate property needs to be defined to make it working.

  2. In many cases the ordinary users are not authorized to perform all required LDAP searches. In such case the system user identity must be set up using ldap.systemDN and ldap.systemPassword properties. Additionally Unity must be instructed to use it by setting ldap.bindAs=system. In this mode the only operation performed with the user is the bind operation used to check user’s password.

  3. In some cases it may happen that username (as entered in the login process) is not a part of DN in the LDAP tree. In such case the DN must be found first. To use this mode one has to set ldap.userDNSearchKey=SOME_KEY property and define an extra search specification under the key SOME_KEY. To make it working also the system user credentials must be set up as the initial search must be run as the system user always, regardless of the further operations governed by the ldap.bindAs setting.

  4. If LDAP attributes should not be anyhow imported/processed or can not be read due to authorization constraints then the ldap.authenticateOnly=true option can be set.

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

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.

In some cases the above approach which retrieves group membership and user’s attributes from LDAP is not enough. It may happen that additional attributes, which should be assigned to the user inside Unity, are placed in other branches of the LDAP tree. To solve this problem it is possible to configure arbitrary number of additional custom LDAP attribute searches. Results of those searches will be added to the regular user’s attributes. Let’s consider an example where user is member of several groups, each group has its gidNumber attribute set and we want to have a gidNumber attribute assigned to user in Unity. The following snippet should be added to configuration:

ldap.additionalSearch.1.baseName=dc=groups,dc=unity-example,dc=com
ldap.additionalSearch.1.filter=(memberUid={USERNAME})
ldap.additionalSearch.1.selectedAttributes=gidNumber

In the above example it is assumed that all groups are found under the dc=groups,dc=unity-example,dc=com node and each group has its members listed with the memberUid attribute. Of course the filter expression may be arbitrary complex.

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

[user, system]

user

Fundamental setting controlling how Unity interacts with the LDAP server. By default Unity binds to the LDAP server as the user who is being authenticated by Unity. This may be changed to use a predefined user (system or unity user) and password. Then the credentials provided by the user are only compared if are genuine, but all searches (and LDAP authorization) is run as the designated system user. In this mode, the system user’s DN, password and user’s password attribute must be configured.

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

string

-

Relevant and mandatory only if bindAs is set to system. The value must be the DN of the system user to authenticate as before performing any queries.

ldap.systemPassword

string

-

Relevant and mandatory only if bindAs is set to system. The value must be the password of the system user to authenticate as before performing any queries.

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

-

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

ldap.userDNSearchKey

string

-

A key of one of the advanced search definitions. The search must be defined and must return a single entry. The DN of this entry will be treated as a DN of the user being authenticated. This is useful when the username is not present in the user’s DN or when users can have different DN templates. Using this mode is slower then userDNTemplate. Mutually exclusive with userDNTemplate and at least one of them must be defined. To use this mode the systemDN and systemPassword must be also set to run the initial search.

ldap.userDNTemplate

string

-

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}. The username provided by the client will be substituted. Mutually exclusive with userDNTemplate and at least one of them must be defined.

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.

--- Advanced attribute search settings ---

ldap.additionalSearch.*

Structured list

-

Advanced attribute searches can be defined with this prefix.

ldap.additionalSearch.*.baseName

string

mandatory to be set

Base DN for the search. The value can include a specialstring: {USERNAME}. The username provided by the client will be substituted.

ldap.additionalSearch.*.filter

string

mandatory to be set

Filter in LDAP syntax, to match requested entries. The filter can include a specialstring: {USERNAME}. The username provided by the client will be substituted.

ldap.additionalSearch.*.scope

[one, sub, base, subordinate]

sub

LDAP search scope to be used for this search.

ldap.additionalSearch.* .selectedAttributes

string

-

Space separated list of attributes to be searched. Attributes from the query will have all values unified from all returned entries by the query.Duplicate values will be removed and finally attributes will be added to the set of the standard attributes of the principal.

10.2. LDAP with certificate-based authentication

Credential verificator name

ldap-cert

Compatible credentials

X.509 certificate

The ldap-cert verification mechanism shares the same features as the ldap mechanism described above. The only difference is that ldap-cert can be used with certificates which were checked on the transport layer (TLS). Naturally the password is not checked in this case (as user does not provide any password), and only the certificate’s subject is searched in LDAP and the attributes are assembled.

To use this verificator all the settings of the classic ldap verificator can be used, however the following rules must be kept in mind:

  1. The {USERNAME} variable (used in configuration) is substituted with a full subject name (DN) of the user’s certificate.

  2. The LDAP configuration must use the ldap.bindAs=system setting with all the consequences (binding as user is not possible without the password).

  3. In the ldap.authenticateOnly=true mode it is only checked if the user is present in the LDAP database.

  4. The returned identity (as used in an input translation profile) is the LDAP distinguished name of the principal not the DN of the certificate. The DN of the certificate is available as an attribute in the translation context.

10.3. External SAML IdP

Credential verificator name

saml2

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 the two most popular SAML2 bindings are supported: HTTP Post, HTTP Redirect and PAOS. PAOS (used for SAML ECP authentication of non-web browser clients) is configured as an endpoint: SAML PAOS Enhanced Client or Proxy (ECP) endpoint.

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.

You can alternatively configure the trusted IdPs with your federation’s metadata. Consult the reference table below for the list of the settings or the SAML Howto for examples.

Let’s consider an example with two remote IdPs:

unity.saml.requester.requesterEntityId=https://unity.example.com/unitygw/saml-sp-metadata/metadata-main
unity.saml.requester.metadataPath=metadata-main
unity.saml.requester.requesterCredential=MAIN
unity.saml.requester.acceptedNameFormats.1=urn:oasis:names:tc:SAML:2.0:nameid-format:persistent
unity.saml.requester.acceptedNameFormats.2=urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress
unity.saml.requester.acceptedNameFormats.3=urn:oasis:names:tc:SAML:2.0:nameid-format:transient
unity.saml.requester.displayName=Remote SAML authentication

unity.saml.requester.remoteIdp.1.name=Simple SAMLPHP in Rohan
unity.saml.requester.remoteIdp.1.address=https://idp.example2.com:8080/simplesaml/saml2/idp/SSOService.php
unity.saml.requester.remoteIdp.1.binding=HTTP_REDIRECT
unity.saml.requester.remoteIdp.1.samlId=https://idp.example2.com:8080/simplesaml/saml2/idp/metadata.php
unity.saml.requester.remoteIdp.1.certificate=ROHAN_IDP
unity.saml.requester.remoteIdp.1.groupMembershipAttribute=urn:oid:1.3.6.1.4.1.5923.1.1.1.1
unity.saml.requester.remoteIdp.2.requestedNameFormat=urn:oasis:names:tc:SAML:2.0:nameid-format:transient
unity.saml.requester.remoteIdp.1.translationProfile=samlProfile

unity.saml.requester.remoteIdp.2.name=Shibboleth IdP in Gondor
unity.saml.requester.remoteIdp.2.address=https://idp.example2.com/idp/profile/SAML2/Redirect/SSO
unity.saml.requester.remoteIdp.2.binding=HTTP_POST
unity.saml.requester.remoteIdp.2.samlId=https://idp.example2.com/idp/shibboleth
unity.saml.requester.remoteIdp.2.certificate=GONDOR_IDP
unity.saml.requester.remoteIdp.2.translationProfile=samlProfile

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

string

-

Default setting of requested identity format. Used for those IdPs, for which the setting is not set explicitly.

unity.saml.requester .defaultSignRequest

[true, false]

false

Default setting of request signing. Used for those IdPs, for which the setting is not set explicitly.

unity.saml.requester.identityMapping .*

Structured list

-

Prefix used to store mappings of SAML identity types to Unity identity types. Those mappings are used to reverse the mapping process of remote identity mapping into Unity representation (as configured with an input translation profile). This is used solely to provide a single logout functionality, where remote peer may request to logout an identity previously authenticated. Unity needs to be able to find this person’s session to terminate it.

unity.saml.requester.identityMapping .*.localIdentity

string

mandatory to be set

Unity identity to which the SAML identity is mapped. If it is set to an empty value, then the mapping is disabled, what is useful for turning off the default mappings.

unity.saml.requester.identityMapping .*.samlIdentity

string

mandatory to be set

SAML identity to be mapped

unity.saml.requester .requesterCredential

string

-

Local credential, used to sign requests and to decrypt encrypted assertions. If neither signing nor decryption is used it can be skipped.

unity.saml.requester.requesterEntityId

string

mandatory to be set

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

unity.saml.requester.sloPath

string

-

Last element of the URL, under which the SAML Single Logout functionality should be published for this SAML authenticator. Any suffix can be used, however it must be unique for all SAML authenticators in the system. If undefined the SLO functionality won’t be enabled.

unity.saml.requester.sloRealm

string

-

Name of the authentication realm of the endpoints using this authenticator. This is needed to enable Single Logout functionality (if undefined the SLO functionality will be disabled). If this authenticator is used by endpoints placed in different realms and you still want to have SLO functionality you have to define one authenticator per realm.

--- Configuration read from trusted SAML metadata ---

unity.saml.requester.metadataSource .*

Structured list

-

Under this prefix you can configure the remote trusted SAML IdPs however not providing all their details but only their metadata.

unity.saml.requester.metadataSource .*.httpsTruststore

string

-

If set then the given truststore will be used for HTTPS connection validation during metadata fetching. Otherwise the default Java trustststore will be used.

unity.saml.requester.metadataSource .*.perMetadataRegistrationForm

string

-

Deafult registration form for all the IdPs from the metadata. Can be overwritten by individual IdP configuraiton entries.

unity.saml.requester.metadataSource .*.perMetadataTranslationProfile

string

-

Deafult translation profile for all the IdPs from the metadata. Can be overwritten by individual IdP configuration entries.

unity.saml.requester.metadataSource .*.signaturVerification

[require, ignore]

ignore

Controls whether metadata signatures should be checked. If checking is turned on then the validation certificate must be set.

unity.saml.requester.metadataSource .* .signatureVerificationCertificate

string

-

Name of certificate to check metadata signature. Used only if signatures checking is turned on.

unity.saml.requester.metadataSource .*.url

string

mandatory to be set

URL with the metadata location. Can be local or HTTP(s) URL. In case of HTTPS the server’s certificate will be checked against the main Unity server’s truststore only if httpsTruststore is set.

unity.saml.requester.refreshInterval

integer number

3600

How often the metadata should be reloaded.

--- Manual settings of trusted IdPs ---

unity.saml.requester.remoteIdp.*

Structured list

-

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.* .address

string

-

Address of the IdP endpoint.

unity.saml.requester.remoteIdp.* .binding

[HTTP_REDIRECT, HTTP_POST, SOAP]

HTTP_REDIRECT

SAML binding to be used to send a request to the IdP. If you use SOAP here then the IdP will be available only for ECP logins, not via the web browser login.

unity.saml.requester.remoteIdp.* .certificate

string

-

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.* .certificates.*

list of properties with a common prefix

-

Using this property additional trusted certificates of an IdP can be added (when IdP uses more then one). See certificate for details. Those properties can be used together or alternatively.

unity.saml.requester.remoteIdp.* .enableAccountAssociation

[true, false]

true

If true then unknown remote user gets an option to associate the remote identity with an another local (already existing) account.

unity.saml.requester.remoteIdp.* .groupMembershipAttribute

string

-

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

unity.saml.requester.remoteIdp.* .logoURI[.*]

string can have subkeys

-

Displayed logo of the IdP. If not defined then only the name is used. The value can be a file:, http(s): or data: URI. The last option allows for embedding the logo in the configuration. The property can have subkeys being locale names; then the localized value is used if it is matching the selected locale of the UI.

unity.saml.requester.remoteIdp.* .name[.*]

string can have subkeys

-

Displayed name of the IdP. If not defined then the name is created from the IdP address (what is rather not user friendly). The property can have subkeys being locale names; then the localized value is used if it is matching the selected locale of the UI.

unity.saml.requester.remoteIdp.* .postLogoutEndpoint

string

-

Address of the IdP Single Logout Endpoint supporting HTTP POST binding.

unity.saml.requester.remoteIdp.* .postLogoutResponseEndpoint

string

-

Address of the IdP Single Logout response endpoint supporting HTTP POST binding. If undefined the base redirect endpoint address is used.

unity.saml.requester.remoteIdp.* .redirectLogoutEndpoint

string

-

Address of the IdP Single Logout Endpoint supporting HTTP Redirect binding.

unity.saml.requester.remoteIdp.* .redirectLogoutResponseEndpoint

string

-

Address of the IdP Single Logout response endpoint supporting HTTP Redirect binding. If undefined the base redirect endpoint address is used.

unity.saml.requester.remoteIdp.* .registrationFormForUnknown

string

-

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.* .requestedNameFormat

string

-

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.* .samlId

string

mandatory to be set

SAML entity identifier of the IdP.

unity.saml.requester.remoteIdp.* .signRequest

[true, false]

false

Controls whether the requests for this IdP should be signed.

unity.saml.requester.remoteIdp.* .soapLogoutEndpoint

string

-

Address of the IdP Single Logout Endpoint supporting SOAP binding.

unity.saml.requester.remoteIdp.* .translationProfile

string

-

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 web UI specific settings ---

unity.saml.requester .selectedProviderIconScale

[none, heightSmall, widthSmall, heightTiny, widthTiny, maxHeightTiny, maxHeightSmall, maxHeightMedium]

none

Controls whether and how the icon of a selected provider should be scalled. Note that this setting affects only the icon of a currently selected provider.

--- SAML metadata settings ---

unity.saml.requester.metadataPath

string

-

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.

unity.saml.requester.metadataSource

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.

unity.saml.requester.publishMetadata

[true, false]

true

Controls whether the SAML Metadata should be published.

unity.saml.requester.signMetadata

[true, false]

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.

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

10.4. Standard OAuth2 (Unity as OAuth Client)

Credential verificator name

oauth2

Compatible credentials

OAuth2 tokens

The typical authenticator’s configuration will look as follows:

unityServer.core.authenticators.x.authenticatorName=oauthWeb
unityServer.core.authenticators.x.authenticatorType=oauth2 with web-oauth2
unityServer.core.authenticators.x.verificatorConfigurationFile=conf/authenticators/remoteOAuth.properties

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.type=google
unity.oauth2.client.providers.google.clientId=UNITY_APP_ID_FROM_GOOGLE
unity.oauth2.client.providers.google.clientSecret=UNITY_APP_SECRET_FROM_GOOGLE
unity.oauth2.client.providers.google.scopes=profile openid email
unity.oauth2.client.providers.google.translationProfile=googleProfile

unity.oauth2.client.providers.fb.type=facebook
unity.oauth2.client.providers.fb.clientId=UNITY_APP_ID_FROM_FACEBOOK
unity.oauth2.client.providers.fb.clientSecret=UNITY_APP_SECRET_FROM_FACEBOOK
unity.oauth2.client.providers.fb.translationProfile=facebookProfile

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:

https://YOUR-EXTERNAL-UNITY-ADDRESS/unitygw/oauth2ResponseConsumer

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

unity.oauth2.client.iconScale

string

-

Deprecated, please use authentication UI icon settings or the selectedProviderIconScale

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

Structured list can have subkeys

mandatory to be set

Prefix, under which the available oauth providers are defined.

unity.oauth2.client .selectedProviderIconScale

[none, heightSmall, widthSmall, heightTiny, widthTiny, maxHeightTiny, maxHeightSmall, maxHeightMedium]

none

Controls whether and how the icon of a provider should be scalled. Note that this setting controls only the size of the icon of the currently selected provider.

Property name Type Default value / mandatory Description

unity.oauth2.client.CLIENT_ID .accessTokenEndpoint

string

-

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]

standard

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

string

-

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]

secretBasic

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

unity.oauth2.client.CLIENT_ID.clientId

string

mandatory to be set

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

unity.oauth2.client.CLIENT_ID .clientSecret

string

mandatory to be set

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

unity.oauth2.client.CLIENT_ID .enableAccountAssociation

[true, false]

true

If true then unknown remote user gets an option to associate the remote identity with an another local (already existing) account.

unity.oauth2.client.CLIENT_ID .httpClientHostnameChecking

[NONE, WARN, FAIL]

FAIL

Controls how to react on the DNS name mismatch with the server’s certificate. Unless in testing environment should be left on the default setting.

unity.oauth2.client.CLIENT_ID .httpClientTruststore

string

-

Name of the truststore which should be used to validate TLS peer’s certificates. If undefined then the system Java tuststore is used.

unity.oauth2.client.CLIENT_ID .iconUrl[.*]

string can have subkeys

-

URL to provider’s logo. Can be http(s), file or data scheme. Can be localized.

unity.oauth2.client.CLIENT_ID .name[.*]

string can have subkeys

mandatory to be set

Name of the OAuth provider to be displayed. Can be localized with locale subkeys.

unity.oauth2.client.CLIENT_ID .openIdConnect

[true, false]

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

string

-

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

unity.oauth2.client.CLIENT_ID .profileEndpoint

string

-

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

string

-

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

unity.oauth2.client.CLIENT_ID.scopes

string

-

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

string

mandatory to be set

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

unity.oauth2.client.CLIENT_ID.type

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

custom

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.

10.5. Simple OAuth2 (Unity as OAuth Resource Provider)

Credential verificator name

oauth-rp

Compatible credentials

OAuth2 access token

The standard OAuth authentication is the best choice whenever it is possible to use it. Unfortunately there are cases when it is not suitable, e.g. if the authentication of a non web browser based user/client shall be performed.

Unity can authenticate its clients by consuming an OAuth2 access token, more precisely the bearer access token as defined by the http://tools.ietf.org/html/rfc6750. The access token can be issued by a remote OAuth Authorization Server or by the local Unity instance.

As a remote access token validation is not defined in OAuth protocol and there is no well established standard currently, the verification method depends on the OAuth AS implementation. If you want to use another OAuth AS which is unsupported let us know.

The validation work as follows:

  1. The access token is validated using a remote service. Usually this means: one HTTP GET to a token validation endpoint of a remote AS.

  2. If the token is valid then another query to a profile endpoint at the OAuth AS is performed, to obtain information about the user initiated token generation.

Of course Unity supports caching the verification results.

The current implementation authenticates the client in somewhat simplistic way: as the user who issued the access token. This approach called impersonation is not the best one as we loose the ability to distinguish the identity of the actual Unity client who is providing the access token. Therefore the current implementation of the OAuth RP authenticator will be modified in future to fully support a delegation approach, instead of impersonation.

The typical authenticator’s configuration looks as follows:

unityServer.core.authenticators.x.authenticatorName=oauthRP-Rest
unityServer.core.authenticators.x.authenticatorType=oauth-rp with rest-oauth-bearer
unityServer.core.authenticators.x.verificatorConfigurationFile=conf/authenticators/remoteOAuth-RP.properties

An example configuration of the OAuth2 RP verificator in file conf/authenticators/remoteOAuth-RP.properties follows:

unity.oauth2-rp.verificationProtocol=mitre
unity.oauth2-rp.profileEndpoint=https://mitreid.org/userinfo
unity.oauth2-rp.verificationEndpoint=https://mitreid.org/introspect
unity.oauth2-rp.cacheTime=20
unity.oauth2-rp.clientId=unity
unity.oauth2-rp.clientSecret=unity-pass
unity.oauth2-rp.translationProfile=tr-oauth

In this example the demo MITRE service is configured. The first three lines are the most important: the verification protocol is chosen and the validation and user profile endpoints are defined. The clientId and clientSecret are obtained at registration time (note that in this case there is bit of ambiguity in naming: the client mentioned her in OAuth terminology is not is OAuth Resource Provider not the OAuth client). Finally a translation profile is set to process the user’s information and to map it to a local representation.

The following table lists all currently implemented validation protocols:

Validation protocol Description

internal

Validates a token using the internal Unity’s database of tokens issued by its own OAuth AS endpoint. This method doesn’t require any endpoints to be defined.

unity

Validates a token using an external Unity OAuth AS endpoint.

mitre

Validates a token using an external MITRE OAuth Authorization Server.

A full reference of configuration parameters:

Property name Type Default value / mandatory Description

unity.oauth2-rp.cacheTime

integer >= 0

-

Per-token validation result cache time in seconds. If unset then the cache time will be equal to the discovered token lifetime or to 60s if it is impossible to establish the lifetime. Set to zero to disable caching.

unity.oauth2-rp .clientAuthenticationMode

[secretPost, secretBasic]

secretBasic

Defines how the client access token should be passed to the AS.

unity.oauth2-rp.clientId

string

-

Client identifier, used to authenticate when performing validation. If not defined then only the access token is used to authorize the call.

unity.oauth2-rp.clientSecret

string

mandatory to be set

Client secret, used to authenticate when performing validation. If not defined then only the access token is used to authorize the call.

unity.oauth2-rp .httpClientHostnameChecking

[NONE, WARN, FAIL]

FAIL

Controls how to react on the DNS name mismatch with the server’s certificate. Unless in testing environment should be left on the default setting.

unity.oauth2-rp.httpClientTruststore

string

-

Name of the truststore which should be used to validate TLS peer’s certificates. If undefined then the system Java tuststore is used.

unity.oauth2-rp.opeinidConnectMode

[true, false]

false

If true then the profile is fetched from the profile endpoint with assumption that the server is working in the OpenID Connect compatible way.

unity.oauth2-rp.profileEndpoint

string

-

Location (URL) of OAuth2 provider’s user’s profile endpoint. It is used to obtain token issuer’s attributes.

unity.oauth2-rp.requiredScopes.*

list of properties with a common prefix

-

Optional list of scopes which must be associated with the validated access token to make the authentication successful

unity.oauth2-rp.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.

unity.oauth2-rp.verificationEndpoint

string

-

OAuth token verification endpoint address.

unity.oauth2-rp.verificationProtocol

[mitre, unity, internal]

unity

OAuth token verification is not standardised. Unity supports several protocols, you can set the proper one here.

11. 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=oauthWeb;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 two authenticators (MFA - multi-factor authentication). In such case the two 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 oauthWeb 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:

11.1. Configuration of web authentication screen

Web endpoints (besides settings relevant for the particular type of the endpoint, what is covered below) share a number of common settings. Those settings control:

  • what (if any) registration possibilities are enabled for the endpoint

  • custom theme and web resources location for the endpoint (see Web interface branding for details)

  • how to arrange authentication options on the authentication screen

The last point constitutes the majority of the configuration options. In principle the authentication options (provided by authenticators configured for the endpoint) can be arranged in one or more authentication tiles. Authentication tile is a visual grouping of authentication options. Each tile can be configured differently. The following screenshot shows an authentication screen with two tiles:

Authentication tiles

The first tile is using the default simple mode where icons (or names if icons are not defined) of authentication options are arranged in configurable number of columns. The second tile is using the table mode. The table mode provides a more compact (and less flexible) presentation of authentication options but is perfect in cases when the number of options is high. On the screenshot part of the EduGain federation is presented with ca 1000 IdPs.

More advanced customization of the authentication screen look can be performed with custom theming, see Web interface branding.

Configuration of the above example follows:

unity.endpoint.web.authnsPerLine=2
unity.endpoint.web.authnIconScale=maxHeightSmall
unity.endpoint.web.authenticationTiles.1.tileContents=pwd cert ldap
unity.endpoint.web.authenticationTiles.1.tileMode=simple
unity.endpoint.web.authenticationTiles.1.tileName.pl=Lokalne metody
unity.endpoint.web.authenticationTiles.1.tileName.en=Local authentication
unity.endpoint.web.authenticationTiles.1.tileIconSize=maxHeight50

unity.endpoint.web.authenticationTiles.2.tileContents=saml oauth
unity.endpoint.web.authenticationTiles.2.tileMode=table
unity.endpoint.web.authenticationTiles.2.tileName.pl=Zdalne logowanie
unity.endpoint.web.authenticationTiles.2.tileName.en=Remote methods

Options reference for all Web (Vaadin) endpoints are as follows:

Property name Type Default value / mandatory Description

unity.endpoint.web.authenticationTiles .<NUMBER>

Structured list

-

Under this prefix authentication tiles can be defined. Authentication tile is a purely visual grouping of authentication options. If this list is undefined all authentication options will be put in a single default tile.

unity.endpoint.web.authenticationTiles .<NUMBER>.tileAuthnsPerLine

integer [1 — 10]

-

Defines how many authenticators should be presented in a single line of a tile in the simple mode. Overrides the default setting.

unity.endpoint.web.authenticationTiles .<NUMBER>.tileContents

string

mandatory to be set

Specification of the authentication tile contents. Value is a list of name prefixes separated by spaces. Authentication option whose (primary) authenticator name starts with one of the prefixes will be assigned to this tile. The unassigned authentication options will be assigned to additional tile.

unity.endpoint.web.authenticationTiles .<NUMBER>.tileIconScale

[none, heightSmall, widthSmall, heightTiny, widthTiny, maxHeightTiny, maxHeightSmall, maxHeightMedium]

-

Defines how to scale authenticator icons in a tile in the simple mode. Overrides the default setting.

unity.endpoint.web.authenticationTiles .<NUMBER>.tileMode

[table, simple]

simple

Defines how the tile should present authentication options assigned to it. In the simple mode all logos (or names if logo is undefined) of authentication options are displayed,and it is configurable how many per row and how to scale them. The table mode presents authentication options in rows one by one with logo in the first column. The table is much better choice when many authenticators are present as those are lazy loaded. In case when there is more then ca 30 authentication options the simple mode should not be used.

unity.endpoint.web.authenticationTiles .<NUMBER>.tileName[.*]

string can have subkeys

-

Defines the displayed name of the tile. Can have language specific versions. If undefined then tile has no name.

unity.endpoint.web.authnIconScale

[none, heightSmall, widthSmall, heightTiny, widthTiny, maxHeightTiny, maxHeightSmall, maxHeightMedium]

maxHeightTiny

Defines how to scale authenticator icons in the simple mode. Can be overriden per tile.

unity.endpoint.web.authnTheme

string

-

Overrides the default theme name as used for rendering the endpoint’s authentication screen contents. If undefined the same setting as for the main endpoint UI is used.

unity.endpoint.web.authnsPerLine

integer [1 — 10]

3

Defines how many authenticators should be presented in a single line of an authentication tile in simple mode.

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

string

-

Overrides the default theme name as used for rendering the endpoint contents.

unity.endpoint.web.webContentDirectory

filesystem path

-

Defines a folder from which the endpoint will serve static content, configured locally. If undefined the default value from the server’s main configration is used.

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

Currently the Admin UI endpoint offers the same options as the Home endpoint naturally including the options common for all web endpoints. The Home endpoint’s options can usually be left unchanged as are used only to control the logged user’s profile screen, which is also available for administrator’s convenience in the Admin UI.

11.3. 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 couple of options, which can be used to fine tune the information presented in its interface. All options common to all web endpoints are naturally also supported. The remaining options are provided below:

Property name Type Default value / mandatory Description

unity.userhome.attributes.<NUMBER>

Structured list

-

Prefix under which it is possible to define attributes which should be either presented or made editable on the User Home UI.

unity.userhome.attributes.<NUMBER> .attribute

string

mandatory to be set

Attribute name.

unity.userhome.attributes.<NUMBER> .editable

[true, false]

true

If enabled and the attribute is marked as self modificable, it will be possible to edit it. Otherwise it is shown in read only mode.

unity.userhome.attributes.<NUMBER> .group

string

mandatory to be set

Group of the attribute.

unity.userhome.attributes.<NUMBER> .showGroup

[true, false]

false

If true then the group is shown next to the attribute.

unity.userhome.disabledComponents .*

list of properties with a common prefix

-

List of tags of UI components which should be disabled. Valid tags: [credentialTab, preferencesTab, userDetailsTab, accountRemoval, attributesManagement, userInfo, identitiesManagement, accountLinking]

For instance the following configuration snippet will enable display of the email attribute of the root group in the profile page. What’s more the user will be allowed to edit the email attribute if only the attribute type is marked as self modifiable.

unity.userhome.attributes.2.attribute=email
unity.userhome.attributes.2.group=/
unity.userhome.attributes.2.showGroup=false
unity.userhome.attributes.2.editable=true

11.4. Web SAML SSO endpoint

Endpoint type

SAMLWebIdP

Binding

Web (Vaadin)

Exposed paths

/saml2idp-web, /metadata, /SLO-WEB, /SLO-SOAP

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 endpoint can be configured to support arbitrary SAML identity type names. By default the following identity type mappings are used:

SAML name UNITY identity type

urn:oasis:names:tc:SAML:2.0:nameid-format:persistent

targetedPersistent

urn:oasis:names:tc:SAML:1.1:nameid-format:X509SubjectName

x500Name

urn:oasis:names:tc:SAML:2.0:nameid-format:transient

transient

urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified

targetedPersistent

unity:persistent

persistent

unity:identifier

identifier

unity:userName

userName

It is possible to reconfigure the mappings in the configuration or to add a new one. For example the following snippet will map the SAML identity type userId to the Unity userName identity type:

unity.saml.identityMapping.1.localIdentity=userName
unity.saml.identityMapping.1.samlIdntity=userId

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

Property name Type Default value / mandatory Description

--- Configuration read from trusted SAML metadata ---

unity.saml.acceptedSPMetadataSource .*

Structured list

-

Under this prefix you can configure the remote trusted SAML Sps however not providing all their details but only their metadata.

unity.saml.acceptedSPMetadataSource .*.httpsTruststore

string

-

If set then the given truststore will be used for HTTPS connection validation during metadata fetching. Otherwise the default Java trustststore will be used.

unity.saml.acceptedSPMetadataSource .*.signaturVerification

[require, ignore]

ignore

Controls whether metadata signatures should be checked. If checking is turned on then the validation certificate must be set.

unity.saml.acceptedSPMetadataSource .* .signatureVerificationCertificate

string

-

Name of certificate to check metadata signature. Used only if signatures checking is turned on.

unity.saml.acceptedSPMetadataSource .*.url

string

mandatory to be set

URL with the metadata location. Can be local or HTTP(s) URL. In case of HTTPS the server’s certificate will be checked against the main Unity server’s truststore only if httpsTruststore is set.

unity.saml.refreshInterval

integer number

3600

How often the metadata should be reloaded.

--- Manual settings of allowed Sps ---

unity.saml.acceptedSP.* .certificates.*

list of properties with a common prefix

-

Using this property additional trusted certificates of an SP can be added (when SP uses more then one). See certificate for details. Those properties can be used together or alternatively.

unity.saml.acceptedSP.* .logoURI[.*]

string can have subkeys

-

Displayed logo of the SP. If not defined then only the name is used. The value can be a file:, http(s): or data: URI. The last option allows for embedding the logo in the configuration. The property can have subkeys being locale names; then the localized value is used if it is matching the selected locale of the UI.

unity.saml.acceptedSP.* .name[.*]

string can have subkeys

-

Displayed name of the Sp. If not defined then the name is created from the Sp address (what is rather not user friendly). The property can have subkeys being locale names; then the localized value is used if it is matching the selected locale of the UI.

--- SAML subsystem settings ---

unity.saml.acceptedSP.*

Structured list

-

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

unity.saml.acceptedSP.* .certificate

string

-

Certificate of the SP. Used only when acceptance policy is strict and when assertion encryption is turned on for this SP.

unity.saml.acceptedSP.*.dn[.*]

string can have subkeys

-

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.

unity.saml.acceptedSP.* .encryptAssertion

[true, false]

false

Whether to encrypt assertions sent to this peer. Usually not needed as Unity uses TLS. If turned on, then certificate of the peer must be also set.

unity.saml.acceptedSP.*.entity

string

-

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

unity.saml.acceptedSP.* .postLogoutEndpoint

string

-

HTTP POST Single Logout Endpoint of the SP.

unity.saml.acceptedSP.* .postLogoutResponseEndpoint

string

-

HTTP POST Single Logout response endpoint of the SP. If undefined the base endpoint address is assumed.

unity.saml.acceptedSP.* .redirectLogoutEndpoint

string

-

HTTP Redirect Single Logout Endpoint of the SP.

unity.saml.acceptedSP.* .redirectLogoutResponseEndpoint

string

-

HTTP Redirect Single Logout response endpoint of the SP. If undefined the base endpoint address is assumed.

unity.saml.acceptedSP.*.returnURL

string

-

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

unity.saml.acceptedSP.* .soapLogoutEndpoint

string

-

SOAP Single Logout Endpoint of the SP.

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

string

mandatory to be set

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

unity.saml.defaultGroup

string

mandatory to be set

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

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.identityMapping.*

Structured list

-

Prefix used to store mappings of SAML identity types to Unity identity types. Those mappings can override and/or complement the default mapping.

unity.saml.identityMapping.* .localIdentity

string

mandatory to be set

Unity identity to which the SAML identity is mapped. If it is set to an empty value, then the mapping is disabled, what is useful for turning off the default mappings.

unity.saml.identityMapping.* .samlIdentity

string

mandatory to be set

SAML identity to be mapped

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.

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

[true, false]

true

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.

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

[true, false]

false

Controls whether the user being authenticated should see the consent screen with the information what service requested authentication and what data is going to be released. Note that user may always choose to disable the consent screen for each service, even if this setting is set to false.

unity.saml.spAcceptPolicy

[all, validSigner, validRequester, strict]

validRequester

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. Important: this setting fully works for web endpoints only, for SOAP endpoints only validRequester and all acceptance policies can be used. All other will be treated as all. This is because you can control the access with authentication and authorization of the client, additional SAML level configuraiton is not neccessary.

unity.saml.translationProfile

string

-

Name of an output translation profile which can be used to dynamically modify the data being returned on this endpoint. When not defined the default profile is used: attributes are not filtered, memberOf attribute is added with group membership

unity.saml.truststore

string

-

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

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.

--- SAML metadata settings ---

unity.saml.metadataSource

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.

unity.saml.publishMetadata

[true, false]

true

Controls whether the SAML Metadata should be published.

unity.saml.signMetadata

[true, false]

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.

11.5. Web Service SAML SOAP endpoint

Endpoint type

SAMLSoapIdP

Binding

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.

11.6. UNICORE Web SAML SSO endpoint

Endpoint type

SAMLUnicoreWebIdP

Binding

Web (Vaadin)

Exposed paths

/saml2unicoreIdp-web, metadata, /SLO-WEB, /SLO-SOAP

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.

11.7. UNICORE Web Service SAML SOAP endpoint

Endpoint type

SAMLUnicoreSoapIdP

Binding

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.

11.8. SAML PAOS Enhanced Client or Proxy (ECP) endpoint

Endpoint type

SAML-ECP

Binding

none (this endpoint doesn’t use authenticators thus there is no binding in Unity sense. Formally it is HTTP/PAOS.)

Exposed paths

/saml2-ecp

SAML ECP endpoint is a helper endpoint for non web browser clients, which want to authenticate for using Unity interfaces (e.g. to perform SAML attribute queries), however the authentication should be performed with a remote SAML IdP. In other words this endpoint is non-web browser client friendly counterpart of the Web SAML SSO endpoint. The details of the ECP are described in the SAML ECP profile: http://docs.oasis-open.org/security/saml/Post2.0/saml-ecp/v2.0/cs01/saml-ecp-v2.0-cs01.html.

As the only function of the endpoint is to actually authenticate the client, it is not using any of regular Unity authenticators (none is matching this endpoint).

After successful ECP authentication against this endpoint, the client receives a JWT credential which can be used to authenticate it against other Unity endpoints.

Configuration of the ECP endpoints is the same as the configuration of the remote SAML authenticator (see External SAML IdP) as ECP endpoint is in fact a relaying party (SP in SAML terminology) for remote IdPs. However there are the following things to note:

  1. The ECP endpoint must have additional settings configuring JWT generation. Those are the same as the settings for JWT management endpoint, however the prefix is unity.saml.requester.jwt..

  2. The ECP endpoint always uses the default settings for signing the request and of the requested SAML format. This is because the target IdP is not known during SAML query generation.

An example configuration:

unity.saml.requester.requesterEntityId=http://ecpSP.example.com
unity.saml.requester.metadataPath=metadata
unity.saml.requester.remoteIdp.1.address=http://localhost:52443/
unity.saml.requester.remoteIdp.1.samlId=http://example-saml-idp.org
unity.saml.requester.remoteIdp.1.certificate=MAIN
unity.saml.requester.remoteIdp.1.translationProfile=testP
unity.saml.requester.jwt.credential=MAIN
unity.saml.requester.jwt.tokenTtl=10

11.9. OAuth 2 Authorization Server and OpenId Connect endpoints

Endpoint 1 type

OAuth2Authz

Binding

Web (Vaadin)

Exposed paths

/oauth2-authz

Endpoint 2 type

OAuth2Token

Binding

RESTful (CXF)

Exposed paths

/token, /userinfo, /jwk, /tokeninfo, .well-known/openid-configuration

The OAuth 2 endpoints expose a functionality of a generic Authorization Server with a support for the OpenID Connect specification. The code, implicit and hybrid flows are supported.

The functionality is provided by two Unity endpoints, which shouldn’t be mixed with endpoints in OAuth sense which are equivalent to particular paths exposed by Unity endpoints. The first Unity endpoint, OAuth2Authz, exposes the OAuth authorization endpoint functionality. It is a web endpoint. It is used by end-users and the authentication of this endpoint should be configured so that OAuth users can authenticate themselves.

The second Unity endpoint, OAuth2Token, supports all remaining OAuth endpoints, including the most important token endpoint. The authentication settings of this endpoint should allow for authenticating OAuth clients accessing the /token path as required by OAuth specification. Note however that some of the operations needs to be authorized/authenticated by providing an OAuth access token only and this fact is handled internally - nothing has to be configured. Also two of the paths require neither authentication nor access token: /jwk and .well-known/openid-configuration. This is also handled automatically.

11.9.1. Configuration

Both OAuth endpoints create a pair, both must use the same configuration file. Configuration example:

unity.oauth2.as.issuerUri=https://example.com:2443/oauth2-token
unity.oauth2.as.signingCredential=MAIN

unity.oauth2.as.clientsGroup=/oauth-clients
unity.oauth2.as.usersGroup=/oauth-users
unity.oauth2.as.translationProfile=oauthOutputProfile

unity.oauth2.as.scopes.1.name=scope1
unity.oauth2.as.scopes.1.description=Provides access to base info
unity.oauth2.as.scopes.1.attributes.1=cn
unity.oauth2.as.scopes.1.attributes.2=o
unity.oauth2.as.scopes.1.attributes.3=email

The issuer should be equal to the base URL of the OAuth token endpoint in order to be compatible with OpenID Connect Discovery specification.

OAuth clients are configured as regular Unity entities. To make an ordinary entity an OAuth client one must place it in the configured OAuth clients groups (/oauth-clients in the above example). Additionally the client:

  • must have a credential so it can authenticate at the token endpoint in the way it was configured,

  • must possess the sys:oauth:allowedGrantFlows attribute (in OAuth clients group) with allowed flows,

  • must possess the sys:oauth:allowedReturnURI attribute (in OAuth clients group) with allowed return URI,

  • can have logo and/or displayed name OAuth attributes assigned to improve client’s presentation during user’s consent.

OAuth users must belong to a group specified in the configuration file. If no restrictions are required the / group can be used. In case that there are different groups of users for different OAuth clients, those groups can be configured with client’s attribute sys:oauth:groupForClient.

OAuth scopes should be defined next. Each scope includes a list of Unity attributes (use the Unity name) that should be exposed when the client asks for the scope and the user gives her consent.

Finally an output translation profile can be configured. It is highly useful to map Unity’s internal attribute names to names used by OAauth consumers. Standard OAuth/OIDC attribute names can be found in the OIDC specification: http://openid.net/specs/openid-connect-core-1_0.html#StandardClaims

Note that currently Unity requires you to configure all profiles and assign attributes to them manually.

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

Property name Type Default value / mandatory Description

unity.oauth2.as.accessTokenValidity

integer >= 1

3600

Controls the maximum validity period of an Access token (in seconds).

unity.oauth2.as.clientsGroup

string

/oauth-clients

Group in which authorized OAuth Clients must be present. OAuth related attributes defined in this group are usedto configure the client.

unity.oauth2.as.codeTokenValidity

integer >= 1

600

Controls the maximum validity period of a code token returned to a client (in seconds).

unity.oauth2.as.idTokenValidity

integer >= 1

3600

Controls the maximum validity period of an OpenID Connect Id token (in seconds).

unity.oauth2.as.issuerUri

string

mandatory to be set

This property controls the server’s URI which is used in tokens to identify the Authorization Server. To be compliant with OAuth&OIDC specifications it should be the server’s URL of the OAuth endpoint.

unity.oauth2.as.scopes.*

Structured list

-

Under this prefix OAuth scopes can be defined. In general scope defines a set of attribtues returned when it is requested.

unity.oauth2.as.scopes.* .attributes.*

list of properties with a common prefix

-

List of Unity attributes that should be returned when the scope is requested. Note that those attribtues are merely an input to the configured output translation profile.

unity.oauth2.as.scopes.* .description

string

-

Human readable description of the scope meaning.

unity.oauth2.as.scopes.*.name

string

mandatory to be set

Name of the scope as used in OAuth protocol.

unity.oauth2.as.signingCredential

string

mandatory to be set

Name of a credential which is used to sign tokens. Used only for the OpenId Connect mode, but currently it is always required.

unity.oauth2.as.skipConsent

[true, false]

false

Controls whether the user being authenticated should see the consent screen with the information what service requested authorization and what data is going to be released. Note that user may always choose to disable the consent screen for each service, even if this setting is set to false.

unity.oauth2.as.translationProfile

string

-

Name of an output translation profile which can be used to dynamically modify the data being returned on this endpoint. When not defined the default profile is used which simply return all Unity attribtues.

unity.oauth2.as.usersGroup

string

/

Group for resolving attributes of OAuth users. Only members of this group can authorize with OAuth.

11.9.2. OpenID Connect

Unity supports OpenID Connect (OIDC) protocol nearly out of the box. The only requirement to enable OIDC is to define a scope with a special name openid. Typically the openid scope has no attributes assigned.

Clients requesting the openid scope trigger OpenID Connect compatibility mode. In this mode the OIDC id token is generated and returned in the implicit grant from the authorization endpoint or in the code grant from the token endpoint.

11.9.3. Usage

Unity as Authorization Server usage is mostly regulated with the OAuth or OIDC specifications. In short the client redirects the user’s browser to the authorization endpoint. There user should accept the client’s request and Unity redirects the user back to the client. Depending on the flow used, the client receives an OAuth access token immediately (the implicit or hybrid flows) or has to ask Unity’s token endpoint about it (the code flow). The access token is then used by the client to access resources owned by the user.

At this point the OAuth specification doesn’t specify how the access token presented to a resource server can be validated. This missing step of the specification results from a common use case when a Resource Server and Authorization Server are the same. With Unity this is not the case so the Resource Server needs to contact Unity to verify if the received access token is genuine and valid.

To validate an access token a client (any, not necessarily the OAuth client) has to send a GET request to /tokeninfo path at the OAuth token endpoint.


@Path("/tokeninfo")
@Authorization("Bearer access token")
@GET

Returns status of a given access token, which must be provided in the Authorization header according to the RFC 6750). If the token is invalid then the HTTP 401 error is returned (see RFC 6750, section 3.1). If the token is valid then the following JSON document is returned:

{
  "sub": "subject id",
  "client_id": "client id",
  "exp": "12345678",
  "scope": ["scope1", "scope2"]
}
This Unity endpoint can be also used to issue an access token which subsequently can be used as a simple credential (mostly suitable for RESTful clients) to access Unity. Such approach is similar to the use of the JWT authentication and JWT management endpoint. The differences are that the Unity’s JWT tokens can be obtained in a much easier way then an OAuth access token. On the other hand JWT tokens can be used only with Unity, other services will neither issue nor validate them.

11.10. JWT management endpoint

Endpoint type

JWTMan

Binding

RESTful (CXF)

Exposed paths

/*

This endpoint exposes a simple JWT (JSON Web Token) management endpoint. It is possible to obtain, refresh and invalidate JWT with simple API calls. The usage of this endpoint is documented on the Unity Wiki.

The options of the endpoint are:

Property name Type Default value / mandatory Description

unity.jwtauthn.credential

string

mandatory to be set

Name of the PKI credential that will be used to sign or verify tokens. Note that this must be an RSA credential.

unity.jwtauthn.tokenTtl

integer >= 1

3600

Token validity time in seconds. Relevant only for token generation

11.11. RESTful Administration API endpoint

Endpoint type

RESTAdmin

Binding

RESTful (CXF)

Exposed paths

/v1/*

This endpoint exposes a RESTful API to Unity features. The endpoint does not require any specialized configuration.

All paths must be naturally prefixed with the server’s base URL, endpoint deployment’s path (as configured) and API version (currently there is only one). Example query path can be similar to:

https://unity.example.com/rest-admin/v1/entity/1

11.11.1. API reference


@Path("/resolve/{identityType}/{identityValue}")
@GET

Resolves a provided identity of a given type. The returned information is the same as in case of the /entity operation.

Example output:

{
  "id" : 3,
  "state" : "valid",
  "identities" : [ {
    "typeId" : "userName",
    "value" : "tested",
    "target" : null,
    "realm" : null,
    "local" : true,
    "entityId" : 3,
    "comparableValue" : "tested"
  }, {
    "typeId" : "persistent",
    "value" : "129ffe63-63b9-4467-ae24-6bc889327b0d",
    "target" : null,
    "realm" : null,
    "local" : true,
    "entityId" : 3,
    "comparableValue" : "129ffe63-63b9-4467-ae24-6bc889327b0d"
  } ],
  "credentialInfo" : {
    "credentialRequirementId" : "cr-pass",
    "credentialsState" : {
      "credential1" : {
        "state" : "notSet",
        "extraInformation" : ""
      }
    }
  }
}

@Path("/entity/{entityId}")
@GET

Returns information about a given entity, including its status and all identities.

Example output:

{
  "id" : 3,
  "state" : "valid",
  "identities" : [ {
    "typeId" : "userName",
    "value" : "tested",
    "target" : null,
    "realm" : null,
    "local" : true,
    "entityId" : 3,
    "comparableValue" : "tested"
  }, {
    "typeId" : "persistent",
    "value" : "129ffe63-63b9-4467-ae24-6bc889327b0d",
    "target" : null,
    "realm" : null,
    "local" : true,
    "entityId" : 3,
    "comparableValue" : "129ffe63-63b9-4467-ae24-6bc889327b0d"
  } ],
  "credentialInfo" : {
    "credentialRequirementId" : "cr-pass",
    "credentialsState" : {
      "credential1" : {
        "state" : "notSet",
        "extraInformation" : ""
      }
    }
  }
}

@Path("/entity/{entityId}/groups")
@GET
Returns all groups the entity is member of.

Example output:

["/example/sub","/example","/"]

@Path("/entity/{entityId}/attributes")
@QueryParam("group")
@GET

Returns effective attributes of a given entity in a selected group. Values are encoded using simple mapping if possible (e.g. String attribute is placed as JSON string), values with syntax which is not directly mappable to JSON type is converted to binary representation and then Base64 encoded.

Example output:

[ {
  "values" : [ "/9j/4AAQSk .... KKKKACiiigD//2Q==" ],
  "direct" : true,
  "name" : "jpegA",
  "groupPath" : "/example",
  "visibility" : "full",
  "syntax" : "jpegImage"
}, {
  "values" : [ "value" ],
  "direct" : true,
  "name" : "stringA",
  "groupPath" : "/example",
  "visibility" : "full",
  "syntax" : "string"
} ]

@Path("/group/{groupPath}")
@GET

Returns all members and subgroups of a given group.

Example output:

{
  "subGroups" : [ ],
  "members" : [ 3 ]
}

@Path("/entity/identity/{type}/{value}")
@QueryParam("credentialRequirement")
@POST

Creates a new entity, with the given initial identity and credential requirement. The new entity is in valid state. New entity id is returned.

Example output:

{"entityId":3}

@Path("/entity/{entityId}/identity/{type}/{value}")
@POST

Creates a new identity for the given entity. No content is returned. Note that for e-mail identities the regular Unity conventions can be used to control confirmation state and tags - see Special encoding of emails.


@Path("/entity/{entityId}")
@DELETE

Removes the given entity. No content is returned.


@Path("/entity/{entityId}/removal-schedule")
@QueryParam("when") @PUT

Sets the entity in the state where it can only login and schedules its removal at given time unless the user logs in before this time. No content is returned. This operation is allowed to be called on self .


@Path("/entity/{entityId}/admin-schedule")
@QueryParam("when") @QueryParam("operation") @PUT

Schedules an operation to be invoked at a given time on an entity. Must be called by privileged user. Allowed operations are: REMOVE and DISABLE.


@Path("/entity/identity/{type}/{value}")
@DELETE

Removes the given identity. No content is returned.


@Path("/group/{groupPath}/entity/{entityId}")
@POST

Adds the given entity as a member to a group. Note that group must be URL encoded, the / character should be given as %2F. No content is returned.


@Path("/group/{groupPath}/entity/{entityId}")
@DELETE

Removes a given entity from a group. Note that group must be URL encoded, the / character should be given as %2F. No content is returned.


@Path("/entity/{entityId}/attribute")
@PUT
@Consumes(MediaType.APPLICATION_JSON)

Sets (creates or updates) an attribute for the given entity. The body of the PUT request describes the attribute: its name, values and group. Its syntax is the same as returned by the GET attributes operation, however the syntax and direct shall not be used. No content is returned. Example attribute encoded (email with two values):

{
  "values" : [ {
    "value" : "some@example.com",
    "confirmationData" : "{\"confirmed\":false,\"confirmationDate\":0,\"sentRequestAmount\":0}"
  }, {
    "value" : "some2@example.com",
    "confirmationData" : "{\"confirmed\":true,\"confirmationDate\":1429006209143,\"sentRequestAmount\":0}"
  } ],
  "name" : "emailA",
  "groupPath" : "/",
  "visibility" : "full"
}

@Path("/entity/{entityId}/attributes")
@PUT
@Consumes(MediaType.APPLICATION_JSON)

Bulk attributes creation or update for a given entity. The body of the PUT request describes the attributes. Its root level element must be JSON array. Elements of the array are attributes expressed in the same way as in the singular set attribute operation.


@Path("/entity/{entityId}/attribute/{attributeName}")
@QueryParam("group")
@DELETE

Removes the given attribute of an entity. No content is returned.


@Path("/entity/{entityId}/credential-adm/{credential}")
@PUT
@Consumes(MediaType.APPLICATION_JSON)

Sets a new credential secret for the given entity. The caller must have administrative privileges. Credential name is given as the path parameter, while the secret is carried in the JSON body. No content is returned. For the password credential the complete value could be (with a selected security question and its answer):

{"password":"newpass","answer":"Some answer","question":1}

@Path("/entity/{entityId}/credential/{credential}")
@PUT
@Consumes(MediaType.APPLICATION_JSON)

Sets a new credential secret for the given entity. The caller is assumed to change his/her own credential and must provide its current value (assuming the credential was already set). Credential name is given as the path parameter, while the new and current secrets are carried in the JSON body. No content is returned. The body must be a JSON array with one (only when the credential was not yet set) or (typically) two elements. IMPORTANT: the values of the array must be JSON strings, not JSON objects.

For the password credential the complete value could be (with a selected security question and its answer):

[
  "{\"password\":\"newpass\",\"answer\":\"Some answer2\",\"question\":0}",
  "{\"password\":\"currentpass\",\"answer\":\"Some answer\",\"question\":1}"
]

@Path("/attributeTypes")
@GET

Returns an array with all attribute types. Example:

[{
  "flags" : 0,
  "maxElements" : 1,
  "minElements" : 0,
  "selfModificable" : false,
  "uniqueValues" : false,
  "visibility" : "full",
  "syntaxState" : "{\"allowed\":[\"V2\",\"V1\"]}",
  "displayedName" : {
    "DefaultValue" : "enumA",
    "Map" : { }
  },
  "i18nDescription" : {
    "DefaultValue" : null,
    "Map" : { }
  },
  "metadata" : { },
  "name" : "enumA",
  "syntaxId" : "enumeration"
},
...
]

@Path("/attributeType")
@POST
@Consumes(MediaType.APPLICATION_JSON)

Creates a new attribute type. The POSTed request body must contain a JSON description of the attribute type, with the same syntax as returned by the GET query on attributeTypes. Only a single element is permitted, i.e. do not pass an JSON array. The flags field should be always set to 0.


@Path("/attributeType")
@PUT
@Consumes(MediaType.APPLICATION_JSON)

Updates an existing attribute type. The syntax rules are as for POST, however the name of the updated attribute type must resolve to an existing attribute type.


@Path("/attributeType/{toRemove}")
@QueryParam("withInstances")
@DELETE

Removes a given attribute type. Query parameter withInstances is used to control whether all attributes of the removed type should be removed too (value true) or whether the operation should fail if there are any attributes (value false).


@Path("/confirmation-trigger/identity/{type}/{value}")
@POST

Triggers sending of confirmation message of identity. Nearly always it is a re-send.


@Path("/confirmation-trigger/entity/{entityId}/attribute/{attributeName}")
@QueryParam("group")
@POST

Triggers sending of confirmation message for an attribute. Nearly always it is a re-send.

11.12. Access with well-known URLs

Endpoint type

WellKnownLinksHandler

Binding

Web (Vaadin)

Exposed paths

/sec

This endpoint is providing access to various Unity functions which are accessible via well known URLs and, at the same time, require authentication to be used. Analogous feature but for cases not requiring authentication is exposed always under the /unitygw reserved path.

Currently the endpoint offers a single feature but there are plans to extend it in future.

Available paths:

Path Description

/#!account-association

Provides direct access to account association feature, i.e. the same which is available from the HomeUI.

The following settings are allowed for the endpoint:

Property name Type Default value / mandatory Description

unity.endpoint.connectId.redirectUrl

string

-

If defined must must contain a valid URL to which the requester is redirected after completing the accountassociation process. Additional status information is providedwith query parameters.

Appendix A: Currently supported features

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

A.2. Local credentials

Feature Status Notes

Password

Certificate

Pseudo credential allowing for X.509 certificate login

One Time Passwords

Not yet available

A.3. Endpoints

Feature Status Notes

SAML 2, Web SSO profile

SAML 2, SOAP binding

SAML 2, PAOS binding (for ECP)

Web admin interface

REST admin interface

Base part, read-only, is available, will be extended in future

Web user profile management

Available however more functionality is required

SAML 2, Web binding + UNICORE profile

SAML 2, SOAP binding + UNICORE profile

OpenID Connect

OAuth 2

Tokens management UI not yet available

A.4. Upstream IdPs

Feature Status Notes

LDAP

SAML 2, Web SSO profile

OAuth 2

Tested with Facebook, Microsoft Live, MITRE

OpenID Connect

Tested with Google

OpenID 2

Not yet available

OAuth 1

Not yet available

A.5. Attribute syntaxes

Feature Status Notes

String

Verifiable e-mail

Enumeration

Integer number

Floating point number

JPEG image

A.6. Identity types

Feature Status Notes

User name

E-mail identifier

Must be confirmed to be usable

X.500 distinguished name (DN)

Persistent (anonymous)

Persistent,targeted (anonymous)

Transient,targeted (anonymous)

Opaque identifier