of 3

Documentation

Unblu 6 (latest)

The Unblu Financial CLoud allows you to use single sign-on (SSO) for your agents, visitors, or both. This article describes the different mechanisms used.

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 Financial Cloud to your organization’s directory service.

Unblu offers SSO based on OpenID Connect, an identity layer on top of OAuth 2.0. For each organization on the Unblu Financial Cloud, it uses a dedicated subdomain of https://unblu.cloud, e.g. https://yourcompany.unblu.cloud.

Requirements

To support SSO on the Unblu Financial Cloud, your identity provider (IDP) must meet the requirements listed below.

  • 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.

  • The access token presented must be provided as one of the following:

  • The user attributes of your agents must be supplied in the claims agreed upon with Unblu. If Unblu user roles are not provided in a claim, they must be managed in Unblu, e.g. via the Account Configuration interface.

We recommend that the validity of the access tokens presented to the Unblu Financial Cloud be limited to a relatively short time period, for example 1 hour.

If the initial access token obtained from your identity provider includes a refresh token, we recommend that you set its validity to 10 hours. Unblu will use the refresh token to obtain a new access token when the initial access token expires.

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 it cannot be used as the authentication mechanism without leading to a poor user experience.

Visitor SSO works as follows:

  1. 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 will attempt to load any unknown key.

  2. 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, notably Safari, block third-party cookies. 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, e.g. https://unblu.yourcompany.com, in the Unblu Financial Cloud. There are two additional steps required for the subdomain to work:

  • You must ensure that your DNS records are set up to redirect calls to the subdomain to the Unblu Financial Cloud.

  • You must provide Unblu with a valid SSL/TLS certificate for the subdomain. Alternatively, the certificate may be issued by Let’s Encrypt.

Examples

The sections below give examples for various aspects of visitor SSO. You can find a complete sample implementation of visitor SSO in our GitHub repo.

Authentication request

In this example, unblu.example.com is owned by the example company but points to the IP address of the Unblu Financial Cloud.

The visitor’s browser or mobile app sends an authentication request to the Web API endpoint authenticator/loginWithSecureToken.

Listing 1. The authentication POST request with the request body containing the access token
POST https://unblu.example.com/unblu/rest/v3/authenticator/loginWithSecureToken?x-unblu-apikey=6qNarnR6RWuerf0ZnnJDeQ

{
    token: "eyJraWQiOiJlMTA1YjkyMC1lMDcxLTQwOWItODllYS1lYjUyM2UwYmI1MzgiLCJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJhdWQiOiJodHRwczpcL1wvdmlzaXRvcnNzb2JhY2tlbmQuZGV2LnVuYmx1LXRlc3QuY29tXC91bmJsdSIsImZpcnN0TmFtZSI6IlBldGVyIiwibGFzdE5hbWUiOiJNdXN0ZXIiLCJpc3MiOiJodHRwczpcL1wvdmlzaXRvcnNzby5kZXYudW5ibHUtdGVzdC5jb20iLCJleHAiOjE2MTIzNTExNDEsImlhdCI6MTYxMjM0NzU0MSwiZW1haWwiOiJwZXRlci5tdXN0ZXJAZXhhbXBsZS5jb20ifQ.dB1JuRvQOHRpyWBgkJb2o0NbhVVQr2RNgu0Jd1QfE2pjjHmvpbP7v_saZfXHTCDL7dmOOju0dcuaBZFKfDkXXMXyjHIAwvNNJqYxwBSuRjxRh7mWimEroWBs-E_tdeJmuvyhI4W2tTcDM8fOIM-vw4cXPI5NoLHD68-VrOUqH9-2YU16LUmXB05C1fBFE-mKjfalcQWndOCbdCHMD2EierCubOgWmFdSCF7KaM_wte63YG6f07Q-HIVH4E43j3RfrA80RopcCI8xUrzupTiLjO7Ibe45iuATDKNHRfcI3sZRJNq6IPyzA9TXPnEWDFpymSi-SX5Xukq7VyXs-262uw",
    type: "JWT"
}

Upon successful authentication, the Unblu Financial Cloud sends this response:

Listing 2. Response setting session cookie
set-cookie: x-unblu-authsession="1FNjxPFySmCTH7wgc64RJg";Path=/unblu;Expires=Wed, 10 Feb 2021 10:19:01 GMT;SameSite=None;Secure;HttpOnly

JSON Web Key (JWK)

Unblu will load the public key from the URL configured in com.unblu.authentication.jwt.jwkUrl. It will then accept all JWTs signed with those keys.

The public key must be provided in the JWK format as specified in RFC 7517.

Listing 3. GET request to retrieve the public key for verifying the signature of the JWT
GET https://bank.example.com.com/api/jwk

The expected response will look similar to the one shown below.

Listing 4. Response to the GET request for the public key
{
   "keys":[
      {
         "kty":"RSA",
         "e":"AQAB",
         "use":"sig",
         "kid":"e105b920-e071-409b-89ea-eb523e0bb538",
         "n":"hQjPxhN2tmSnvM2zvDNk..."
      }
   ]
}

API authentication

In the example below, the

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