Unity Manual

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

Internally Unity is composed of two parts:

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

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

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

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

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

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

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

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

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

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

Unity can be started right away, but most probably the default setting should be changed. Please refer to the 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 is realized on the database level, and currently it is only supported when using MySQL.

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

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

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:

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.

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.

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

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.

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:

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.

Examples of some of the allowed combinations:

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

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 1.2.x (note that the latest version 2.x is much different). What is more the log4j-extras package is included so additional logging features are enabled. Logging is configured in the conf/log4j.properties file.

By default, log files are written to the the logs/ directory.

The following example config file configures logging so that log files are rotated daily, and the old log files are compressed.

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

Log4j supports a very wide range of logging options, such as date based or size based file rollover, logging different things to different files and much more. For full information on Log4j we refer to the publicly available documentation, for example the Log4j manual.

Unity 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.wikisource.org/wiki/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.

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.

The form definition consists of three 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. 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:

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.

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.

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.

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

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

Links to client management pages of the well known providers:

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

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

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

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:

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

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:

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

Web Admin UI is the first place to visit after server installation and startup as it offers a administrator oriented management interface. By default it is accessible under the link: https://localhost:2443/admin/admin

The features of the Web Admin interface are covered in the Contents management section.

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

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.

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:

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:

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

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

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

This endpoint is a slightly enhanced Web SAML SSO endpoint, with the UNICORE 7 Grid middleware support. It is useful for UNICORE portal SAML authentication, 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.

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.

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:

An example configuration:

The OAuth 2 endpoints expose a functionality of a generic Authorization Server with a support for the OpenID Connect specification. The code, implicit, client credentials 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.

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:

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:

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:

The following settings are allowed for the endpoint: