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 |
oidc |
OpenID Connect using opaque Access Tokens |
oidc:claim |
oidc:email |
jwt |
Json Web Tokens |
jwt:claim |
jwt:email |
# 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. |
| When using HTTP header based identity propagation a reverse proxy needs to ensure that those header can never be supplied from an untrusted source. |
Json Web Tokens
The user identity can be supplied into Unblu using a Json Web Token (JWT).
com.unblu.authentication.untrusted.sources=PROPAGATED
com.unblu.authentication.propagated.untrusted.userId=jwt\:email
com.unblu.authentication.jwt.httpHeader=X-UNBLU-JWT
com.unblu.authentication.jwt.jwkUrl=https\://www.googleapis.com/oauth2/v3/certs
com.unblu.authentication.jwt.expectedIssuer=https\://accounts.google.com| JWT support is available in Unblu 6.6.0 and later versions. |
OpenID Connect
OpenID Connect (OIDC) opaque Access Tokens can be propagated into Unblu in an Authorization: Bearer HTTP header. Unblu will then call the UserInfo endpoint to resolve the user information of the token.
com.unblu.authentication.oidc.userInfoEndpoint=https\://openidconnect.googleapis.com/v1/userinfo
com.unblu.authentication.untrusted.sources=PROPAGATED
com.unblu.authentication.propagated.untrusted.userId=oidc\:email
com.unblu.authentication.propagated.untrusted.firstName=oidc\:given_name
com.unblu.authentication.propagated.untrusted.lastName=oidc\:family_nameUnblu cache the Access Tokens for an hour by default. In case your application uses tokens that are valid for less than an hour, you should set this configuration to a lower value.
# Set token cache TTL to 10 minutes
com.unblu.authentication.oidc.tokencachettl=600| OpenID Connect support is available in Unblu 6.6.0 and later versions. |
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.