|
This document describes version 5 of Unblu. If you’re using the latest major version of Unblu, go to the documentation of the latest version. The support period for version 5 ended on 22 November 2021. We no longer provide support or updates for this version. You should upgrade to the latest version of Unblu. |
Authentication
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 webapi-home. 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 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 com.unblu.storage.resetSuperAdmin to true.
| 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 |
# trusted path
com.unblu.authentication.trusted.sources=PROPAGATED (1)
com.unblu.authentication.propagated.trusted.userId=header:x-unblu-trusted-user-id
com.unblu.authentication.propagated.trusted.virtualUserMode=ALLOW (2)
# untrusted path
com.unblu.authentication.untrusted.sources=PROPAGATED (1)
com.unblu.authentication.propagated.untrusted.userId=header:x-unblu-untrusted-user-id
com.unblu.authentication.propagated.untrusted.firstName=header:x-unblu-untrusted-first-name
com.unblu.authentication.propagated.untrusted.lastName=header:x-unblu-untrusted-last-name| 1 | Allow only propagated authentication, set to PROPAGATED,LOCAL to also enable the login form in Unblu. |
| 2 | Allow propagated users that are not present in the Unblu user database. |
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.
Configuration
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.
Trusted
Use configuration-properties 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 userid must be configured and, optionally, you can configure the following:
-
roles -
first -
last -
additionalInfo -
virtual
Untrusted
Use configuration-properties 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 userid must be configured and, optionally, you can configure the following:
-
firstName -
lastName -
additionalInformation
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.