Overview

Single Sign-On (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 re-enter their credentials. Once authenticated, users can access all of the authorized Cisco web applications.

Components of a Typical Contact Center SSO Enabled Deployment

The following components work in tandem to provide the Single Sign-On functionality:

  • Cisco Identity Service (IdS): This component is available in a Contact Center solution deployment, starting from the release 11.5(1) onwards. This service is either embedded in the Cisco Unified Contact Center Express (Unified CCX) and Packaged Contact Center Enterprise deployments (Packaged CCE) or in a standalone form in the Cisco Unified Contact Center Enterprise (Unified CCE).

  • Identity Provider (IdP): An Enterprise Identity Provider that usually creates, maintains, and manages identity information for the principals (users, services, or systems) and provides authentication for those principals to other service providers (applications).

  • Cisco Contact Center Web Applications and REST API Services: These are the Cisco Contact Center products, which provide web based applications and REST API services. For example, Cisco Finesse and Cisco Unified Intelligent Center.

  • Partner Application(s): Partner developed software applications, which service REST API calls or provide Cisco Finesse based gadgets.

Cisco Identity Service (IdS)

Cisco Identity Service (IdS) is a light-weight OAuth server built to support Single Sign-On. From the 11.5(1) release onwards, the IdS is supported in Unified CCX, Packaged CCE, and  Unified CCE solutions.

Cisco Identity Service: A Technical Overview

Cisco Identity Service uses the combination of SAML 2.0 and OAuth 2.0 protocols to offer cross-domain and cross-product Single Sign-On for Cisco Customer Care solutions.

It allows the exchange of user authentication data between an IdP, IdS and SSO enabled applications while maintaining high-security levels.

Authentication using SAML 2.0

SAML 2.0 is used as the user authentication protocol. Using OAuth, the IdS works as an OAuth server to issue tokens that allow users to login to various web applications and also access service APIs. The IdS supports the Authorization Code Grant flow implementation of OAuth.

IdS establishes a Circle of Trust (CoT) by exchanging metadata and certificates as part of the provisioning process between the IdP and the IdS. All the applications register as OAuth clients with the IdS so as to access and validate the oAuth tokens with the IdS.

When an unauthenticated user tries to access an SSO enabled application, the application redirects to the IdS to trigger the Authorization Code Grant Flow. The IdS uses SAML to authenticate the user through the configured IdP.

On successful authentication, the IdP issues a SAML assertion to the IdS. The IdS, then, generates a short lived authentication code (referred as authcode) to the application. The application, then submits this authcode to the IdS and fetches the oAuth token pair: access token and refresh token.

Authorization

The individual applications are responsible for the required authorization checks (for example, post successful authentication), the applications get the userid, which is to be used to internally (may be database lookup) to identify the corresponding user roles and so on.

IdSClient SDK

To simplify the integration efforts for the developers, the vital IdS interfaces are abstracted out into a Java library, the IdS Client SDK.

The IdS Client SDK exposes Java APIs to the following:

  1. Get an access token
  2. Validate the obtained token
  3. Refresh the access token before its expiry.

Access Token

Access tokens are used to access the protected resources. An access token is a string representing an authorization issued to the client.

IdS generates this token, which is essentially a JWE (JSON Web Encryption) token. Only IdS can decrypt this token.

Refresh Token

Refresh tokens are used to obtain a new access token before the current access token expires.

Refresh Token is also generated by Cisco IdS. This is also a JWE (JSON Web Encryption) token. Only IdS can decrypt this token.

Enable SSO for Partner Web Applications

Partner web applications must use the IdSClientlib (IdS Client Library) SDK in their server side implementation to interact with IdS and obtain the access token that is used to invoke the Cisco Contact Center APIs.

A browser is involved in the SAML 2.0 authentication flow and hence obtaining a token involves a user accessing the application using a browser.

When the authentication is successful, the authorization code is delivered to the application (server) through the browser. Pure browser based (JavaScript based) applications are not supported.

SSO Workflow for Partner Web Applications

SSO Workflow

Register Your Application

To make your application as part of the IdS SSO ecosystem, the application must be registered or on-boarded with IdS.

Every application that invokes some Contact Center (CC) product API which is SSO enabled (expects bearer token for authentication), needs to register themselves with IdS as a client.

To register an application:

  1. Navigate to the Identity Service Management console by going to: https://<your_CCX_Host>:8553/idsadmin
  2. Login using the Cisco Unified CCX application user credentials.
  3. Select the Clients icon on the left side of navigation. Identity Service Management UI
  4. Click on the Add Client button in the upper right hand side.
  5. Fill the form

    • Enter a unique name for the client (partner application).

    • Enter one or more redirect URLs to which the authorization code has to be delivered.

    • Click the '+' button on the right of the input field.

      Identity Service Management Add Client

  6. Click the Add button to add the client.

Integrate IdSClient SDK at the server side of your application

Using the IdSClient SDK with your application involves the following steps:

  1. Provide an application specific IdSClientConfiguration implementation:
    • The IdSClient Library provides a default implementation (com.cisco.ccbu.common.ids.client.impl.IdSClientConfigurationImpl) where it reads the configuration from a given configuration file instance. Applications can use the instance of this implementation if it suffices their needs.
    • Components may override the getFileName() and getFilePath() methods to make appropriate customizations to the Default IdSClientConfguration implementation.
    • IdSClient interface is the main library interface. This is implemented by IdSClientImpl. Applications can set their own TrustManager and HostnameVerifier for SSL trust store.
    • The SDK provides a default implementation of TrustManager that trusts everything that comes along and a HostnameVerifier that verifies any host. NOTE: This is provided only for testing purposes. We strongly discourage its use in production.
  2. Initialize the IdSClient with the customized client configuration on application start:
    • IdsClient provides an init(IdSClientConfiguration config) method which applications should use to initialize/reinitialize the IdSClient with new/updated configuration.
  3. In the partner application code:

    • Get the IdS client reference:

      IdSClient idsClient = IdSClientFactory.getIdSClient();

   * Set a client specific TLS Context:

     ```java     
IdSClient idsClient = IdSClientFactory.getIdSClient();
idsClient.setTLSContext(ClientSpecific instanceOf X509TrustManager, ClientSpecific instanceOf HostnameVerifier);

  • Initialize/reinitialize a client with new/updated configuration:

      IdSClient idsClient = IdSClientFactory.getIdSClient(); idsClient.init(ClientSpecific instanceOf IdSClientConfiguration);


### Fetch the access token
The IdS posts the `authcode` as part of the authentication flow.

The application code would then have to invoke the below Java API to fetch the access token

```java
AccessToken getAccessToken(String authorizationCode, String redirectURL) throws IdSClientException

Validate the access token

To validate a given access token, use the following API:

TokenInfo validateToken(String accessToken) throws IdSClientException

When a token is validated by the IdS server, if caching is enabled, then the token details that are obtained from the server will be cached at the client side. For any subsequent validation requests for the same token, the token details are fetched from the cache itself.

If the object is not present in the cache or the cache entry has expired, then the request is forwarded to the IdS server.

Token Caching

Applications can enable Token Caching with either user-defined caching properties or defaults. Cache properties can be set before or after enabling Token Caching. Changing these properties will have the immediate effect.

When Token Caching is enabled, a polling thread will start. Disabling Token caching stops this polling thread. Explicit disabling is necessary to avoid memory leaks. The Token Caching needs to be disabled when the web application is reloaded or restarted.

void setTokenCaching(boolean isTokenCachingEnabled)

Applications can also set the cache property for the Token Caching. Caching properties are predefined with default values. Each property has a minimum and maximum value. Any value set for these properties must be within the range for that property. The API will return True if a custom value for a property is saved successfully. It will return False if the values are not in the specified range. Custom set properties are not persisted and those values are lost when the IdS client restarts.

boolean setTokenCachingProperty(CacheProperty property, String Value)

Enable Retry Mechanism

Applications can decide to retry if the IdS REST API (get access token, validate access token, and refresh access token) fails for the first time with HTTP 503 response.

void setRetryEnabled(boolean retryEnabled)

Appendix: Sample Code

During SSO Service Start-up

IdSClientConfigurationImpl config = new IdSClientConfigurationImpl.(“… file path …”);
config.load();

// Instantiate IdS Client
IdSClient client = IdSClientFactory.getIdSClient();
client.setTLSContext(customTrustMngr, customHostVerifier);

// Init IdS Client with Configuration loaded earlier
client.init(config);

During Agent Login

// Get Access Token for the received Authorization Code
String redirectURI = config.getRedirectUri();
AccessToken token = client.getAccessToken(authCode, redirectURI);

String accessTokenString = token.getAccess_token();
// pass the above access token to frontend application

Token Refresh while Agent is Still in Shift

// To refresh the token before expiry
AccessToken refreshedToken = client.refreshAccessToken(token.getAccess_token(), token.getRefresh_token());

String accessTokenString = token.getAccess_token();
// pass the above access token to the frontend application

During Agent Logout

// On agent logout, remove the OAuth token from ids client cache
client.removeToken(accessToken);

During Application Service Shutdown

// Cleanup when SSO Service is shutting down
client.getIdSStatusMonitor().cleanUp();
client.setTokenCaching(false);

Additional Sample Code

Additional sample code can be found in the UCCX IdS Sample Code repository.