Single sign-on in the Unblu Cloud
The Unblu Cloud allows you to use single sign-on (SSO) for your agents, visitors, or both. This article describes the different mechanisms used.
This article discusses single sign-on in the Unblu Cloud.. For information on authentication in self-hosted and on-premises installations, see Authentication in self-hosted and on-premises installations. |
Agent SSO
Agents are typically employees of your organization. As such, their details are often already stored in a directory service or identity provider of some kind. It makes sense to leverage this fact and link authentication for the Unblu Cloud to your organization’s directory service.
Unblu offers agent SSO based on OpenID Connect.
Requirements
To support SSO on the Unblu Cloud, your identity provider (IDP) must meet the requirements below.
-
We use either the access token or the ID token to extract the user information from the JWT claims.
-
When you use an access token, it must be provided as one of the following:
-
An opaque access token with which Unblu may call the
UserInfo
endpoint of the identity provider.
-
The user attributes of your agents must be supplied in the claims agreed upon with Unblu. If a claim doesn’t provide Unblu user role information, the user roles must be managed in Unblu, for example via the Account Configuration interface.
-
API clients must first acquire an access token using the OAuth 2.0 Client Credentials grant type. The client should then present Unblu with a valid access token in an
Authorization: Bearer <token>
HTTP header.
You should limit the validity of the access tokens presented to the Unblu Cloud to a relatively short period, for example 1 hour.
If the initial access token obtained from your identity provider includes a refresh token, you should set its validity to 10 hours. Unblu will use the refresh token to obtain a new access token when the initial access token expires.
It is strongly recommended that you provide refresh tokens to ensure a smooth user experience. |
Visitor SSO
For visitors, the Unblu UI is typically embedded as a widget in your website. Since OpenID Connect relies on browser redirects, this means Unblu must use an alternative authentication mechanism to avoid an unsatisfactory experience for your users.
Visitor SSO works as follows:
-
Your application must issue a JWT signed with a private key and send it to Unblu from the visitor’s browser. The corresponding public key must be accessible to Unblu in the JSON Web Key (JWK) format wrapped in a JWK Set. You can rotate the keys regularly: Unblu attempts to load any unknown key.
-
Unblu sets a session cookie authenticating all requests from the visitor’s browser until either the session expires or an explicit logout occurs.
Some browsers block third-party cookies. Apple Safari is one such browser. Google Chrome, too, is preparing to phase out third-party cookies, as described in the Google Chrome docs. Visitor SSO must therefore run on the same second-level domain as your host application. To this end, Unblu configures a dedicated subdomain of your domain, such as https://unblu.yourcompany.com, in the Unblu Cloud. For the subdomain to work, you must create a CNAME record pointing to the cloud instance your Unblu installation is running on.
Unblu uses certificates issued by Google Trust Services or Let’s Encrypt and automatically rotates the certificates at regular intervals (after at most 90 days).
If this approach isn’t possible for you, contact your Unblu account manager.
Implementation
An implementation tutorial with code samples is available at unblu.github.io/unblu-visitor-sso-sample.
API authentication
For web API calls, the Unblu Cloud supports the "Basic" authentication scheme and the "Bearer" authentication scheme. When you implement single sign-on, inform the Unblu Cloud team which authentication scheme you intend to use.
The first example uses curl
to call an endpoint of the Unblu web API using the "Basic" authentication scheme.
USER_NAME='<username>'
USER_PASSWORD='<password>'
curl -u $USER_NAME:$USER_PASSWORD -v https://unblu.yourcompany.com/unblu/rest/v3/authenticator/getCompactUser (1)
1 | For the "Basic" authentication scheme, the username and password must be separated by a colon : . |
The example below shows the two steps required with the "Bearer" authentication scheme. It first uses curl
to acquire an access token, then it calls an endpoint of the Unblu web API, passing the access token to the Unblu server in an Authorization: Bearer <token>
HTTP header. Note that your IDP must support the client credentials grant for the application that you want to use the "Bearer" authentication scheme to access the Unblu web API.
CLIENT_ID="unblu-api-access"
CLIENT_SECRET="very-secret"
ACCESS_TOKEN=$(\
curl -s -X POST https://idp.yourcompany.com/token \
--user $CLIENT_ID:$CLIENT_SECRET \
-H 'content-type: application/x-www-form-urlencoded' \
-d 'grant_type=client_credentials' | jq --raw-output '.access_token' \
)
echo $ACCESS_TOKEN
curl -s -H "Authorization: Bearer $ACCESS_TOKEN" -v https://unblu.yourcompany.com/unblu/rest/v3/authenticator/getCompactUser
See also
-
For a general tutorial on setting up visitor login with a JWT, refer to Visitor login with a JSON web token (JWT).