Authentication and single sign-on (SSO) in self-hosted and on-premises installations
This article discusses the authentication methods available in self-hosted and on-premises installations. For information on authentication in the Unblu Cloud, see Single sign-on in the Unblu Cloud. |
The Collaboration Server supports several different approaches to authentication.
Authentication is configured based on the request’s entry path, which in turn is determined by the access path prefix of the request URL. The path prefixes for INTERNAL
and PUBLIC
entry paths, which are relevant for authentication, are specified in the configuration properties:
-
com.unblu.identifier.internalPathPrefix for the
INTERNAL
entry path -
com.unblu.identifier.publicPathPrefix for the
PUBLIC
entry path
The default values are /app
for the internal entry path and /unblu
for the public entry path.
When configuring authentication for Unblu, the first decision to make is which authentication sources should be used for each entry path.
-
For the
INTERNAL
entry path: com.unblu.authentication.internal.sources -
For the
PUBLIC
entry path: com.unblu.authentication.public.sources
You can configure multiple sources for each entry path.
Authentication source NONE
The NONE
source only makes sense for the public entry path. It means that unauthenticated visitors are allowed to use Unblu.
Using NONE
with other authentication sources such as PROPAGATED
or LOCAL
allows unauthenticated visitors to become authenticated while they’re 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 Unblu web API.
When logging in from a PUBLIC
entry path, users can only attain the WEBUSER
role. Login may only be performed with the Unblu web API (see below).
From an INTERNAL
entry path, 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 Unblu web API.
Users must have a password to be able to log in.
Agent Desk login form
Agents can log in to the Unblu Agent Desk using a traditional form requiring a username and password.
Web API basic authentication
When using the Unblu web API, the "basic authentication" mechanism can be used by setting the following configuration properties to true
as required:
If you opt for this authentication method, the Authorization
HTTP header must be sent with each request. The header will be processed by Unblu using the charset specified in the configuration property com.unblu.rest.basicAuthEncoding. The default charset for the Authorization
HTTP header is UTF-8. To avoid problems, make sure that any clients consuming the API use the same charset.
In Unblu 6, the default charset was ISO-8859-1. |
Web API authenticator service
The Unblu 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
in the JSON request body, it expects the single query parameter authenticationToken
.
The token can be created with the endpoints:
-
/authenticator/createAuthenticationToken
(using ausername
andpassword
)
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). It’s only available to authenticated users with the WEBUSER
role on the PUBLIC
entry path.
To use this authentication method, the configuration property com.unblu.authentication.tokenSignup.enabled must be true
.
The method provides several JWT claims to propagate visitor information to the Unblu server. The configuration properties to map these claims to visitor properties can be found in the group com.unblu.platform.server.core.auth.configuration.ClaimMappingConfiguration.
The values of JWT claim mappings are case sensitive: "john.smith@yourcompany.com" and "John.Smith@yourcompany.com" aren’t the same value.
The example below demonstrates how to map JWT claims to visitor properties.
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.authInfo=authInfo
com.unblu.authentication.tokenSignup.claimMapping.additionalInformation=other
Nested JWT claims are accessible using dot notation. For example, given the token below, the value of user_name
("john.smith@yourcompany.com") can be accessed through resources.unblu_access.user_name
. That’s the value you’d assign the configuration property com.unblu.authentication.tokenSignup.claimMapping.username.
"resources" : {
"unblu_access": {
"user_name": [
"john.smith@yourcompany.com"
]
},
//...
}
Users authenticated with a JWT are created on the fly as virtual users (see User modes below).
The visitor and embedded JS APIs include a login()
convenience method to handle authentication. The methods expect a JWT for Unblu to authenticate the visitor.
The Android and iOS mobile SDKs let you include an access token in the configuration for the Unblu API. For more information, refer to the documentation of UnbluClientConfiguration.Builder.setAccessToken()
(Android) and UnbluClientConfiguration.accessToken
(iOS).
A sample app demonstrating this authentication method using a signed and encrypted JWT is available from the Unblu GitHub repository. There is also a tutorial.
Using the authenticator service to bypass the login form
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 like the one shown below and set the URL as the value of the
src
attribute of an<iframe>
tag in the page it’s serving.
https://unblu.cloud/unblu/rest/v3/authenticator/loginWithToken?authenticationToken=<token-value>&redirectOnSuccess=https%3A%2F%2Funblu.cloud%2Fapp%2Fdesk%2F%23%2Finbox%2Fmy-conversations
If you have deployed Unblu in a cross-origin setup (as opposed to a site-embedded setup) and want to integrate the Agent Desk using an <iframe>
element, you will have to set the configuration property com.unblu.identifier.sameSiteForInternalPath to NONE
. This ensures that the SameSite
cookie attribute is set to NONE
for calls to INTERNAL
entry paths. (The cookie’s Secure
attribute is still determined by the configuration property com.unblu.identifier.cookieSecureFlag.)
If your setup doesn’t use an account ingress, you must set the configuration property to NONE
in the global scope. If you have a setup with an account ingress, you can choose to set the configuration property to NONE
in the scope of the account or accounts where it is needed.
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 an INTERNAL
entry path as well as for visitors using a PUBLIC
entry path.
ID propagation is configured separately for each entry path. A number of aspects of ID propagation need configuring:
-
The user mode (virtual or physical)
-
The definition of the propagated values
-
The source of the propagated values
Propagated users don’t differ greatly from regular, local users. The differences are:
-
In an ID propagation setup it isn’t possible to log out of the Unblu system.
-
Users with the
SUPER_ADMIN
role aren’t 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’s possible to delegate agent authentication while still loading the users from the built-in user management system (that is, in combination with automated user synchronization), or to use virtual users.
This is controlled with the configuration property com.unblu.authentication.propagated.internal.virtualUserMode, 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 Unblu’s user management system. This is called virtual user mode. -
ALLOW
: Both modes (physical and virtual) are possible.
In physical user mode, the users' details are retrieved from the Unblu database. The configuration property com.unblu.authentication.propagated.internal.userId (not username
) must be configured to enable Unblu to retrieve the value corresponding to the username
property in the Unblu user management system. If you propagate authentication information or additional information, the configuration properties com.unblu.authentication.propagated.internal.authInfo and com.unblu.authentication.propagated.internal.additionalInformation, respectively, must also be configured accordingly.
All other propagated values are ignored.
In virtual user mode, users are created in the database when they are first authenticated via ID propagation. Their property values are determined according to the configuration properties com.unblu.authentication.propagated.internal.*
. Any changes to these property values must be propagated; they can’t be edited in Unblu. You can, however, edit the settings and the canned responses of virtual users.
In both physical and virtual user mode, a person entity will be created in order for the user to be present in conversations.
The distinction between physical and virtual users doesn’t apply to visitors. Propagated visitor user identities are always virtual. |
Propagated values
The following user-related fields can be propagated.
Field | Mandatory | System entry paths |
---|---|---|
username |
yes |
internal, public |
roles |
no |
internal |
no |
internal |
|
phone |
no |
internal |
firstName |
no |
internal, public |
lastName |
no |
internal, public |
additionalInformation |
no |
internal, public |
authInfo |
no |
internal, public |
teamId |
no |
internal |
accountId |
no |
internal, public |
Please note:
-
If no account is specified, the server’s default account is used. When ID propagation is used with multiple accounts, the account must therefore be specified with each request.
-
For the
accountId
value, either the ID (e.g.wZvcAnbBSpOps9oteH-Oxw
) or the name (e.g.Main Account
) may be used. -
For the
teamId
value, too, either the ID or the team name may be used. -
If the team or role you provide doesn’t exist, ID propagation fails with an error.
-
The
username
field is case sensitive. You must provide the value of the field in the way Unblu should use it, for example, if you want it to be treated as lower-case in Unblu. -
Propagated roles are not case sensitive.
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 |
oidc |
OpenID Connect using opaque access tokens |
oidc:claim |
oidc:email |
jwt |
JSON Web Token |
jwt:claim |
jwt:email |
Character set for propagated header and cookie values
By default, Unblu expects propagated header and cookie values to be URL encoded. If the values you propagate contain a reserved character such as +
, you must either propagate the values using proper percent encoding or disable URL decoding in Unblu.
To disable URL in Unblu, set the following configuration properties to false
as needed:
Doing so restricts the characters you can use in propagated values to the ISO-8859-1 character set.
Examples
Below are a few examples of how to configure ID propagation for different sources.
Headers
In this example, Unblu is configured to use the content of the 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.
# internal path
com.unblu.authentication.internal.sources=PROPAGATED (1)
com.unblu.authentication.propagated.internal.userId=header\:x-unblu-trusted-user-id
com.unblu.authentication.propagated.internal.virtualUserMode=DENY (2)
# public path
com.unblu.authentication.public.sources=PROPAGATED (1)
com.unblu.authentication.propagated.public.userId=header\:x-unblu-untrusted-user-id
com.unblu.authentication.propagated.public.firstName=header\:x-unblu-untrusted-first-name
com.unblu.authentication.propagated.public.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).
com.unblu.authentication.public.sources=PROPAGATED
com.unblu.authentication.propagated.public.userId=jwt\:email
com.unblu.authentication.jwt.httpHeader=X-UNBLU-JWT (1)
com.unblu.authentication.jwt.jwkUrl=https\://www.googleapis.com/oauth2/v3/certs
com.unblu.authentication.jwt.expectedIssuer=https\://accounts.google.com
# Only accept JWT containing aud=unblu-sso-client-id
com.unblu.authentication.jwt.expectedAudience=unblu-sso-client-id
1 | If you want to use bearer tokens for authentication, set this configuration property to Authorization . The HTTP header must contain the type Bearer followed by the token. |
The configuration properties that start with com.unblu.authentication.jwt.*
are also available as configuration properties for the internal und public entry paths. The names of the configuration properties begin with com.unblu.authentication.jwt.internal.*
and com.unblu.authentication.jwt.public.*
, respectively.
Opaque access tokens
OpenID Connect (OIDC) opaque access tokens can provide Unblu with user information in an Authorization: Bearer
HTTP header. Unblu then calls 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.public.sources=PROPAGATED
com.unblu.authentication.propagated.public.userId=oidc\:email
com.unblu.authentication.propagated.public.firstName=oidc\:given_name
com.unblu.authentication.propagated.public.lastName=oidc\:family_name
You can specify different UserInfo endpoints for the internal and/or public entry path:
com.unblu.authentication.oidc.internal.userInfoEndpoint=https\://openidconnect.googleapis.com/v1/userinfo
com.unblu.authentication.oidc.public.userInfoEndpoint=https\://yourtenant.b2clogin.com/yourtenant.onmicrosoft.com/policy-name/openid/v2.0/userinfo
You can specify how long Unblu should wait for OIDC UserInfo endpoints. The default timeout is 2 s, the maximum timeout is 30 s. To wait indefinitely, set the timeout to 0.
# Specify general UserInfo timeouts
config:com.unblu.authentication.oidc.userInfoConnectTimeout [PROPERTIES,30]
config:com.unblu.authentication.oidc.userInfoReadTimeout [PROPERTIES,30]
# Alternatively, set different timeouts for public and internal endpoints
config:com.unblu.authentication.oidc.public.userInfoConnectTimeout [PROPERTIES,30]
config:com.unblu.authentication.oidc.public.userInfoReadTimeout [PROPERTIES,30]
config:com.unblu.authentication.oidc.internal.userInfoConnectTimeout [PROPERTIES,30]
config:com.unblu.authentication.oidc.internal.userInfoReadTimeout [PROPERTIES,30]
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.
# Set token cache TTL to 10 minutes
com.unblu.authentication.oidc.tokenCacheTtl=600
You can override the general configuration property and define different token cache TTL for the internal and/or public entry path:
com.unblu.authentication.oidc.internal.tokenCacheTtl=3600
com.unblu.authentication.oidc.public.tokenCacheTtl=180
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 a prohibited change in authentication is detected during a session, then the session will be terminated. A prohibited change in authentication can occur, for example, because identity propagation sends a different user ID, or because the user logs out.
It is, however, possible to grant unauthenticated (anonymous) users access to the Unblu visitor UI from a PUBLIC
entry path. This is usually done when visitors are not authenticated on the website that Unblu is integrated into.
User change: transitioning from unauthenticated to authenticated access
You can configure Unblu so that visitors can authenticate themselves during a conversation. This is referred to as user change.
If you do, when a visitor with the role ANONYMOUS
logs in during a session, the person entity associated with the anonymous user in the session is replaced with that of the authenticated user. In the background, the anonymous user leaves the conversation with the reason USER_CHANGED
.
The authenticated user’s participation in the session is associated with the anonymous user’s participation. That way, messages sent when the visitor was anonymous are associated with the authenticated user. Unblu UIs display messages from the authenticated and anonymous user as coming from the same participant.
If the visitor was in an onboarding process, the bot performing the onboarding is informed of the user change with a bot.dialog.counterpart_changed
event.
To allow users to log in during a session without ending the session, make the following changes to your configuration:
-
Set com.unblu.authentication.allowVisitorLoginDuringSession to
true
. -
Set com.unblu.conversation.lifecycle.replaceUserOnLogin to
ALWAYS
orIF_ACTIVE_CONVERSATION
.
Every time the authenticated user changes within a session (if allowed by the configured policy), a message describing the user change is added to the session’s chat protocol.