Cisco Unified Communications Single Sign-On for APIs

 

Recent enhancements to several Cisco Unified Communications (UC) products - including Cisco Unified Communications Manager, Cisco Unity Connection and Webex - have brought the benefits of Single Sign-On authentication technologies to users, and now to UC developers writing apps integrated via UC APIs.

 

'Single Sign-On' (SSO) covers a spectrum of concepts, system security architectures, protocols and standards designed to allow end-users to 'log in once' and obtain access to multiple applications and services on the network (Wikipedia [http://en.wikipedia.org/wiki/Single_sign-on])  The benefits are clear, and include: greater ease-of-use for end-users, savings in productivity and support due to lost passwords or password resets, centralized management of credentials, and a consistent, secure framework for application authentication.

 

With the proliferation of Cisco Unified Communications (UC) products, services and end-user applications, pervasive SSO support has become an important baseline across the Cisco Collaboration portfolio, allowing users to easily and securely access multiple UC capabilities without the headache of remembering multiple credentials or re-entering passwords each time they access UC features like Cisco Jabber, Unity Connection voicemail, or the Unified Communications Manager 'Self Help Portal'.  This SSO login functionality has now been extended to several UC application interfaces, allowing developers to incorporate SSO seamlessly into their applications.

 

SSO Tokens

 

For applications implementing SSO support, one of the first steps is to initiate the single-sign on process (usually via a web browser or webview control).  During this process the web browser accesses the SSO Identity Provider service and the UC Manager or Unity Connection server, and prompts the user to sign in.  The end result generates a SSO 'token', which can then be used by the application to authenticate subsequent API requests.  This token can be used with any of the SSO-enabled APIs without prompting the user for a login.

 

For additional details on obtaining a UC Manager or Unity Connection SSO token, including browser-based sample application code, please see this tutorial: https://developer.cisco.com/site/sso/

 

Webex provides flexible SSO capabilities, for more details on the various possible SSO configurations and authentication flows, see the resources available here: https://developer.cisco.com/site/webex-developer/develop-test/sso/overview/

 

SSO Enabled Products and APIs

 

Cisco Unified Communications Manager v10.5+

 

Cisco UC Manager provides SAML/OAuth integration with various industry leading SSO Identity Providers, including OpenAM, Microsoft Active Directory Federation Services, Ping Identity, and Oracle Identity Manager.  Administrators and end-users can use SSO to login to the UC Manager web user interfaces, while voice/video endpoints like Jabber also leverage SSO for authentication.  In addition to these standard features, several UC Manager APIs now support SSO: TAPI, JTAPI, WebDialer SOAP, and UDS.

 

TAPI - The Cisco TAPI Telephony Service Provier (TSP) can now be installed on the user's PC with SSO support enabled.  The Cisco TSP will automatically open a browser instance to allow the user to login via the Identity Provider.  All authentication tasks are handled by the TSP, and applications do not need to do anything to benefit from SSO.  For more details see the UC Manager Release Notes

 

JTAPI - JTAPI provides support for SSO by introducing a new login parameter 'ssoauthtoken' in the getProvider() request, which can be supplied instead of a username/password combination:

 

//application gets SSOoAuthToken
String oAuthToken = tokenFetchedByApp;
//Create provider string in the required format
String providerString = ctiserverIP + “;ssooauthtoken=” + oAuthToken +”;;
JtapiPeer peer = JtapiPeerFactory.getJtapiPeer ( null );
try {
         Provider provider = peer.getProvider (providerString);
} catch (Exception exp ){
//Exception handling code
}

 

For more details on JTAPI SSO support, including details on obtaining an SSO token, please see the UC Manager  Release Notes

 

WebDialer - The WebDialer HTML interface, which enables simple embedding of UC Manager click-to-dial functionality into web applications, now natively supports SSO - no application changes required.  The WebDialer SOAP interface also supports SSO via introduction of a new 'token' element in the request:

<in0 xsi:type="urn:Credential">
   <token xsi:type="xsd:string">MjpjMTAzNDk4NC00ZjhhLTQzMTMtYjdlNS0xMTI2MDgzNzNlZDg</token>
</in0>

 

For more details on WebDialer SSO support, please see the WebDialer Dev Center: https://developer.cisco.com/site/webdialer/webdialer/authentication/

 

UDS - The User Data Service API allows end-user applications to access and update UC Manager settings and configurations (like speed-dials or call-forwarding) via a cross-platform REST interface.  UDS requests can authenticate by providing an SSO token in a 'bearer mode' HTTP Authentication header:

 

UDSsample.png

 

For more details on UDS SSO support, including sample code for browser-based applications, please see the UDS Dev Center: https://developer.cisco.com/site/user-data-services/overview/authentication/

 

Cisco Unity Connection 10.5+

 

Cisco Unity Connection REST-based APIs for accessing and managing voicemail details - including the '/vmrest' APIs: Cisco Unity Messaging Interface (CUMI), Cisco Unity Telephony Interface (CUTI), Cisco Unity Connection Imaging Interface (CUII), Cisco Unity Provisioning Interface (CUPI) - also support SAML/OAuth SSO in conjunction with UC Manager.

 

These APIs can authenticate by providing an SSO token in a 'bearer mode' HTTP Authentication header:

UDSsample.png

Cisco Webex Meetings

 

Cisco Webex is a cloud-based online collaboration service, offering group video conferencing, HD quality audio conferencing, screen-sharing, co-browsing and much more.  Applications can integrate to the Webex cloud via an HTTP/XML API to automate admin-level tasks - such as user provisioning, access control, and feature enablement - as well as end-user interactions such as listing meetings, scheduling new meetings, and launching/managing meeting controls in real time.

 

Once the application has obtained the Webex SSO session ticket, XML API requests can be made by providing the ticket in place of the password:

<?xml version="1.0" encoding="UTF-8"?>
<serv:message xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:serv="http://www.webex.com/schemas/2002/06/service">
  <header>
    <securityContext>
      <webExID/>
      <sessionTicket/>
      <siteID/>
      <partnerID/>
    </securityContext>
  </header>
  <body>
    <bodyContent xmlns:meet="http://www.webex.com/schemas/2002/06/service/meeting" xsi:type="java:com.webex.service.binding.meeting.LstsummaryMeeting">
      <listControl>
        <startFrom/>
        <maximumNum>5</maximumNum>
      </listControl>
      <order>
        <orderBy>STARTTIME</orderBy>
      </order>
      <dateScope></dateScope>
    </bodyContent>
  </body>
</serv:message>

The Cisco Unified Communications Vision

 

Cisco's vision of pervasive, secure, high-performance collaboration capabilities, tightly integrated into whatever devices and applications the user has at hand, is growing quickly.  Enabling developers to seamlessly integrate these capabilities via SSO-capable APIs is a key part of the vision, and we look forward to seeing what partners and customers can create!

 

Learn More

 

For documents, samples, online Sandbox labs, forums and support regarding the above APIs and products, please visit http://developer.cisco.com

 

Also, don't miss the 'Cisco Unified Communications Single Sign-On for Developers' classroom session at Cisco Live! Milan in the DevNetZone for live, hands-on code walk-throughs of Cisco UC SSO APIs.