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 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 com.unblu.storage.resetSuperAdmin 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 |
roles | no | trusted |
firstName | no | trusted, untrusted |
lastName | no | trusted, untrusted |
additionalInformation | no | trusted, untrusted |
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 and will also be visible in the session statistics (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 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:
- com.unblu.authentication.propagated.trusted.roles
- com.unblu.authentication.propagated.trusted.firstName
- com.unblu.authentication.propagated.trusted.lastName
- com.unblu.authentication.propagated.trusted.additionalInformation
- com.unblu.authentication.propagated.trusted.virtualUserMode
Untrusted
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:
- com.unblu.authentication.propagated.untrusted.firstName
- com.unblu.authentication.propagated.untrusted.lastName
- com.unblu.authentication.propagated.untrusted.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.
This default policy prohibits all changes to authentication during a session The policy can be changed using com.unblu.authentication.propagated.trusted.allowedTransitions and com.unblu.authentication.propagated.untrusted.allowedTransitions to allow changed authentication during a session. It is possible to selectively allow transitions from ANONYMOUS to AUTHENTICATED, from AUTHENTICATED to ANONYMOUS, or even from AUTHENTICATED to AUTHENTICATED (with a different user).
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
- userauthenticator authenticate via REST api
- users manage users in the built in user directory using REST api
- System Entry Path Concept
- deployonprem