Imagine sitting in an interview room with a bunch of techies, firing questions at you, assessing you, sizing you up and you walking in with confidence and trepidation knowing fully well you really want the job but also that you are really good at what you do, but somehow things are not going quite well as you would want or envisage and then in the midst of all the pandemonium and barrage of questions, you hear these words: "Do you know how OAuth works"??
And you bet, my ears felt like ( did I just hear that) and in my head I am like "O what?"
If you want to know the result of that interview you would have to stay with me till the very end...But for now lets get into the matter of OAuth.
OAuth is simply an Authorization protocol defined by RFC 6749. OAuth allows an end user ( like me) to authorize an application (like Jabber) to gain access to a third party service ( like CUCM) without sharing their credentials with the application.
OAuth is becoming the defacto authorization protocol within UC collaboration solutions and vendors like Cisco and Microsoft have deployed it within their solution stacks. Some UC solutions deploying or requiring OAuth are
OAuth is an authorization framework specification that comprises of different components. The diagram below gives the components used within the Cisco Oauth deployment.
The diagram below shows the Oauth architecture used within CUCM and the interactions between the end user and various components in the Oauth deployment
CUCM uses tokens to authorize access to resources once user has been successfully authenticated. Depending on the CUCM version and the Oauth grant flow model used, CUCM uses either
The process of Authentication involves a user confirming their identity and approving what information can be accessed. Once the user has been successfully authenticated, access token is issued to the 3rd party using OAuth by the authorization server. Cisco implementation offers two tokens that will be issued for authorizing access to resources
OAuth supports multiple grant flows however CUCM deployment supports the following:
|CUCM Version||OAuth Flow model||Authentication method||Tokens issued|
|10.5 <= cucm-version < 11.5.1(SU3)||Implicit Flow||SAML SSO only||access token|
|>= 11.5.1(SU3)||Authorization code grant flow||Local user, LDAP and SAML SSO||access token, refresh token|
CUCM OAuth server generates a set of encryption and signing keys used for signing and encrypting OAuth tokens. These keys are automatically distributed within Unified CM clusters to call control and IM and presence nodes. Unity connection and Expressway-C servers are also able to fetch encryption and signing keys using a REST API.
The signing/encryption key set is used to validate/decrypt tokens presented by jabber clients when authorization to a resource is requested
OAuth provides several benefits to both end users and UC administrators. Some of these benefits are highlighted below:
The recommended and supported versions for OAuth are shown below:
To enable OAuth perform the following procedure
1. Go to Cisco Unified Communications Manager Admin > System > Enterprise Parameters > SSO and OAuth Configuration and
"Select OAuth with Refresh Login Flow" set Enable support OAuth feature. ( adjust timers if desired)
NB: There is no configuration change required on IM&P nodes. CUCM will automatically push this settings to all the IM&P nodes in the cluster.
There is an exception to this and that is when centralized IM&P cluster is deployed. Additional configuration is required on the IM&P cluster to fetch the OAuth token keys from the CUCM clusters
Two steps are required to enable unity connection for OAuth:
To obtain the signing and encryption keys Unity must be configured with the Unified CM host details and a user account enabled for Unified CM AXL access
Go to AuthZ Servers > Add New
Now that the theory is explained and understood we now take a deep dive into the inner workings of OAuth in MRA deployment.
The selected trace analysis was taking while troubleshooting an issue with OAuth login flow and I thought it might provide an excellent source of learning. Sit tight, here we go....
++ Summary of Issue ++
After enabling OAuth on CUCM and Expressway-C, users attempted to login, got the CUCM browser page ( shown in step 4 of the architecture diagram), entered in user credentials but got "unable to communicate with server"
For all who are familiar with the Jabber MRA call flow, the first request that jabber sends ( after _collabe-edge SRV lookup) used to be "get_edge_config" However to support OAuth flow, the first request that jabber sends now is
The next few lines we will detail the requests and responses used in OAuth flow with Jabber
++ Expressway-E receives the request ++
2020-03-24T16:31:00.962-06:00 labucexpye01 traffic_server: UTCTime="2020-03-24 22:31:00,962" Module="network.http.trafficserver" Level="INFO": Detail="Receive Request" Txn-id="2004" Src-ip="18.104.22.168" Src-port="59252" Msg="GET https:///Ym91bGRlcm1lZGljYWxjZW50ZXIuY29temail@example.com HTTP/1.1"
++ Expwe-responds with 200 OK With Token-reuse set to True ( NB: Request is forwarded to ExpwC and C sends to CUCM and CUCM responds based on the Refresh login configuration ++
2020-03-24T16:31:00.963-06:00 labucexpye01 traffic_server: UTCTime="2020-03-24 22:31:00,962" Module="network.http.trafficserver" Level="DEBUG": Detail="Sending response" Response-code="200" Txn-id="2004" Dst-ip="22.214.171.124" Dst-port="59252"
++ Once Token re-use is set to True, Expressway-E will then presents Jabber with a login form ( via the built in web browser)
Once the user has entered all the login details, Jabber sends an Authorize Response with the client ID to be used for the authentication++
++ Jabber confirms Token reuse is enabled ++
2020-03-24 22:31:00,442 INFO [0x00002b04] [rvices\impl\system\SingleSignOn.cpp(206)] [Single-Sign-On-Logger] [CSFUnified::SingleSignOn::Impl::isAuthenticatorTokenReuseEnabled] - TokenReuse enabled for 1001
++ Jabber states that services needs authorization and we need credentials for authentication ++
2020-03-24 22:31:00,442 INFO [0x00002b04] [\impl\system\UserProfileManager.cpp(153)] [UserProfileManager] [CSFUnified::UserProfileManager::Impl::getCredentialsForAuthenticator] - for authenticator: 1001
++ Jabber sends authorization response with client id++
2020-03-24 22:31:00,442 DEBUG [0x00002b04] [bwindowplugin\browsercontroller.cpp(167)] [PluginUtils]
[BrowserController::NavigateTo] - Enter - url = https://labucexpwye01.bouldermedicalcenter.com:8443/Ym91bGRlcm1lZGljYWxjZW50ZXIuY29t/authorize?response_type=code&realm=local&client_id=C1b4b988f3efa1c3fc97d0d0a36f6b97f244b4fafe55e8d9d7
++ Expressway-E recieves the the Authorization response ++
2020-03-24T16:31:01.569-06:00 labucexpye01 traffic_server: UTCTime="2020-03-24 22:31:01,569"
Module="network.http.trafficserver" Level="INFO": Detail="Receive Request" Txn-id="2005" Src-ip="126.96.36.199"
Src-port="59254" Msg="GET https:///Ym91bGRlcm1lZGljYWxjZW50ZXIuY29t/authorize?response_type=code&realm=local&client_id=C1b4b988f3efa1c3fc97d0d0a36f6b97f244b4fafe55e8d9d78774
++ Next Jabber sends Authentication request with client_id established earlier ++
"POST https:///Ym91bGRlcm1lZGljYWxjZW50ZXIuY29t/localauthentication HTTP/1.1"
+++ Next Jabber sends a POST request for local authentication with its client_id++
2020-03-24T16:31:22.729-06:00 labucexpye01 traffic_server: UTCTime="2020-03-24 22:31:22,729"
Module="network.http.trafficserver" Level="INFO": Detail="Receive Request" Txn-id="2007" Src-ip="188.8.131.52"
Src-port="59254" Msg="POST https:///Ym91bGRlcm1lZGljYWxjZW50ZXIuY29t/localauthentication HTTP/1.1"
Module="network.http.trafficserver" Level="DEBUG": Detail="Receive Request" Txn-id="2007" Src-ip="184.108.40.206" Src-port="59254"
+++ Next Expressway-E sends POST request to C +++
+++ Expressway-C receives the request +++
2020-03-24T16:31:22.739-06:00 labucexpyc01 traffic_server: UTCTime="2020-03-24 22:31:22,739" Module="network.http.trafficserver" Level="INFO": Detail="Receive Request" Txn-id="6114" Src-ip="127.0.0.1"
Src-port="33688" Last-via-addr="10.10.1.44" Msg="POST http://vcs_control.lab.com:8443/Ym91bGRlcm1lZGljYWxjZW50ZXIuY29t/localauthentication HTTP/1.1"
+++ Expressway-C will do two things here
+++ Now Jabber will send a POST request to get access_token and will embed the following information in the POST request +++
1. authorization code
2020-03-24T16:31:23.789-06:00 labucexpyc01 edgeconfigprovisioning UTCTime="2020-03-24 22:31:23,789" Module="network.http.sso.server" Level="DEBUG" Action="Send"
+++ CUCM responds with 200 OK containing +++
OAuth process is now complete and Jabber will then start the normal service requests process but rather than using user credentials, will use the authorization header which will contain the access_token that has been obtained.
++ get_edge_config with Authorization header and access_token embedded ++
++ Back to the issue +++
Now that we understand the flow and we can see that the OAuth flow successfully completes, we now focus on why the client still could not login. For this we need to turn to Jabber PRT logs,
From the Jabber logs, here is what I see:
+++ 2020-03-31 12:12:54,998 ERROR [0x000006c8] [rwerx\jwcpp\xmppcore\src\client.cpp(192)] [csf.jwcpp] [gloox::Client::handleNormalNode] - @XmppSDK: #0, The server doesn't offer any SASL authentication mechanism that we can support
++ Jabber says that there is no Simple Authentication and Security Layer (SASL) authentication mechanism it can support ++
Questions is why? We have already established that Jabber is going to use OAuth for this session and has successfully obtained the required tokens. So what is going on.??
To understand what is going on, we need to know that Jabber needs to know the supported SASL authentication mechanism in the XMPP features advertised by Expressway-C. This in-turn depends on the advertised SASL authentication supported by IM&P server. So the next logical place to go is to find what SASL mechanism is advertised by both IM&P and Expressway-C
1. ++ Expressway-C request to get supported sasl mechanism supported by IM&P ++
NB: OAUTHBEARER ( is included in the SASL mechanism supported. This is required for OAuth to work)
The issue turns out that even though OAuth was enabled and the first stage of obtaining OAuth tokens was successful, expressway-C configuration was stuck on OAuth not been enabled:
Looking at the xconfiguration API of expressway-C we saw "OAuthLocal:off" This should be on.
A reboot of the server fixed the issue:
This is the correct configuration
1. Some quick thing to check when having issues, verify the keys on all servers in the cluster
2. Refresh servers in Expressway-C to ensure that expressway has the keys to validate access tokens from CUCM
This was a long one, I guess by now you know I do not do short articles/blogs. I guess the complexities of some of these solutions cant easily be written. OAuth is a great solution, I encourage you deploy it for your customers.
As for my job interview, lets just say that I am still looking for a job. If you know someone or your team needs a good guy like myself. Please reach out to me.