|
Cisco AJAX XMPP Library |
The Cisco AJAX XMPP Library is a JavaScript XMPP client library that allows you to integrate instant messaging, availability and roster management services from Cisco WebEx and Cisco Unified Presence to your web-based application.
However if integrating with Cisco Unified Presence, then there are specific configuration steps that need to be performed to ensure that Cisco AJAX XMPP Library based clients interact correctly with Cisco Unified Presence.
The following sections describe the configuration required:
Cisco Unified Presence provides for a multi-node/multi-cluster deployment. This feature permits the deployment of a number of Cisco Unified Presence clusters
where each Cisco Unified Presence cluster can consist of up to six Cisco Unified Presence nodes. Cisco Unified Presence nodes within a cluster can form a
subcluster. A subcluster is a single Cisco Unified Presence server, or a pair of Cisco Unified Presence servers operating with a shared presence database
that is able to support common users.
In a single-node deployment within the subcluster, there is no high-availability failover protection for the users assigned to that node. In a dual-node deployment
within a subcluster the system administrator can enable high-availability failover protection. Users assigned to a subcluster with the high-availability mode enabled
have redundancy and full failover capabilities as each node acts as a backup for the other node allowing clients to fail over in case of outages of components or nodes.
CAXL supports the Cisco Unified Presence multi-node/multi-cluster deployment model allowing a single CAXL-based application to be deployed that facilitates a user from any node or cluster (assuming that the clusters are on the same domain) to access their assigned Cisco Unified Presence node. This support includes the high-availability failover protection provided by an enabled dual-node deployment within a subcluster. In such deployments a user can have two associated Cisco Unified Presence nodes:
CAXL internally determines both home & backup nodes for a connected user using a discovery mechanism (XEP-0233), henceforth referred to as Service Discovery. Service Discovery requires that CAXL is configured with two Service Discovery (SD) nodes:
The Service Discovery mechanism on Cisco Unified Presence operates across a Cisco Unified Presence multi-cluster deployment. This means that a service discovery node in one cluster can provide home and backup node information for a user that exists in a different Cisco Unified Presence cluster. This allows users existing on different Cisco Unified Presence clusters to use a single CAXL-based client, as Service Discovery can determine a user's home & backup node across clusters.
Note: Unless load considerations dedicate otherwise, the Primary & Secondary SD nodes do not need to be in a standalone cluster nor does their only function need to be Service Discovery. It may be the case that the SD nodes exist within any cluster within the given deployment and can also be either a user's home or backup node.
The Cisco AJAX XMPP Library Deployment Guide provides information on an alternative approach to using the HTTP Proxy
to overcome the same-origin security policy issue. Cross Origin Resource Sharing (CORS) is a standard that allows requests made by a web page from one origin (host + port)
to make requests to other origins. Support for the CORS standard is implemented by a number of browsers and by Cisco Unified Presence. Therefore CAXL-based clients connecting
to Cisco Unified Presence using one of the supported browsers (See Cisco AJAX XMPP Library Deployment Guide - Cross origin policy)
can do so without the need for a HTTP Proxy. In these circumstances the configured Primary & Secondary SD node values can be specified as the resolvable BOSH URLs of the Cisco
Unified Presence servers acting as the Primary & Secondary SD nodes.
Note: There are some limitations to be considered if using HTTPS as the protocol to connect to Cisco Unified Presence
server. Please refer to Limitations
for HTTPS CORS Configuration.
//################
// Set globally
//################
// Ensure that CAXL's service discovery support is enabled
jabberwerx._config.serviceDiscoveryEnabled = true;
// When using CORS the primary SD node is specified as the resolvable BOSH URL of
// the Cisco Unified Presence server acting as the primary Service Discovery node
jabberwerx._config.httpBindingURL = "https://node-sd1.example.com:7335/httpbinding";
// When using CORS the secondary SD node is specified as the resolvable BOSH URL of
// the Cisco Unified Presence server acting as the secondary Service Discovery node
jabberwerx._config.httpBindingURL_secondary = "https://node-sd2.example.com:7335/httpbinding";
//##########################################
// Set by passing arguments to the client
//##########################################
var connectArgs = {
httpBindingURL = "https://node-sd1.example.com:7335/httpbinding",
httpBindingURL_secondary = "https://node-sd2.example.com:7335/httpbinding",
serviceDiscoveryEnabled = true
};
var client = jabberwerx.Client();
client.connect(userJid, password, connectArgs);
Note:
// A home node value can be either a hostname, an FQDN or an IPv4 address
// The backup node URL is constructed in the same manner
// home node value is a hostname
Primary SD node BOSH URL ==> "http(s)://primarySDNode:7335/httpbinding"
A user's home node value ==> "cupNodeA"
CAXL internally constructed home node BOSH URL for the connecting user ==> "http(s)://cupNodeA:7335/httpbinding"
// home node value is a FQDN
Primary SD node BOSH URL ==> "http(s)://primarySDNode.example.com:7335/httpbinding"
A user's home node value ==> "cupNodeA.example.com"
CAXL internally constructed home node BOSH URL for the connecting user ==> "http(s)://cupNodeA.example.com:7335/httpbinding"
// home node value is an IP address
Primary SD node BOSH URL ==> "http(s)://127.0.0.1:7335/httpbinding"
A user's home node value ==> "127.0.0.2"
CAXL internally constructed home node BOSH URL for the connecting user ==> "http(s)://127.0.0.2:7335/httpbinding"
// The backup node URL is constructed in the same manner
Primary SD node BOSH URL (attested FQDN URL) ==> "https://primarySDNode.example.com:7335/httpbinding"
A user's home node value ==> "cupNodeA" or "cupNodeA.example.com"
CAXL internally constructed home node BOSH URL for the connecting user (attested FQDN URL) ==> "https://cupNodeA.example.com:7335/httpbinding"
As mentioned in the Cisco AJAX XMPP Library Deployment Guide, browsers apply a same-origin security policy, which will prevent a CAXL-based web application from directly accessing the Cisco Unified Presence server. One workaround to resolve this issue is to create a HTTP Proxy on your web server to proxy all BOSH requests from the CAXL client to the Cisco Unified Presence server. The Cisco AJAX XMPP Library Deployment Guide provides the details on configuring the HTTP Proxy on your web server. In order for CAXL to support the Cisco Unified Presence multi-node/multi-cluster deployment model you must specify the reverse proxy URLs on your web server in the correct format. The reverse proxy URL must map the Cisco Unified Presence server node name to the complete BOSH URL for that Cisco Unified Presence server. A reverse proxy URL must exist for each Cisco Unified Presence server that exists in the deployment.
For example, add the following entries to the main Apache config file httpd.conf:
# Reverse proxy URL format: /{cup-node-name} {resolvable BOSH URL}
# Maps 'node-a1' to its resolvable BOSH URL 'https://node-a1.example.com:7335/httpbinding'
ProxyPass /node-a1 https://node-a1.example.com:7335/httpbinding
# Maps 'node-b1' to its complete BOSH URL 'https://node-b1.example.com:7335/httpbinding'
ProxyPass /node-b1 https://node-b1.example.com:7335/httpbinding
//################
// Set globally
//################
// Ensure that CAXL's service discovery support is enabled
jabberwerx._config.serviceDiscoveryEnabled = true;
// '/node-sd1' is the primary Service Discovery node for providing user's home & backup node information.
// 'node-sd1' must match the node name for the Cisco Unified Presence server acting as the primary Service Discovery node
// A reverse proxy URL must exist in the HTTP Proxy config file for 'node-sd1'
jabberwerx._config.httpBindingURL = "/node-sd1";
// '/node-sd2' is the secondary Service Discovery node for providing user's home & backup node information
// which CAXL uses should the primary SD node be unavailable
// 'node-sd2' must match the node name for the Cisco Unified Presence server acting as the secondary Service Discovery node
// A reverse proxy URL must exist in the HTTP Proxy config file for the 'node-sd2'
jabberwerx._config.httpBindingURL_secondary = "/node-sd2";
//##########################################
// Set by passing arguments to the client
//##########################################
var connectArgs = {
httpBindingURL = "/node-sd1",
httpBindingURL_secondary = "/node-sd2",
serviceDiscoveryEnabled = true
};
var client = jabberwerx.Client();
client.connect(userJid, password, connectArgs);
Backwards Compatibility:
Previous CAXL versions did not require that the http binding URL must match the Cisco Unified Presence server node name. These versions supported
a modifiable http binding URL (default value = '/httpbinding') that allowed CAXL-based clients to connect to a single Cisco Unified Presence server.
The current CAXL version is backwards compatible with this behavior. The system administrator can deploy a CAXL-based client connecting to a single
Cisco Unified Presence server where the configured http binding URL does not match the Cisco Unified Presence server node name. In such a deployment
the CAXL configuration flag serviceDiscoveryEnabled must be set to false. By doing so CAXL's service discovery support is disabled and hence,
the CAXL-based client will not support the Cisco Unified Presence multi-node/multi-cluster deployement model.
//################
// Set globally
//################
// Disable CAXL's service discovery support
jabberwerx._config.serviceDiscoveryEnabled = false;
// http binding URL does not match the Cisco Unified Presence server node name
jabberwerx._config.httpBindingURL = "/httpbinding";
//##########################################
// Set by passing arguments to the client
//##########################################
var connectArgs = {
httpBindingURL = "/httpbinding",
httpBindingURL_secondary = "/httpbinding",
serviceDiscoveryEnabled = false
};
var client = jabberwerx.Client();
client.connect(userJid, password, connectArgs);
# HTTP Proxy Config
# Reverse proxy URL is no longer required to map the Cisco Unified Presence server node name to the complete BOSH URL
# Reverse proxy URL must map the configured default http binding URL to the desired Cisco Unified Presence server BOSH URL
ProxyPass /httpbinding https://node-a1.example.com:7335/httpbinding
Note: If serviceDiscoveryEnabled configuration flag is true:
CAXL supports the Cisco Unified Presence multi-node/multi-cluster deployment model allowing a single CAXL-based application to be deployed that facilitates a user from any node or cluster to access their assigned Cisco Unified Presence node. This support requires that CAXL persists a user's home and backup node information client-side using the browsers storage mechanism. CAXL utilises jStore (ver 1.2.0) to persist information to browser storage. All the CAXL supported browsers (except Internet Explorer 7) use jStore's Local Storage mechanism, allowing CAXL to seemlessly persist the node values. Internet Explorer 7 utilises jStore's Flash Storage Engine to persist the node values, hence it must have Adobe Flash Player installed for CAXL to function correctly. Please see Adobe for details on installing Adobe Flash Player.
As described in the Cisco AJAX XMPP Library Deployment Guide, a common deployment scenario for deploying the Cisco AJAX XMPP Library is to set up a HTTP proxy on a web server, which proxies all BOSH requests from the Cisco AJAX XMPP Library to the Cisco Unified Presence server. Please refer to the Cisco AJAX XMPP Library Deployment Guide for further details as to why a HTTP Proxy is required.
It is important to be aware of the security configuration that is required by Cisco Unified Presence on the front-end. In this case, the front-end refers to the connection between the browser and the HTTP proxy server and NOT the connection between the HTTP Proxy and the Cisco Unified Presence server. Cisco AJAX XMPP Library based clients that connect to a Cisco Unified Presence server use plaintext authentication.
If the HTTP Proxy server is set up to use HTTPS, then no action is required to enable the Cisco AJAX XMPP Library based client to connect successfully to the Cisco Unified Presence server. If the HTTP Proxy server is set up to use HTTP, then the Cisco AJAX XMPP Library "unsecureAllowed" flag must be set to be true, which permits plaintext authentication over an unencrypted or unsecured HTTP channel.
To set/modify any of the Cisco AJAX XMPP Library configuration options, create an object called "jabberwerx_config" in the global namespace. To set the unsecureAllowed flag, create the jabberwerx_config object in the global namespace and set unsecureAllowed to the desired value.
// Create jabberwerx_config object in the global namespace
jabberwerx_config = {
// Set the unsecureAllowed flag to be true
unsecureAllowed: true
};
A number of the Cisco AJAX XMPP Library configuration options can be set together as follows:
// Create jabberwerx_config object in the global namespace
jabberwerx_config = {
persistDuration: 30,
unsecureAllowed: true,
capabilityFeatures: ['http://jabber.org/protocol/caps',
'http://jabber.org/protocol/chatstates',
'http://jabber.org/protocol/disco#info',
'http://jabber.org/protocol/muc',
'http://jabber.org/protocol/muc#user'],
capabilityIdentity: {
category: 'client',
type: 'pc',
name: 'Cisco AJAX XMPP Library',
node: 'http://jabber.cisco.com/caxl'},
baseReconnectCountdown: 30,
enabledMechanisms: ["DIGEST-MD5", "PLAIN"]
};
For further information please refer to the Cisco AJAX AMPP Library API.
Back to the top
As part of the default configuration for Cisco Unified Presence, the BOSH interface is enabled for HTTPS communication. This can however be configured to use non-secure HTTP.
Enabling HTTP via the BOSH interface can be performed as follows:
By default, when a contact is added or updated using the RosterController, their group attribute is empty (i.e. they have no group). Some clients will not display contacts without a group attribute. Therefore, a property is defined in the RosterController class to facilitate the situation where a client using Cisco AJAX AMPP Library will always want contacts added or updated to be members of a group. This property is jabberwerx.RosterController.defaultGroup.
To set the default group name:
// Create a jabberwerx client instance
var client = new jabberwerx.Client('Demo Client');
// Create a jabberwerx roster controller
var rosterCtrl = new jabberwerx.RosterController(client);
// Set the default group name for this roster
rosterCtrl.defaultGroup = "General";
This property will take affect when an add or update contact call is made without a group
parameter, or where the group parameter is null or empty.
Note: This is not the same as the default grouping name in jabberwerx.ui.RosterView. The RosterView default group name refers to the group display name for entities that belong to no group (i.e. contacts with an empty group attribute). This is purely a visual setting.
Back to the topAny Cisco client that connects to Cisco Unified Presence is expected to remove contacts from their roster in a consistent manner. In order to maintain a consistent functionality across all Cisco Unified Presence clients, clients should first unsubscribe to a contact (See RFC3921, Section 8.4. "Unsubscribing") as opposed to performing a roster remove (See RFC3921, Section 8.6. "Removing a Roster Item and Cancelling All Subscriptions").
If a client performs a roster remove, this removes the subscription in both directions, specifically the user's subscription to their contact is removed and the contact's subscription to the user is removed. The desired approach is for the user to unsubscribe to the contact. This removes the user's subscription to their contact but the contact's subscription to the user is preserved.
To remove a roster contact using unsubscribe:
// Previously triggered event that contains session information
var session = evt.data.content.session;
if (session) {
// Get the current entity
var entity = session.getEntity();
if (entity instanceof jabberwerx.Contact) {
// Calls jabberwerx.RosterController.unsubscribe
entity.controller.unsubscribe(entity.jid);
}
}
The above behavior only occurs if the setting for automatic authorisation is enabled on Cisco Unified Presence. In the event that this is disabled on Cisco Unified Presence, further Cisco AJAX AMPP Library configuration steps will need to be performed. To check if automatic authorization is enabled on the Cisco Unified Presence, sign in to Cisco Unified Presence Administration, and navigate to Presence > Settings, and confirm that the setting "Allow users to view the availability of other users without being prompted for approval" is checked.
If automatic authorization is disabled on Cisco Unified Presence, an unsubscribe is sent to the contact to be removed. This triggers a roster remove, which removes the subscription in both directions. To prevent this, set the following Cisco AJAX AMPP Library configuration items:
// Set autoSubscription to true
// Default value is true, so this step may not be required
rosterCtrl.autoSubscription = true;
// Set autoremove to false. JabberWerx AJAX will not automatically remove the roster item
// Default value is true, so this step is required
rosterCtrl.autoremove = false;
The procedure mentioned above for removing roster contacts is not sufficient if the roster contact is an instance of jabberwerx.cisco.QuickContact as opposed to an instance of jabberwerx.RosterContact. If the roster contact is an instance of jabberwerx.cisco.QuickContact, remove() (i.e jabberwerx.Entity.remove(); ) must be called as opposed to unsubscribe() (i.e. jabberwerx.cisco.QuickContactController.unsubscribe() ); The following shows how to remove a contact that is an instance of jabberwerx.cisco.QuickContact:
// Previously triggered event that contains session information
var session = evt.data.content.session;
if (session) {
// Get the current entity
var entity = session.getEntity();
if (entity instanceof jabberwerx.RosterContact) {
entity.controller.unsubscribe(entity.jid);
}
else if (entity instanceof jabberwerx.cisco.QuickContact) {
// Calls jabberwerx.Entity.remove
entity.remove();
}
}
Back to the top
As described in the Cisco AJAX XMPP Library: Public Protocol Compliance document, the Cisco AJAX XMPP Library provides very limited support for XEP-0077: In-band registration.
Note: This feature is not supported by Cisco Unified Presence. To create a new user account on Cisco Unified Presence, please refer to the Deployment Guide For Cisco Unified Presence.
Back to the topCAXL supports High Availability as below:
Note:
Go to Cisco Unified Presence Administration -->"System" -->"Cluster Topology" and select the desired sub-cluster, then tick the "Enable High Availability" checkbox
Note: The CAXL client may still connect to the user's old home node if the user is reassigned to the user's backup node.
Note: The 'Routing Communication Type' must be setup correctly on Cisco Unified Presence (Go to Cisco Unified Presence Administration -->"System" -->"Cluster Topology" -->"Settings" -->Select "Routing Communication Type", you may select "Help" -->"This Page" for more information).
Cisco provides a minimal distribution of the core library for applications that do not need typical IM functionality.
The minimal library, jabberwerx.min.js, provides client session management, authentication, stanza sending and eventing when a stanza is received. IM centric functionality like 1-1 chat sessions, text conferencing rooms and publish/subscribe is not available. Furthermore, Cisco Unified Presence (XEP-0233) Service Discovery is not supported by the Minimal library and is disabled by default. See the Deployment Considerations for further information on Service Discovery. A list of classes included in the minimal library can be found in the API documentation delivered with the library.
THE SPECIFICATIONS AND INFORMATION REGARDING THE PRODUCTS IN THIS MANUAL ARE SUBJECT TO CHANGE WITHOUT NOTICE. ALL STATEMENTS, INFORMATION, AND RECOMMENDATIONS IN THIS MANUAL ARE BELIEVED TO BE ACCURATE BUT ARE PRESENTED WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED. USERS MUST TAKE FULL RESPONSIBILITY FOR THEIR APPLICATION OF ANY PRODUCTS.
THE SOFTWARE LICENSE AND LIMITED WARRANTY FOR THE ACCOMPANYING PRODUCT ARE SET FORTH IN THE INFORMATION PACKET THAT SHIPPED WITH THE PRODUCT AND ARE INCORPORATED HEREIN BY THIS REFERENCE. IF YOU ARE UNABLE TO LOCATE THE SOFTWARE LICENSE OR LIMITED WARRANTY, CONTACT YOUR CISCO REPRESENTATIVE FOR A COPY.
The Cisco implementation of TCP header compression is an adaptation of a program developed by the University of California, Berkeley (UCB) as part of UCB's public domain version of the UNIX operating system. All rights reserved. Copyright © 1981, Regents of the University of California.
NOTWITHSTANDING ANY OTHER WARRANTY HEREIN, ALL DOCUMENT FILES AND SOFTWARE OF THESE SUPPLIERS ARE PROVIDED "AS IS" WITH ALL FAULTS. CISCO AND THE ABOVE-NAMED SUPPLIERS DISCLAIM ALL WARRANTIES, EXPRESSED OR IMPLIED, INCLUDING, WITHOUT LIMITATION, THOSE OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT OR ARISING FROM A COURSE OF DEALING, USAGE, OR TRADE PRACTICE.
IN NO EVENT SHALL CISCO OR ITS SUPPLIERS BE LIABLE FOR ANY INDIRECT, SPECIAL, CONSEQUENTIAL, OR INCIDENTAL DAMAGES, INCLUDING, WITHOUT LIMITATION, LOST PROFITS OR LOSS OR DAMAGE TO DATA ARISING OUT OF THE USE OR INABILITY TO USE THIS MANUAL, EVEN IF CISCO OR ITS SUPPLIERS HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
Any Internet Protocol (IP) addresses and phone numbers used in this document are not intended to be actual addresses and phone numbers. Any examples, command display output, network topology diagrams, and other figures included in the document are shown for illustrative purposes only. Any use of actual IP addresses or phone numbers in illustrative content is unintentional and coincidental.
Cisco and the Cisco logo are trademarks or registered trademarks of Cisco and/or its affiliates in the U.S. and other countries. To view a list of Cisco trademarks, go to this URL:http://www.cisco.com/go/trademarks. Third-party trademarks mentioned are the property of their respective owners. The use of the word partner does not imply a partnership relationship between Cisco and any other company. (1110R)
© 2014 Cisco Systems, Inc. All rights reserved.