The collaboration server supports several different approaches to authentication. These differing approaches depend on the System Entry Path Concept. The available options are described below.

Local Authentication

The collaboration server comes with a built-in user management system that lets you administer (agent) users in the Agent Desk UI or using Web API. Local authentication is only available for the trusted system entry path.

Superadmin password

On initial installation, a single user called "superadmin", with a randomly-generated password, is created. The password of the superadmin user is stored in a file called superadmin.password inside the directory defined in com.unblu.logging.outputDirectory; if this directory has been defined.

If the directory (using com.unblu.logging.outputDirectory has not been defined then the file will be stored in the system's default temporary folder.

Store this password securely! as it is required to gain access to the server's Agent Desk UI.

The superadmin.password file needs to be deleted after initial startup of the server, otherwise the server will not allow ordinary (non superadmin) users to login.

Restoring the superadmin password

If the "superadmin" user's password gets lost, a new one can be generated by configuring to true.

Note: The collaboration server must be restarted after applying this configuration then, after the restart, set this property to false again.

Identity Propagation

The collaboration server supports identity propagation as an alternative to using interactive (username + password) login against the built-in user management system. Identity propagation is available for agents using the (trusted system entry path) as well as for visitors using the (untrusted system entry path). For agents it is possible to delegate authentication while still using the users from the built-in user management system (i.e., in combination with automated user synchronization) or to use virtual users. Propagated visitor user identities are always virtual; as the built-in user directory does not hold information about visitor users.

Identity propagation allows you to specify a number of user-related properties (the first would be a user id) to be propagated to unblu using any of a number of propagation mechanisms.

For example, you could configure unblu to use the content of an http request header field as the user id.

The following user-related fields can be propagated:

Field Mandatory System Entry Paths
userId yes trusted, untrusted
role no trusted
firstName no trusted, untrusted
lastName no trusted, untrusted
additionalInformation no trusted, untrusted
team no trusted
account no trusted

The following sources of propagation are supported:

name description format example configuration value
header http request header field header:<name> header:x-unblu-user-id
attribute java request attribute attribute:<name> attribute:x-unblu-user-id
cookie http cookie cookie:<name> cookie:x-unblu-user-id
jee jee-based authentication jee:principal jee:principal

Unauthenticated Access

For the untrusted system entry path (visitor access) it is also possible to allow access to unauthenticated (anonymous) users. Usually, this makes sense if the visitors are also unauthenticated in the site where unblu is integrated. It is also possible to allow transitions between unauthenticated and authenticated. These transitions are tracked by unblu (see Authentication Change Tracking).


Authentication configuration is done on a per-system access-path basis. If the trusted ("/co-unblu") and untrusted ("/unblu") system entry paths are identical (system entry path concept disabled; see System Entry Path Concept ) then only the configuration for the trusted path is used.

The first decision to be taken when designing authentication configuration is which sources for authentication should be used for each system entry path.


Use com.unblu.authentication.trusted.sources to select sources for the trusted system entry path.

If only LOCAL is configured in sources then no additional configuration is required.

If PROPAGATED is configured then at least com.unblu.authentication.propagated.trusted.userId must be configured and, optionally, you can configure the following:


Use com.unblu.authentication.untrusted.sources to select sources for the untrusted system entry path.

If only NONE is configured in sources then no additional configuration is required.

If PROPAGATED is configured then at least com.unblu.authentication.propagated.untrusted.userId must be configured and, optionally, you can configure the following:

Authentication Change Tracking

The collaboration server tracks authentication changes within the scope of a web session. By default unblu prohibits authentication changes during a session. This means that if, during a session, a prohibited change in authentication is detected (e.g., because identity propagation sends a different user id or because the user logs out) then the session will be terminated.

Every time the authenticated user changes within a session (if allowed by the configured policy), a message describing the user change will be added to the sessions chat protocol.

Further Reading

  • deployonprem

results matching ""

    No results matching ""