Finesse Thirdparty Client Integration with SSO

Introduction

This document describes how you can integrate the custom desktop client with Single Sign-On (SSO) in Unified Contact Center Enterprise (UCCE) or Unified Contact Center Express (UCCX). 

SSO is natively available with Finesse. It is one of the crucial features of the Cisco Unified Contact Center. SSO is an authentication process that allows users to sign in to one application and then securely access other authorized applications without the need to resupply user credentials. SSO permits Cisco supervisors and agents to sign in only once with a username and password to gain access to all of their browser-based Cisco applications and services within a single browser instance.

Prerequisites

Requirements

This document is not restricted to specific software and hardware versions.

Components Used

The information in this document is based on these software and hardware versions:

• Cisco Identity Server (IdS) 12.5
• Finesse 12.5(1)ES1 
• ADFS 2012
• UCCE 12.5

The information in this document was created from the devices in a specific lab environment. All of the devices used in this document started with a cleared (default) configuration. If your network is live, ensure that you understand the potential impact of any command.

Background Information

As a custom client, to send API requests to Finesse server your requests must be authorized. In the context of SSO, this authorization is provided using tokens so understand tokens first.

There are two types of tokens:

• Access Token- It accesses protected resources. Clients are issued an access token that contains identity information for the user. The identity information is encrypted by default.
• Refresh Token- It obtains a new access token before the current access token expires. The IdS generates the refresh token.

The refresh and access tokens are generated as a pair of tokens. When refreshing the access token, the pair of tokens provide an extra layer of security.

You can configure the expiry time of the refresh token and the access token in the IdS administration. When the refresh token expires, you cannot refresh the access token.

Fetch Access Token

With the new Finesse API implementations, you can use two query parameters cc_username and return_refresh_toekn in the Finesse URL to get the access-token.

(Available with 11.6.(1)ES10, 12.0(1)ES3,12.5(1)ES1 and later releases).

(In older releases we used to store the cc_username and tokens in session cookies and it’s still the same with native Finesse Desktop)

Example :

https://<fqdn>:8445/desktop/sso/token?cc_username=<agentid>&return_refresh_token=true

This redirects you to the AD FS (IdP) page

After successful authentication from ADFS, you are redirected to the token directly.

You can use this token to send requests to Finesse for the user as Bearer token.

Use the Authorization Header as Bearer <access token> in your custom code.

This sample uses the Postman Client.

When the request is sent with Access Token, you get the response with 200OK and the corresponding output. This image shows that the current state is fetched.

Similarly, the token can be used for State Change APIs to make Agent Ready, Not Ready, Logout, etc, and for Dialog APIs for Answering, Make Call, etc in the custom client.

Refresh Access Token

An access token has an expiry time. You must refresh this token before it expires.

As per the recommendation:

• Third-party applications have to refresh the access token after 75% of the token expiry time is elapsed.
• Invoking this API might involve browser redirect to Cisco Identity Server and Cisco Identity Provider.

IN order to refresh the access-token use this URL: https://<fqdn>:8445/desktop/sso/token?cc_username=<agentid>&refresh-token=<refresh-token-value>

You receive the new access token as shown in the image.

Now again you can use this new token as the access token to send a request to the Finesse server.