This document describes how Authorization Code Grant flow is based on refresh token (extendible to End Points/Other Collaboration Apps) in order to improve Jabber User Experience across various devices, especially for Jabber on Mobile.
Cisco recommends that you have knowledge of these topics:
Cisco Unified Communications Manager (CUCM) 12.0 version
Single Sign On (SSO)/SAML
Identity Provider (IdP)
In order to get more information on these topics, refer these URL's:
SAML SSO Deployment Guide for Cisco Unified Communications:
The information in this document is based on these software:
Microsoft ADFS ( IdP)
LDAP Active Directory
Cisco Jabber Client
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, make sure that you understand the potential impact of any command.
As of today, Jabber SSO flow with Infrastructure is based on Implicit Grant Flow where CUCM Authz service allocates the short lived access tokens.
Post access token expiry, CUCM redirects Jabber to IdP for re-authentication.
This leads to bad user experience especially with jabber on mobile where user is asked to enter credentials frequently.
Security Re-architecture Solution also proposes Authorization Code Grant Flow (with the use of Refresh Tokens approach) for unification of Jabber and End Point log in flow for both SSO and Non SSO scenarios.
Authorization Code Grant flow is based on refresh token (extendible to End Points/Other Collaboration Apps) in order to improve Jabber User Experience across various devices, especially for Jabber on Mobile.
Supports Self Contained Signed and Encrypted OAuth Tokens to allow various collaboration applications to validate and respond to client resource requests.
The implicit grant flow model is retained which allows backwards compatibility. This also allows a seamless path for other clients (like RTMT) who have not moved to Authorization Code Grant flow.
Implementation such that old jabber client can work with new CUCM (since it supports both implicit grant and authorization code grant flows). Also, new jabber can work with old CUCM. Jabber can determine if CUCM supports Authorization Code Grant flow and only if it supports this model, it switches else uses implicit grant flow.
AuthZ is a service running on CUCM.
AuthZ supports only Implicit Grant Flow. This means there was no refresh token/offline access token. Each time client wanted a new Access token, user needs to re-authenticate with the IdP.
Access Tokens were issued only if your deployment is SSO enabled. Non-SSO deployments didn’t work in this case and access Tokens were not used on all interfaces consistently.
Access Tokens are not self-contained, but rather retained in memory of the server that issued it. If CUCM1 issued the access token, it can be verified only by CUCM1. If the client tries to access service on CUCM2, CUCM2 needs to validate that token on CUCM1. Network delays (proxy mode).
User experience on mobile clients is very bad since user has to re-enter credentials on an alpha-numeric keypad when user re-authenticate with the IdP (typically running from 1 hour to 8 hours which depends on several factors).
Clients that speak to multiple applications over multiple interfaces need to maintain multiple credentials/blocks. No seamless support for same user log in from 2 similar clients. E.g. User A log in from jabber instances that runs on 2 different iPhones.
AuthZ to support both SSO and Non-SSO deployments.
AuthZ to support implicit grant flow + authorization code grant flow. Being backward compatible allows clients like RTMT to continue work until they adapt.
With Authorization code grant flow, AuthZ issues access token and refresh token. Refresh token can be used to get another access token without the need for authentication.
Access Tokens are self-contained, signed and encrypted and use the JWT (JSON web tokens) standard (RFC compliant).
Signing and encryption keys are common to the cluster. Any server in the cluster can verify the access token. There is no need to maintain in memory.
AuthZ service that runs on CUCM 12.0 is the centralized Authentication Server in the cluster.
Refresh tokens are stored in Database (DB). Admin needs to be able to revoke it, if required. Revocation is based on userid or userid & clientID.
Signed access tokens allows different products to validate access token without the need to store them. Configurable access token and refresh token lifetimes (default 1 hour and 60 days respectively).
JWT format is aligned with Spark which allows synergies in the future with Spark Hybrid services.
Support for same user log in from 2 similar devices. Eg: User A can log in from jabber instances that runs on 2 different iphones.
Elements of Authorization Code Grant Flow
Auth Z Server
This feature is not enabled by default.
Step 1. In order to enable this feature, navigate to System > Enterprise Parameters.
Step 2. Set the param OAuth with Refresh Login Flow to Enabled as shown in the image.
Access token is signed and encrypted. Signing and encryption key is common to the cluster. This means any node in the cluster can validate the access token.
Access token is in JWT format (RFC 7519).
Access tokens re-use enterprise parameter (OAuth Access Token Expiry timer), which is applicable for both old token and new token formats.
Default value - 60 Mins.
Minimum Value - 1 Mins
Maximum Value - 1440 Mins
OAuth Refresh Token Expiry Timer” parameter in enterprise parameters page in CUCM.
Path: System -> Enterprise parameters
Values are integers ranging from 1 – 90
Minimum lifetime = 1 Day
Default lifetime = 60 days
Maximum lifetime = 90 days
New access token is issued each time client requests for one. Old one continues to be valid as long as:
Signing/Encryption keys have not changed
Validity (stored inside the token) breaks.
JSON web-tokens: consist of three parts, separated by dots, which are: Header, Payload & Signature.
Sample access token:
At the start of the token that is highlighted in bold is the Header.
Middle part is the Payload.
At the end, if the token is highlighted in bold then it is the Signature.
Here is a high level overview of the call flow involved:
Refresh token are signed.
Refresh token is stored in refreshtokendetails table in the database as a hash value of itself. This is to prevent replication by DB as it can be picked by someone.
Table includes the columns as shown in the image.
Warning: Refresh token is flushed from DB when the validity is expired. Timer thread runs at 2 am everyday (not configurable via UI, but can be modified via remote support account). If the table has a large number of access tokens, that are invalid and need to be flushed out. This can cause a CPU spike.
Signing key is RSA based, who has public/private key pair.
Encryption key is a symmetric key.
These keys are created only on the publisher and are distributed across all the nodes in the cluster.
Both the signing key and encryption key can be re-generated, with the use of the options listed. However, this must be done only if the administrator believes that the keys have been compromised. The impact of the re-generation of either of these keys is that all the access tokens issued by AuthZ service becomes invalid.
Signing keys can be re-generated with UI and CLI.
Encryption keys can be regenerated only with CLI.
The regeneration of Authz certs (signing key) from Cisco Unified OS Administration page on CUCM is as shown in the image.
The regeneration of Authz signing key with the use of CLI command is as shown in the image.
Admin can display authz signing and encryption keys with the use of CLI. Hash of the key is displayed rather than original key.
Command to display keys are:
Signing Key: show key authz signing and as shown in the image.
Encryption Key: show key authz encryption and as shown in the image.
There is currently no verification procedure available for this configuration.
This section provides information you can use in order to troubleshoot your configuration.
The sso app logs are generated in these locations:
/var/log/active/platform/log/ssoApp.log This does not require any trace configuration for log collection. Every time SSO App operation is done, a new log entries are generated in ssoApp.log file.
SSOSP logs are located at /usr/local/thirdparty/Jakarta-tomcat/logs/ssosp/log4j/.
Every time sso is enabled, a new log file is created at this location with name, ssosp00XXX.log. Any other SSO operation and all Oauth operations are also logged into this file.
Certificate logs are located at /var/log/active/platform/log/certMgmt*.log.
Everytime AuthZ certificate is regenerated (UI or CLI), a new log file is generated for this event.
For authz encryption key re-generation, a new log file is generated for this event.