Authentication

The collaboration server supports several different approaches to authentication.

Authentication is configured based on the request’s call origin, which in turn is determined by the access path prefix of the request URL. The path prefixes for trusted and untrusted call origins, which are relevant for authentication, are specified in the configuration properties

respectively. The default values are /co-unblu for trusted call origins and /unblu for untrusted call origins. If the trusted and untrusted access path prefixes are identical, only the authentication configuration for the trusted call origin is used.

When configuring authentication for Unblu, the first decision to make is which authentication sources should be used for each call origin.

For trusted: com.unblu.authentication.trusted.sources
For untrusted: com.unblu.authentication.untrusted.sources

For a given call origin, multiple sources can be configured.

Authentication source `NONE`

The NONE source only makes sense for the untrusted call origin. It means that unauthenticated visitors are allowed to use Unblu.

For the trusted call origin, the NONE source is only accepted when the trusted and untrusted entry path are the same. If they differ the value is rejected, because the concept of an unauthenticated agent makes no sense.

Using NONE with other authentication sources such as PROPAGATED and or LOCAL allows unauthenticated visitors to become authenticated while they are using Unblu. This concept is called "user change" and is explained in the section Unauthenticated access & authentication change tracking.

Authentication source `LOCAL`

With the LOCAL source, authentication is carried out using the built-in user management system which allows you to manage users in the agent desk or using the Web API.

When logging in from an untrusted call origin, users can only attain the WEBUSER role. Login may only be performed with the Web API (see below).

From a trusted call origin, only users with at least the REGISTERED_USER role may log in. They may do so using the login form (to obtain access to the agent desk) or the Web API.

Users must have a password to be able to log in.

Agents can log in to the Unblu agent desk using a traditional form requiring a username and password.

Figure 1. Agent desk user login form

Web API basic authentication

When using the Web API, the "basic authentication" mechanism can be used by setting the following configuration properties to true as required:

For trusted: com.unblu.authentication.propagated.trusted.allowBasicAuthentication
For untrusted: com.unblu.authentication.propagated.untrusted.allowBasicAuthentication

If you opt for this authentication method, the Authorization HTTP header must be sent with each request.

Web API authenticator service

The Web API’s authenticator service provides several alternatives to basic authentication.

A successful login will result in a response that includes a Set-Cookie HTTP header, irrespective of the endpoint used for authentication. The client can cache the provided cookie and include it with subsequent requests. This is the default behavior in web browsers, but may require additional configuration for other HTTP clients.

With username and password

The endpoint authenticator/login allows a login with a username and password.

With a token

The endpoint authenticator/authenticateWithToken is similar to authenticator/login, but is available as a GET request. Instead of username and password sent as JSON request body, it expects the single query parameter authenticationToken.

The token can be created with the endpoints:

authenticator/createAuthenticationToken (using a username and password)
authenticator/createAuthenticationTokenForCurrentUser

It is only valid for a brief period (configured with com.unblu.authenticator.authenticationTokenTTLInSeconds).

Since this HTTP request is a GET request, systems that keep track of requested URLs may store this authentication token.

With a JSON web token (JWT)

The endpoint authenticator/loginWithSecureToken allows for logging in using a JSON Web Token (JWT). To use this authentication method, the configuration property com.unblu.authentication.tokenSignup.enabled must be true. It is only available to authenticated users with the WEBUSER role on the untrusted entry path.

The method provides several JWT claims to propagate visitor information to the Unblu server. The example below demonstrates how to map these claims to visitor properties.

Listing 1. Example mapping of JWT claims to visitor properties for visitor information propagation

com.unblu.authentication.tokenSignup.claimMapping.username=email
com.unblu.authentication.tokenSignup.claimMapping.email=email
com.unblu.authentication.tokenSignup.claimMapping.firstName=firstName
com.unblu.authentication.tokenSignup.claimMapping.lastName=lastName
com.unblu.authentication.tokenSignup.claimMapping.additionalInformation=other

A sample app demonstrating this authentication method using a signed and encrypted JWT is available from our GitHub repository.

loginWithSecureToken is available in Unblu version 6.13.2 and later.

The endpoint authenticator/loginWithToken provides the single query parameter redirectOnSuccess. This can be used to redirect the agent to a specific page in the agent desk upon successfully logging in.

The same approach can also be used to open the agent desk in an iFrame to integrate Unblu into another system. First, the system obtains a valid authentication token with a backend call against the Web API. It can then construct a URL such as the one as shown below and set the URL as the value of the src attribute of an <iframe> tag in the page it is serving.

Listing 2. Example URL (for the Unblu cloud)

https://unblu.cloud/unblu/rest/v3/authenticator/loginWithToken?authenticationToken=<token-value>&redirectOnSuccess=https%3A%2F%2Funblu.cloud%2Fco-unblu%2Fdesk%2F%23%2Finbox%2Fmy-conversations

Authentication source `PROPAGATED`

The collaboration server supports identity (ID) propagation as an alternative to the built-in user management system. ID propagation is available for agents from a trusted call origin as well as for visitors using an untrusted call origin.

ID propagation is configured separately for each call origin. A number of aspects of ID propagation need to be configured:

The user mode (virtual or physical)
The definition of the propagated values
The source of the propagated values

Propagated users do not differ greatly from regular, local users. There are a few differences:

In an ID propagation setup it is not possible to log out from the Unblu system.
Users with the SUPER_ADMIN role are not allowed to switch to other accounts or to impersonate other users.
When users are created in the built-in user management system (see physical user mode below), they aren’t required to have a password.

User modes

It is possible to delegate agent authentication while still loading the users from the built-in user management system (i.e., in combination with automated user synchronization), or to use virtual users.

This is controlled with the com.unblu.authentication.propagated.trusted.virtualUserMode configuration property, which takes one of the following values:

DENY: The users have to be present in the Unblu user management system. This is referred to as physical user mode.
ALWAYS: The users are never taken from user management system. This is called virtual user mode.
ALLOW: both modes (physical and virtual) are possible.

In physical user mode, the configuration property com.unblu.authentication.propagated.trusted.userId must be configured to enable Unblu to retrieve the value corresponding to the username in the Unblu user management system. All other propagated values are ignored, and the user’s details are retrieved from the database. The mapping of a configuration key ending with userId to the value of a username attribute might be misleading. Beware of this when configuring your Unblu installation.

In virtual user mode, on the other hand, the user is not created in the database. Instead, they are created on the fly, with their property values determined according to the configuration properties com.unblu.authentication.propagated.trusted.*.

In both cases, a person entity will be created in order for the user to be present in conversations.

Propagated visitor user identities are always virtual.

Propagated values

The following user-related fields can be propagated.

Table 1. Fields available for propagated user details
Field	Mandatory	System Entry Paths
userId	yes	trusted, untrusted
roles	no	trusted
firstName	no	trusted, untrusted
lastName	no	trusted, untrusted
additionalInformation	no	trusted, untrusted
authInfo	no	trusted, untrusted
teamId	no	trusted
accountId	no (see note below)	trusted, untrusted

When the account is not specified the default account is used. Therefore when ID propagation is used with multiple accounts, the account must be specified with each request.

The following sources of propagation are supported:

Table 2. Possible sources of propagated values
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 Token	jwt:claim	jwt:email

Below are a few examples of how to configure ID propagation for different sources.

Headers

In this first example, Unblu is configured to use the content of an HTTP request header field x-unblu-trusted-user-id as the agent’s user id. Different headers are used for the visitor’s (untrusted) values.

Listing 3. ID Propagation sample configuration based on HTTP headers

# 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=DENY (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	Only allow authentication through ID propagation (virtual user mode). To enable the Unblu login form as well as ID propagation, set the property to `PROPAGATED,LOCAL`.
2	Limit authentication to users already present in the Unblu user database.

When using identity propagation based on HTTP headers, the reverse proxy must be configured in such a way as to ensure that these headers can never be supplied from the outside.

According to RFC 7230 only ASCII characters are allowed in header values. To support special characters nonetheless, Unblu requires that header values be encoded with URI percent encoding.

JSON web tokens

In this example, the user’s identity is supplied to Unblu using a JSON Web Token (JWT).

Listing 4. JWT configuration example

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

Support for JWT is available in Unblu version 6.6.0 and later.

OpenID Connect

OpenID Connect (OIDC) opaque Access Tokens can be used to provide Unblu with user information in an Authorization: Bearer HTTP header. Unblu will then call the UserInfo endpoint to resolve the user information of the token.

Listing 5. OIDC configuration example

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_name

By default, Unblu caches the Access Tokens for an hour. If your application uses tokens that are valid for less than an hour, you should adjust your configuration along the lines of the example below.

Listing 6. Configuring the TTL of the token cache

# Set token cache TTL to 10 minutes
com.unblu.authentication.oidc.tokenCacheTtl=600

Support for OpenID Connect is available in Unblu version 6.6.0 and later.

Unauthenticated access & 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 — because identity propagation sends a different user ID, say or because the user logs out — then the session will be terminated.

It is, however, possible to grant unauthenticated (anonymous) users access to the Unblu visitor UI from an untrusted call origin. This is usually done when visitors are not authenticated on the website that Unblu is integrated into. It is also possible to allow transitions between unauthenticated and authenticated sessions.

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 session’s chat protocol.