Unity Manual

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

Internally Unity is composed of two parts:

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

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

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

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

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

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

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

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

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

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

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

Starting is simple:

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

Stopping the server is simple as well:

It is possible to install Unity in a High Availability (HA) setup. The Unity HA can be realized in two variants:

When configuring the system some precautions must be made:

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 (via AdminUI) 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.

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:

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

Once again, to have a short list:

Navigate your browser to:

Of course if you changed the port use the one you set. Default login and password are provided in the unityServer.conf file. Note that you will be asked to change them immediately after logging in.

Also note that the path /admin can be reconfigured: this is the location of the Admin UI endpoint, and you can set this path for each Unity endpoint.

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

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

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.

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

It uses the (single) authenticator pwdWS:

So lets define a new one, called certWS:

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

Finally let’s use this authenticator:

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

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.

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:

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

Local authenticators use a locally stored credential to verify the client’s identity. Local authentication is simple in that 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.

Remote authentication is more complicated then the local one. 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:

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.

For certain sensitive operations Unity may be configured (and by default is) to require additional or step-up authentication. When this happens Unity asks an already logged user, to provide a single credential before operation is performed.

Operation may be classified as sensitive — and be subject to additional authentication — only when it is invoked by a user with ordinary permissions. Operations invoked by admins are always treated specially and additional authentication is alwyas skipped. There are two classes of sensitive operations:

Administrator can configure the additional authentication policy in the main server configuration file. Configuration is composed from three elements. The main one governs which authenticator is used for additional authentication. It must be always an authenticator which does not require web browser redirection (as remote OAuth) and it must be available on the endpoint. Typically policy is configured with constants which are resolved at runtime. The default policy is as follows:

According to the default policy, for each sensitive operation server will check in order:

The remaining option can be used to control for how long additional authentication is valid (i.e. after setting it to 600s then user won’t need to perform additional authentication for one minute) and whether to block operation if there is no applicable additional authentication authenticator for the user (what typically means that system is misconfigured).

Unity can use a configurable storage backend. Currently there are two options available, more may be added in future:

Selection of the database backend and its subsequent configuration is provided in the main unityServer.conf file. The following option allows to select the database backend:

Note that the Admin UI provides a possibility to create a dump JSON dump of the complete server state and to restore the system from such dump regardless of the selected storage engine.

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:

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 configured instance. The main configuration reference is presented below. The subsequent sections cover in more details the configuration of each of the three classes of artifacts.

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. The Consumer access: the endpoints section covers also how to configure authentication screen, i.e. the visual composition of authentication options which is defined per endpoint. Here we cover only the functional definitions of authenticators, which can be used with many endpoints in various configurations.

Authenticators are added either directly to endpoints or are tied together in authentication flows, what allows for flexible control of multi-factor authentication. The endpoint must have at least one authenticator or flow associated and can have more when alternative or multi-credential authentication scenarios are implemented.

Example configuration of an authenticator:

The name of the authenticator is an arbitrary, unique string. The type is the most important part: it defines the name of the authentication technology to be used. The following table lists supported technologies.

Authenticator typically require a configuration file. In that file details of how to collect and check the credential can be specified. Note that for local authenticators (i.e. checking the credential internally, without help of external service) must be associated with an existing local credential, and configuration of authenticator is typically minimal or even empty: verification process is defined by the local credential settings, and the only things that can be configured for authenticator are UI details like a label to be used on password retrieval text field.

More complex configuration of external authenticators is covered in the section Integration of 3rd party Identity Providers.

Configuration of credential retrievals follows. Note that this configuration is universal for all authenticators that use the credential in question, e.g. password retrieval settings below can be used both with password and ldap authentication technologies.

The password retrieval options:

The SMS retrieval options:

The X.509 certificate retrieval options:

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

Authentication flows are used to configure the authentication process as a whole, in the first place controlling the policy used to trigger multi factor authentication. Additionally flows can be used to define reusable groups of authenticators commonly used together.

An authentication flow consists of 3 sections: mandatory set of first factor authenticators, policy to trigger 2nd factor, and an optional list of 2nd factor authenticators.

Example configuration of an authentication flow:

In this example all users has to authenticate with password first. Then 2nd factor may kick in, but only if the user has opted to use 2nd factor (for others the 2nd factor will be skipped). User who preferrs to have their account secured, is either authenticated with SMS code sent to her phone or with X.509 certificate. Alwyas the first authenticator is used, for which a user has credential set.

Note that an endpoint may have more then one flow configured. Then the user can choose, and the selection of the first factor authentication option determines the flow to be used.

There are the following policies available:

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

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

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

The actual contents of the messages being sent is governed by the message templates. Message templates are configured using Admin UI (Server management→Message templates). It is also possible to configure them with configuration file (by default msgTemplates.properties), but this is much more difficult and not suggested. Currently a template is a named pair of two pieces of text: subject (title) and message body. What’s more the template can contain several variables which must be formated as:

Variables are replaced dynamically with concrete values when a message is prepared to be sent. Naturally each subsystem sending messages provides different variables. Therefore each template must be associated with a concrete subsystem. This is performed in the template edit screen. The list of available variables for each subsystem is also provided there.

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

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

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

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

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

Unity uses the Log4j logging framework in version 2.x (note that the older version 1.x is much different). Logging is configured in the conf/log4j2.xml file. Other log file formats supported by Log4j may be alternatively used but we suggest to use the default XML format.

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. The example contains inline explanations in comments.

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

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:

Regular Unity attributes are assigned in groups and an attribute assigned in a group is valid and visible only in the group where is was defined. Regular attributes are assigned either manually (in Admin UI or via REST interface) or by translation profile for users logging from remote IdP.

In many cases it is not enough: some attributes should be visible in multiple groups, some attributes should be added just for everybody, other attributes should be added to all users fulfilling some criteria. For all those cases Unity offers a feature called attribute statements.

Attribute statements are created per group. Each group can contain multiple statements, which are applied in order. Each statement can assign a single attribute to a group member. Each statement is evaluated per each group member what means it can provide a different values for different group members. The assigned attribute is always fixed, however the actual values and to whom/when the attribute is assigned is decided at runtime.

Each attribute statement contains a condition, an MVEL expression, which must evaluate to a boolean value. Only if condition evaluates to true the attribute of the statement is applied.

Statement’s attribute can be assigned in two ways:

Each statement contains a conflict resolution rule. It defines what to do if two statements create the same attribute. Note that if a statement creates a dynamic attribute which is already defined as a regular one, the dynamic one is always skipped.

Condition and (in case of dynamic attribute) attribute value expressions are given with MVEL language. See https://en.wikibooks.org/wiki/Transwiki:MVEL_Language_Guide for a generic introduction. Below we present a number of examples of the common cases.

Finally a statement can have an extra attribute group defined. If such group is set, then the attributes from this extra group are available in the MVEL context of conditions and dynamic value expressions. Note that dynamic attributes in an extra group are available too, what offers a great power. Unity, however uses advanced algorithms to prevent dependency circles. It is also only possible to to use a subgroup or a parent group as an extra group.

Always check log files after changing attribute statements, to verify if there are no errors. It is also good to enable DEBUG logging on unity.server.AttributeStatementProcessor when behavior is not as expected.

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:

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:

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.

It is possible to invoke or schedule for recurring invocations conditional actions on entities database. This feature is activated in the Server management → Bulk processing.

Scheduled actions are executed with a cron-like schedule (see tooltip for help). Actions are configured in a simple way. the only complicated and key part is rule condition, which must evaluate to true to select entity for which action should be invoked.

Condition is given in MVEL language (see https://en.wikibooks.org/wiki/Transwiki:MVEL_Language_Guide for details). The context exposes the following variables:

Example condition selecting all disabled entities:

Another much more complex example: let’s select all users who logged in no later then 6 months ago (line breaks added for clarity):

Here we first import Java namespace with time operations. The actual condition first checks if the user has logged at all (i.e. has the sys:LastAuthentication attribute) and if so we parse the last authentication attribute as date and compare it to the current time minus 6 months.

In case of troubles you can contact mailing list. It is always good to check server logs - detailed information on bulk processing execution can be found there.

Unity can produce forms which are completed in a single stage (step) or in two stages. On the first stage it is possible to include external sign up options and (if needed) either a "local" sign-up button or just a complete local sign-up form. This latter scenario is useful when the form is small or when there are no remote sign-up options: then we have only the first stage.

The second stage shows a form which is contextual: it is used either to ask for additional data after remote sign-up (required information, which is not obtained from remote IdP) or all details in case on the first stage the "local sign-up" button was placed and used.

The form definition consists of multiple parts:

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. The modes are as follows:

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.

A submitted request is visible in AdminUI and can be accepted, denied or removed there. Depending on form’s configuration notifications are sent upon form arrival and processing.

When a request is accepted all the settings which were requested are applied: a new entity is created with specified identities, attributes and group memberships. Administrator can manually disable some of the attributes and group membership individually.

What is more, and is a big advantage of Unity, is a possibility to automate requests processing in a very flexible way. This automation is described in the subsequent section.

Unity offers invitations support. Invitations are bound to an existing registration form, which must be public and must not possess a fixed (shared) registration code. Typically such forms are marked as by invitation only what ensures that only the invited users can fill the form (but this is not a requirement).

Invitations can be created in the AdminUI (Registration management → Invitations). What is very useful in various integration scenarios, the invitations feature can be also fully controlled by the REST API of Unity, see RESTful Administration API endpoint for details.

Invitation fundamental element is the registration code, which is a unique, random identifier generated by Unity. This code can be handled manually to the invited person, and then used at the beginning of the registration form filling. Typically, however, invitation is sent by e-mail, with link including the code. To enable this feature, the invitation’s form must have the invitation template defined, and the invitation itself the user’s address specified.

The fundamental invitation feature is the most useful for registration requests automatic acceptance: form which is by invitation only can have auto acceptance rule included, as it is guaranteed that all requests were using a valid invitation. For the forms accepting also not invited users, it is possible to check if a (valid) invitation code was provided in form automation rule’s condition with the validCode variable.

Additional, powerful feature is request pre-filling from an invitation. If some information about an invited user is known when inviting (e.g. emial), this information can be associated with the invitation. Precisely speaking all attributes, identities and group parameters of a form can be pre-filled. For each element is is possible to define how the pre-filled value should be treated: whether the user should be able to change the pre-filled value, only see it or neither see nor change.

Finally invitation can contain custom parameters which can be used in invitation message template.

Each registration form can have a translation profile attached to it. The registration translation profile is built using the same approach as the input and output translation profiles: i.e. it consists of a list of rules, where each rule has a MVEL condition and an action taken when the condition is true.

Registration profile is executed primarily when the request is submitted. There are however some rules which are consulted also in other corner cases (see below). Upon submission the the profile can perform couple of actions:

MVEL expression context available in all conditions and value expressions contains the following elements. Note that many of the variables come in a variant prefixed with the r letter. Those variants contain only the elements which were collected automatically, i.e. usually were provided the the registration form by a remote IdP.

Groovy language is not described here, its documentation is provided at Groovy’s site http://groovy-lang.org/documentation.html

Example scripts available in the distribution are a very good starting point to learn how to create own solutions. We suggest to start from browsing and or modifying one of them.

Unity ships a simple test program which allows to perform a dry run of the script. The test tool is invoked with a tested script being its sole argument:

During invocation all invocations of API methods are logged to the console. Note however that the tool provides a mock environment to the script: all objects are the same as during regular run, but all methods invoked on mocked objects return null value. Therefore more complicated scripts relying on data returned by the API objects can require some minor modifications for testing. Also note that regular logging as performed by the script (using the log object) will be placed in the regular log file of the unity server, as it is configured in the logging configuration.

Unity injects a wide range of objects which are available to the script. One of the most important is context which holds details of the event. For instance for all methodInvocation events the method name, arguments and error message in case of failure are stored in this object.

The following table enumerates all available object:

Detailed documentation on the above API objects is available in Unity platform API docs

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

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:

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

Unity uses a Freemarker template engine to produce a web page. By default the whole visible contents of this page is generated by Vaadin framework and this contents can not be manipulated (besides styling described above and system configuration allowing for many customization).

However, the main interface can be wrapped with custom decorations. For instance it is possible to add a foot bar with logos of partners of the infrastructure using Unity.

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 and German translations are mostly complete with the exception of the Admin UI. 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 or to allow for admin-configured locales outside from those predefined in distribution.

Actual translations are fully controlled by Unity administrator. In the i18n/ subfolder of the configuration directory a copy of all system messages is stored. It is possible to change any of the messages which are stored there, also including translations. Files are grouped in several directories; the structure of those directories is hardcoded and can not be modified. In each directory there is one message.properties file with default values (the default is simply English) and arbitrary number of files message_LC.properties, where LC is a code of a locale of the translation.

It is important to note how language-wise resolving of messages follows. For each message key and locale, Unity searches for the message value in the following order:

Note that initially (until any custom reconfigurations are performed) the two last options are the same as the two first.

What is more Unity allows for providing all names, descriptions and other texts which are end-user oriented and 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.

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:

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:

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.

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:

Example output profile:

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.

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:

LDAP communication can be set up in several different ways:

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

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

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

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:

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:

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:

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.

Let’s consider an example with two remote IdPs:

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

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

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

The complete SAML authenticator configuration reference follows:

The typical authenticator’s configuration will look as follows:

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

In the above example two providers are configured: Facebook and Google. Facebook is configuraed with default settings which are most of the time sufficient: you have to select provider’s type ad provide OAuth client’s id and secret. In the 2nd example some of the default values are overriden for Google provider. See reference below for a complete list of fine-tuning options you can use.

You can select among several providers for which we have a predefined type, or use the custom type, where nearly arbitrary standards compliant OAuth identity provider can be configured.

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

Links to client management pages of some of the well known providers:

As with every remote authenticator a translation profile is used to map external data to local representation. Unity is shipped with default profiles for the supported providers, but you can use your own. Typically custom profile inherits rules from the base one and enriches or overwrites them with custom settings.

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.

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:

Of course Unity supports caching the verification results.

The typical authenticator’s configuration looks as follows:

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

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:

A full reference of configuration parameters:

PAM based authentication allows for authenticating Unity users against host Operating System PAM facility. PAM is supported on Linux OS, and may be available also on other UNIXes. The integration is tested on Linux.

To be able to use host operating OS facilities, native access is required, which is beyond capabilities of the portable Java platform on which Unity is build. That said Unity should be able to access most popular Linux platforms out of the box without any additional configuration. Still we test the feature only on the Linux x86-64 platform. In case of runtime problems with native access (which should be pretty obvious in log file) please ask at mailing list.

PAM authenticator exposes the following user attributes after successful authentication, which can be used by a translation profile:

The username is provided as always in case of Unity in the special profile’s variable id. Similarly supplementary group names are in the standard array variable groups

The typical authenticator’s configuration will look as follows:

PAM access is configured by providing a name of PAM facility that should be used by Unity and input translation profile which should map information about authenticated user to Unity representation.

Example configuration in file conf/authenticators/pam.properties:

For such configuration Unity will authenticate against PAM using configuration from /etc/pam.d/unity file. Please refer to PAM documentation for details on how to create such file. An example (which is mostly default local authentication on Linux) can be similar to:

The complete PAM options reference follows:

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 REST endpoints the common options are:

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

Currently there are no common options for Web Service endpoints.

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:

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 columns. By default all options are shown in a single column. This is fine with a single option, but when having more some fine tuning is often desired.

The following screenshot shows an authentication screen with a single column:

Configuration of the above example is as follows (note that it is also localized to Polish language):

When allowing access to a federation with many tens, or hundreds of authentication options, having all of them as individual entries would clutter the screen and make it loading very slowly. Therefore a special grid component is provided, which can be used to group many entries in a column. This is shown on the following example, using two columns.

Configuration of the example:

Number of columns to use is free to be changed, typically one or two are used. Contents of columns can be flexibly arranged. Typically entries are individual authentication options. However there is a plenty of other options, here is the complete list:

A very useful feature (by default turned on, controlled with unity.endpoint.web.authnShowLastOptionOnly) helps returning users by hiding all options but the one previously used. User still has an option to revel all available options.

Note that all separators and headers are automatically hidden if their corresponding authentication options are missing. Also empty columns are not shown.

More advanced customization of the authentication screen look can be performed with custom theme, see Web interface customization and branding. You will find that all elements on the authentication screen have their individual HTML classes, and so it is possible to customize branding to a very high degree.

In many cases authentication screen of an Unity endpoint holds more then one authentication option. The last used option is saved in user’s cookie. Additionally Unity supports a special query attribute uy_select_authn which can be used for any web endpoint to select one of available authentication option. A value of this parameter must be formed according to the following pattern: authenticatorId.authenticationOptionId.

For instance to preselect a remote OAuth provider under key google in configuration of an authenticator with id oauthWeb one would need to add a query parameter uy_select_authn=oauthWeb.google. If in doubt, it is always possible to check the available values by manually trying to authenticate with authentication option of choice and verify the cookie set by Unity with the last authentication option used — the value format is the same.

Unity allows also for acting as an invisible authentication proxy. This can be useful when (sets of) clients should use a fixed upstream IdP, while Unity should still handle all the authentications (for whatever reasons, as attributes unification or protocol bridging). Such mode of operation is only available with remote (i.e. non-interactive from Unity PoV) authentication methods: remote SAML and remote OAuth authentication.

The automated proxy authentication may be enabled in two ways. The first option is to add a special, additional query parameter uy_auto_login=true. Other possibility is to enable automatic authentication within endpoint’s configuration with unity.endpoint.web.autoLogin=true setting. In any of case the target endpoint either must be configured with a single authenticator, with a single authentication option (e.g. OAuth authenticator with a single trusted provider) or the mentioned above uy_select_authn query parameter must be additionally used to select the desired authentication option.

Unity offers couple of web endpoints which are used when remote service authenticates web user against Unity. The most significant examples are OAuth2 Authorization Server endpoint and SAML endpoint.

All IdP web endpoints have rather simple UI and share some of the common features. User can be presented with two screens.

On the first one (rather rarely used feature) user can select active value for an attribute or attributes. Typical use case is to allow user to select active role for the session. Configuration of the active value selection screen can be different per client (e.g. using the screen only for selected clients, or even presenting different attribute for value selection depending on a client). Of course the screen can be completely disabled what is the default behavior.

The 2nd screen in order (more often used) is a consent screen. User is presented with information who is requesting the authentication and what data will be shared with the requesting service. Details of the consent screen vary between IdP endpoints, e.g. OAuth endpoint shows requested scopes, while SAML endpoint doesn’t. Users can save the consent decision and then consent is skipped for them. It is also possible to turn off the consent screen completely.

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/ENDPOINT-CONFIGURED-CONTEXT/admin or simply https://localhost:2443/ENDPOINT-CONFIGURED-CONTEXT as the /admin path is the default.

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.

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/ENDPOINT-CONFIGURED-CONTEXT/home or simply https://localhost:2443/ENDPOINT-CONFIGURED-CONTEXT as the /home path is the default.

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: