Microsoft Office

Communicator Web
Access
(2007 release, Public
Beta)
Authentication Guide
Published: March 2007
This document supports a preliminary release of a software product that may be changed substantially prior to final commercial release.
This document is provided for informational purposes only and Microsoft makes no warranties, either express or implied, in this document.
Information in this document, including URL and other Internet Web site references, is subject to change without notice. The entire risk of
the use or the results from the use of this document remains with the user. Unless otherwise noted, the companies, organizations, products,
domain names, e-mail addresses, logos, people, places, and events depicted in examples herein are fictitious. No association with any real
company, organization, product, domain name, e-mail address, logo, person, place, or event is intended or should be inferred. Complying
with all applicable copyright laws is the responsibility of the user. Without limiting the rights under copyright, no part of this document
may be reproduced, stored in or introduced into a retrieval system, or transmitted in any form or by any means (electronic, mechanical,
photocopying, recording, or otherwise), or for any purpose, without the express written permission of Microsoft Corporation.

Microsoft may have patents, patent applications, trademarks, copyrights, or other intellectual property rights covering subject matter in this
document. Except as expressly provided in any written license agreement from Microsoft, the furnishing of this document does not give
you any license to these patents, trademarks, copyrights, or other intellectual property.

© 2007 Microsoft Corporation. All rights reserved.

Microsoft, MS-DOS, Windows, Windows Mobile, Windows Server, Windows Vista, Active Directory, Internet Explorer, MSDN, Outlook,
SharePoint, Visual Studio, and Win32 are either registered trademarks or trademarks of Microsoft Corporation in the United States and/or
other countries.

All other trademarks are property of their respective owners.

Contents
Contents............................................................. ..............................3
Introduction..................................................................................... .......1
Who Should Read This Guide............................... .............................1
Overview.................................................................................. .........1
Communicator Web Access AJAX Service API...............................2
Communicator Web Access Controls............................................2
Communicator Web Access AJAX Service SDK..............................2
Understanding Authentication.......................................................... .2
Authentication Flow................................................................... ...5
Determining Server Authentication Mode.........................................6
Using Built-in Authentication Mode..............................................6
Using Custom Authentication Mode ............................................6
Built-in Authentication...................................... ................................7
Integrated Windows Authentication.............................................7
Quick Sign-In............................................................ ...............7
Forms-based Authentication.................................................... .....7
Implementing Built In Authentication...........................................8
Setting up the Normal Mode Environment...............................8
Custom Authentication................................................................... ...8
Single Sign-On............................................................................ ..8
Sign-Out URL..........................................................................................................................9
Implementing Single Sign-On Using ISA Server 2006 ..................9
Understanding Single Sign-On Traffic Flow............................10
Configuring Persistent Cookies.................................. ............12
Credentials Caching................................... ...........................13
Session Timeouts....................................... ...........................13
Subsequent Sign In................................... ............................13
Using Third Party Pluggable Authentication Solution..................13
Using Two Factor Authentication............................................... ..14
Selecting HTTPS or HTTP..................................................... ............14
Scenario 1: Creating the Virtual Server......................................14
Scenario 2: Configuring the ISA Server 2006 Web Publishing Rule15
 Scenario 3: Creating the ISA Server 2006 Web Listener.............15
Integrating Communicator Web Access Controls ............................16
Integrating Parallel Integrated Windows Authentication.............16
Integrating Proxy Authentication.................................... ............17
Integrating Passback Authentication..........................................17
Accessing the API from the Client...................................................18
Testing Authentication Implementations.........................................19
Using the Software Development Kit..........................................19
Installing the Software Development Kit...............................19
Accessing the Communicator Web Access AJAX Service API..20
Accessing the API Using the Web Controls............................21
Cross-Domain Solutions and Restrictions..............................22
Authorization................................................................................. ..23
Introduction
Microsoft® Office Communicator Web Access (2007 release) is a service that provides platform-
independent, browser-based, client features for Microsoft Office Communications Server 2007. Office
Communications Server 2007 and Office Communicator Web Access (2007 release) build on the
foundation established by Live Communications Server 2005 with SP1 and Communicator Web
Access (2005 release).
Microsoft Office Communicator Web Access (2007 release) adds support for Custom Authentication,
including single sign-on (SSO) and two-factor authentication. Custom Authentication, combined with
the Microsoft Office Communicator Web Access (2007 release) AJAX Service Application
Programming Interface (API) and the Microsoft Office Communicator Web Access (2007 release)
AJAX Service Web Controls provide application developers with access to the presence, instant
messaging, and conferencing features provided by Office Communications Server 2007 and
Communicator Web Access (2007 release) service.

Who Should Read This Guide

This guide is for third party application developers needing a basic understanding of the authentication
and integration methods provided by or available to the Communicator Web Access (2007 release)
AJAX Service API and Communicator Web Access controls. For detailed API information, see the
Microsoft Office Communicator Web Access (2007 release, Public Beta) AJAX Service SDK.

Overview
Communicator Web Access (2007 release) has been developed and tested with code implementations
added to the 2005 release of Communicator Web Access for enabling automatic sign-in, including
single sign-on (SSO). Many of the changes to the 2005 release that enable automatic sign-in are
changes made to the underlying Communicator Web Access authentication mechanisms.
The Communicator Web Access (2007 release) AJAX Service API is one of five Unified
Communications APIs available to ISVs to help them quickly and easily provide real time
communications solutions to their customers. The five Unified Communications APIs are shown in the
next table.
Table 1: Unified Communications APIs
Unified Communications API Description
A .NET Framework-based (managed) API for
creating and deploying server-like or middle-
tiered real-time communications applications. It
Unified Communications Managed
is especially useful for application with high
API (UCMA)
scalability requirements. Communicator Web
Access is a server-based application that uses
UCMA.
A COM-based API for creating and deploying
client side real-time collaboration applications. It
Unified Communications Client is interoperable with the .NET Framework and is
Platform API useful for applications with high requirements
for device performance. Office Communicator is
a desktop client built on UCCP.
2 | Microsoft Office Communicator Web Access Authentication Guide

A COM Automation API to enable programmatic

access to Office Communicator. It is useful for
Office Communicator API
applications that extend Office Communicator to
offer customized functionalities.
An AJAX Service-based API for creating browser-
based client applications. Communicator Web
Communicator Web Access AJAX
Access controls are based on the AJAX service
Service API
API. It is especially useful for applications that
must be operating system independent.
For managing server and creating server
Office Communications Server API
applications.
Communicator Web Access (2007 release) provides the AJAX Service API, the Communicator Web
Access Controls, and the Communicator Web Access AJAX Service SDK.

Communicator Web Access AJAX Service API

The Communicator Web Access (2007 release) AJAX Service API provides access to Communicator
Web Access (2007 release) API methods and events, and is based on the Asynchronous JavaScript and
XML programming model. Clients communicate with each other and the server by sending HTTP and
HTTPS messages formatted in prescribed XML and JSON (JavaScript Object Notation) syntaxes. See
the Accessing the API From the Client section.

Communicator Web Access Controls

Communicator Web Access controls are JavaScript classes that encapsulate the commonly used
functionality required of a Communicator Web Access AJAX Service client. The Communicator Web
Access controls inherit from the Microsoft.Rtc.Internal.Cwa.WebPages.WebControls_Code class.
See the Integrating Communicator Web Access Controls section.

Communicator Web Access AJAX Service SDK

The Communicator Web Access (2007 release) AJAX Service Software Development Kit (SDK) is
provided as a reference for ISVs. It contains detailed information about the API and Controls, and
contains three samples to illustrate them. See the Using the Software Development Kit section.

Understanding Authentication
Independent software vendors (ISVs) can use the Communicator Web Access (2007 release) AJAX
Service SDK, the Communicator Web Access (2007 release, Public Beta) API, and the Web server
controls to rapidly and easily:
• Deploy Communicator Web Access out of the box using built-in authentication
• Integrate enhanced presence provided by the AJAX Service API and the Communicator Web
Access controls
• Provide interoperability between enhanced and legacy clients
• Integrate and build custom Communicator Web Access controls
• Develop custom conferencing and call routing applications
• Provide an SSO experience using custom authentication
• Provide two factor authentication using custom authentication
 Authorization| 3

• Build a custom user interface (UI ) to meet their customer’s specific needs
For example, you can combine customer relationship management (CRM), Web-based portal, and
enterprise resource planning (ERP) systems within a Web-based portal to meet your customers’ needs.
You can use the Communicator Web Access API to create the following:
• Browser-based applications
• Standalone network applications
• Platform-agnostic applications running on the Microsoft Windows® operating system, or on
UNIX, Linux, Mac OS, or Berkeley Software Distribution (BSD)
• Language-agnostic applications using Microsoft .NET or open-source implementations (Mono),
native C/C++ applications running on Linux or one of the BSD operating systems, JavaScript,
Perl, C#, etc
• Mobile device applications
• Custom Authentication mechanisms for any of the above
Some advantages to Web-based solutions that expose multiple systems and applications are:
• Web-based solutions can provide common functionality to a wide variety of operating systems
and hardware or software platforms.
• Users can access Web-based solutions through a browser without having to install additional
software on their computers.
• Frequent updates to the user interface or functionality of back-end applications are usually
transparent to the Web-based solution.
You must deploy Office Communicator Web Access (2007 release) and Office Communications Server
2007 at a minimum to support your applications using one or more of the following authentication and
integration methods:
• Built-in Authentication
• Integrated Windows authentication (NTLM/Kerberos) only – only available for internal users
who have an account in the Active Directory® Domain Services.
• Forms-based authentication only – required for external users and optional for internal users
• Integrated Windows and Forms-based authentication – for internal deployments with the
Windows Internet Explorer® Internet browser and the Mozilla Firefox browser.
• Quick Sign-In
• Custom Authentication
• Single Sign-On (SSO) Authentication
o Microsoft ISA Server 2006 SSO solution
• Third Party Authentication
• Two Factor Authentication
These authentication methods can be implemented to access the API, either via the AJAX Service or
the Communicator Web Access controls. The reference topology is shown in the next figure.
4 | Microsoft Office Communicator Web Access Authentication Guide

Figure 1: Reference Topology

Available authentication mechanisms by operating system and browser are shown in the next table.
Table 2: Authentication matrix

Operating Browser Authentication

System Mechanism
Windows® 2000 Microsoft Forms-based
SP4 Internet NTLM
Explorer® 6 SP1
Custom
Windows XP SP2 Internet Explorer Forms-based
6 SP2 NTLM
Windows Internet Kerberos
Explorer 7
Custom
Firefox 2.0.latest
 Authorization| 5

Windows Vista™ Internet Explorer Forms-based

7 NTLM
Firefox 2.0.latest Kerberos
Custom
Mac OS X 10.3.9 Safari 1.3.2 Forms-based
Kerberos
Custom
Firefox 2.0.latest Forms-based
NTLM
Kerberos
Custom
Mac OS X 10.4.8 Safari 2.0.latest Forms-based
Kerberos
Custom
Firefox 2.0.latest Forms-based
NTLM
Kerberos
Custom

Authentication Flow
The authentication request must be made first before any other requests in a session. The
authentication method is the only request method which cannot have a rid attribute. The URL that is
used by each authentication mechanism is different. The URL can be used to authenticate a user with
the Communicator Web Access service using one of the following authentication schemes:
• Integrated Windows authentication in which the credentials from the user's Windows account is
used to have the user authenticated. The URL for such a request is of the
"https://server.contoso.com/iwa/logon.html".
• Form-based authentication in which the user must provide their credentials explicitly in order to
be authenticated. The URL used for such a request is of the
"https://server.contoso.com/forms/logon.html".
• Single Sign-On (SSO) The URL for such a request is of the
"https://server.contoso.com/sso/logon.html".
When the request is successful, the server creates an authentication ticket and returns it to the client via
a special HTTP header (named "CWA-Ticket") in the HTTP response. The caller must cache this ticket
and submit it, as the CWA-Ticket header, in all subsequent HTTP requests throughout the session.
The ticket will expire after a server-specified time period. The Communicator Web Access service will
issue a new ticket when that time period expires. The client must watch for the new ticket in the HTTP
responses from both the command and data channels. The client cache must be updated after receiving
a new authentication ticket. This new ticket will be used in all HTTP requests made to the command
and data channels until the next update of the ticket. If the authentication ticket is not returned, the
Logon request has failed.
The rest of this guide discusses the various authentication and integration methods that can be used.
Companion documents to be used with this guide for more detailed information, include the following:
• Microsoft Office Communicator Web Access (2007 release) AJAX Service SDK
6 | Microsoft Office Communicator Web Access Authentication Guide

• Microsoft Office Communicator Web Access (2007 release) Guide to Lab Deployment
• Microsoft Internet Security and Acceleration (ISA) Server 2006 documentation

Determining Server Authentication

Mode
Depending upon the authentication and integration methods you choose in your implementation, the
Communicator Web Access (2007 release) server supporting your implementation must be configured
in one of two modes:
• Use built-in authentication mode is the default authentication mode
• Use custom authentication mode is used and required for single sign-on and third party
authentication solutions
Figure 2: Select Authentication Type

Using Built-in Authentication Mode

Built-in authentication is the default mode. Built-in authentication mode is a non-single sign-on
environment, and is the mode that should be used for testing automatic logon scenarios when an ISA
Server 2006 providing SSO functionality isn’t deployed. Built-in authentication mode is also the
environment that an independent software vendor (ISV) uses as a starting place for testing the new
Microsoft Office Communicator Web Access (2007 release) Controls and the new Microsoft® Office
Communicator Web Access (2007 release) AJAX Service API For information about setting up a
Built-in authentication mode environment, see the Communicator Web Access (2007 release, Public
Beta) Guide to Lab Deployment. For information about the Communicator Web Access (2007 release)
AJAX Service API and the Communicator Web Access (2007 release) Controls, see the
Communicator Web Access (2007 release, Public Beta) Software Development Kit (SDK).

Using Custom Authentication Mode

Communicator Web Access (2007 release) now contains a custom authentication option, which
includes single sign-on authentication. This allows Communicator Web Access to work with ISA
Server 2006 and third-party single sign-on solutions that capture and manage credentials.
When using ISA Server 2006 for SSO, the Communicator Web Access virtual server must be
published using HTTPS. Configuring the ISA Server 2006 to use HTTP is not supported. When using
 Authorization| 7

single sign-on users are challenged for authentication credentials only if the sign-in request is an
HTTPS root request or it is a sign-in request after a failed authentication attempt. If the user has
already been authenticated, the user is not challenged again for access to Communicator Web Access
(2007 release). ISA Server 2006 can be deployed either as a workgroup member, or a domain member
when providing SSO.

Built-in Authentication
Built-in authentication is authentication supported by Communicator Web Access without
modification, other than the initial setup and configuration. Built-in authentication includes Integrated
Windows authentication and Forms-based authentication.

Integrated Windows Authentication

Integrated Windows authentication consists of the NTLM and Kerberos authentication protocols over
HTTP and HTTPS. Communicator Web Access supports this form of authentication for Internet
Explorer® Internet browser and for AJAX clients that enable sign in to Communicator Web Access
and that use cached credentials when a user has already logged onto a Microsoft Windows domain.
Integrated Windows authentication is available only for internal users, who are members of Active
Directory and are running Windows platforms.

Quick Sign-In
When using Integrated Windows authentication, Communicator Web Access users can authenticate
using Quick Sign-in. For example, with Quick Sign-in, a user can enter the following URI to access
Communicator Web Access:
• https://server.contoso.com/quicksignin
The following two settings in the Internet Explorer browser are required:
• The Automatic logon only in Intranet zone radio button must be selected on the Security
Settings – Local Intranet Zone page
• The Communicator Web Access server URL must be added to the Local Intranet zone.
The domain user account that the user is logged on to the local computer is the account that is used for
Quick Sign-In.
When the user is already authenticated through Integrated Windows authentication, Communicator
Web Access will open immediately with no further authentication requests. This is beneficial to
frequent users that bookmark Communicator Web Access as https://server.contoso.com/quicksignin.
Selecting the bookmark enables the user to sign-in without providing credentials, thereby providing a
better user experience.
For remote users, and supported browsers that don’t support Integrated Windows authentication, the
forms-based authentication window will appear.
Quick Sign-in does not work with forms-based authentication.

Note Using these URIs to code quick sign-in from other Web applications is
not a supported scenario and may result in unexpected behavior.

Forms-based Authentication
Clients that use forms authentication submit a user’s credentials (domain, user name, and password) in
plain text within the sign-in request. To provide compatibility with a variety of different Web browsers
and to support all scenarios, Communicator Web Access supports Forms-based authentication. When
8 | Microsoft Office Communicator Web Access Authentication Guide

providing remote users with access to Communicator Web Access from across an enterprise firewall,
Forms-based authentication is the only form of authentication supported. Because credentials are in
plain text, using secure HTTP (HTTPS) and certificates is imperative for security. Forms-based
authentication can also be used for internal user access, and is required for use of some browsers such
as Mozilla Firefox with Communicator Web Access.

Implementing Built In Authentication

Built-in authentication mode is a non-single sign-on (SSO) environment, and is the mode that should
be used for testing automatic logon scenarios when an ISA 2006 Server providing SSO functionality
isn’t deployed. Built-in authentication mode is also the environment that an independent software
vendor (ISV) uses as a starting place for testing the new Microsoft Office Communicator Web Access
(2007 release) Controls and the new Microsoft® Office Communicator Web Access (2007 release)
AJAX Service API.

Setting up the Normal Mode Environment

Lab 1 in the Communicator Web Access (2007 release) Guide to Lab Deployment provides the
procedures for deploying a built-in authentication mode lab environment, in which you can:
• Test Communicator Web Access features
• Test applications that integrate proxy authentication
• Test applications that integrate passback authentication
• Test the Communicator Web Access Controls
• Test applications with custom controls
• Test applications that integrate Integrated Windows authentication or forms-based authentication
to provide an automatic sign-in user experience
• Run the samples that are contained in the Communicator Web Access AJAX Service SDK.
• Test a custom UI that accesses the Communicator Web Access AJAX Service API
You must us custom authentication when implementing SSO.

Custom Authentication
Custom authentication is any authentication other than Integrated Windows authentication or forms-
based authentication provided by Communicator Web Access built-in authentication. Examples of
custom authentication include single sign-on, third party plug-in authentication solutions, and two
factor authentication. Custom authentication can be used for both internal and external virtual servers.

Single Sign-On
ISVs creating Web-based portal solutions want to provide an optimal sign-on experience for their
users. Ideally, when a user signs into one of the applications, the sign-in information can be used for
other applications so that the user does not have to manually provide credentials again. This is
automatic sign-in. Single Sign-On (SSO) is one type of automatic sign-in. Automatic sign-in is the
process by which, after successful initial authentication to another ISA Server Web published site,
subsequent sign-in to Communicator Web Access (2007 release) occurs without requiring the user to
provide credentials again. The following are examples of scenarios in which single sign-on provides an
optimal user sign-in experience:
 Authorization| 9

• A user wants to use other ISA Server Web published applications in addition to Communicator
Web Access (2007 release), for example, Microsoft Office Outlook® Web Access and Microsoft
Office SharePoint® portal services. If the user has already provided his or her credentials when
signing in to Outlook Web Access, the user should not have to provide his or her credentials again
when accessing Communicator Web Access.
• A user wants to access Web Services in a portal that aggregates information from several different
back-end systems. For example, a financial portal may provide Communicator Web Access (2007
release) Instant Messaging in addition to several other services, such as account balances and
other transactions. The user should be able to authenticate once and then have access to all parts of
the portal.
ISA Server 2006 also supports Two Factor Authentication. See the ISA documentation for details.
Sign-Out URL
If your custom authentication solution requires a virtual directory (vdir) and files on the
Communicator Web Access server, you must allow anonymous access on that vdir. Use the Sign-Out
URL field to specify an optional sign-out URL.
Figure 3: Sign-Out URL

The authentication token provided by the SSO server is stored on the client machine in the form of a
cookie. If the Communicator Web Access client is browser based, closing the browser will delete the
cookie. Otherwise, the expiration time value of the cookie will enforce its invalidation. It is strongly
suggested that at the time a user has logged off Communicator Web Access, they visit the URL
designated as the sign-out page by the SSO server. A visit to this page will result in the clearing of any
authentication cookies stored on the client. This step is particularly important when the Communicator
Web Access client is not browser based. The desktop based Communicator Web Access client
application is responsible for clearing the authentication cookie with a visit to the sign-out page.

Implementing Single Sign-On Using ISA Server 2006

You can also integrate an SSO experience with the Communicator Web Access API. You need to
configure a Communicator Web Access (2007 release) virtual server using custom authentication, and
deploy an ISA Server 2006 server configured for SSO. To provide an SSO solution using
Communicator Web Access (2007 release) you must:
• Deploy Communicator Web Access (2007 release) virtual server in custom authentication mode
• Deploy ISA Server 2006 with a Web listener configured for SSO and using HTTPS to publish the
virtual server
10 | Microsoft Office Communicator Web Access Authentication Guide

ISA Server 2006 can be used to provide SSO for Communicator Web Access users accessing a virtual
server using custom authentication. The ISA Server 2006 server publishing the virtual server must be
deployed in the perimeter network, and it is recommended that the ISA server be a workgroup
member, not a domain member server. Configuration of the ISA server to use SSL (HTTPS) when
publishing the external site is the only supported configuration. Configuring ISA to use HTTP on the
published external site is not supported for Communicator Web Access (2007 release).
Although Communicator Web Access (2007 release) uses a session ticket instead of cookies, many of
the enterprise applications you might use in your solution, such as Windows SharePoint Services
(WSS) and ISA Server 2006 enabled for SSO, use cookies.

Understanding Single Sign-On Traffic Flow

You might enable SSO, for example, in a customer solution that uses Microsoft SharePoint Portal
Server 2003, Communicator Web Access (2007 release), and Exchange Server 2003 with Outlook Web
Access enabled. Your solution consists of an extranet portal with links to Communicator Web Access
(2007 release) and Outlook Web Access. You can use ISA Server 2006 to Web publish the SharePoint
portal site using SSL with links to the Communicator Web Access (2007 release) virtual server and the
Outlook Web Access site. Table 3 shows example URLs, IP addresses, and ports for this scenario.
Table 3: Server URL, IP Address, and Port
Site Public URL Private URL IP Address Ports

ISV Portal Solution https://isv.contoso. isv.contoso.co 192.168.1 80/44

com m 0.1 3
Communicator Web https://cwa.contos cwa.contoso. 192.168.1 80/44
Access o.com com 0.2 3
Outlook Web https://owa.contos mail.contoso. 192.168.1 80/44
Access o.com com 0.3 3

Note
ISA Server 2006 uses cookies to enable single sign-on.

The next figure shows the SSO traffic flow for the ISA Server 2006 solution.
 Authorization| 11

Figure 4: ISA Server 2006 Single Sign-On Flow

The flow of traffic for this scenario is as follows:

1. The User enters https://isv.contoso.com in the browser on the client, sending the traffic to ISA
Server 2006.
2. ISA Server 2006 responds with an ISA SSO authentication form back to the client.
12 | Microsoft Office Communicator Web Access Authentication Guide

3. The user enters credentials for the ISV application, and clicks Log On, which sends the traffic to
ISA Server 2006.
4. On behalf of the client, ISA Server 2006 caches the credentials in a cookie on the local computer
and then sends the traffic to the ISV SharePoint server, which authenticates the user.
5. The ISV SharePoint server sends the client-response back to ISA Server 2006.
6. ISA Server 2006 forwards the response to the client, which, for example, displays the ISV’s
solution default page, containing a link to Communicator Web Access (2007 release).
7. The user clicks the Communicator Web Access (2007 release) link, which sends the request to ISA
Server 2006.
8. ISA Server 2006, using the credentials cached on ISA Server 2006 after the initial authentication
with ISA, and on behalf of the client, logs on to Communicator Web Access.
9. Communicator Web Access authenticates the client and attaches an authentication ticket to the
response, and sends the response with the authentication ticket to the client, by way of ISA Server
2006.
10. ISA Server 2006 forwards the response back to the client, and displays, for example, the
following:

With only one set of credentials during initial authentication with the SharePoint server in this
example, Communicator Web Access (2007 release) authentication was done without the need for
the user to enter her credentials again.
Subsequent authentications for SSO-aware applications, which are marked as N in Figure 4, are done
in the same way.

Configuring Persistent Cookies

To enable single sign-on consistently with all supported browsers, you need to use persistent cookies
within ISA Server 2006. You set persistent cookies from the Forms tab of the Properties page for the
Web listener for which you want to enable multiple browser instances. The Forms tab is shown on
Figure 5. Click the Advanced button on the Forms tab. This action displays the Advanced Form
Options dialog box shown in Figure 6.
 Authorization| 13

Figure 5: Forms Tab Figure 6: Advanced Form Options

On the Advanced Form Options page (Figure 6), from the Use Persistent Cookies options list, select
the option to use persistent cookies on all computers, or only on private computers, and select the
Ignore browser’s IP address for cookie validation check box. Doing so will provide your users with
a single sign-on experience for multiple browser instances.
The Forms tab is where you to specify an SSO credentials challenge page that you have custom-built
for your solution, instead of the default ISA Server 2006 forms page.

Credentials Caching
In a single sign-on scenario, a user’s credentials are cached in memory on ISA Server 2006 and are
then reused whenever the user accesses one of the other Web services.

Session Timeouts
When a user accesses multiple Web-based services simultaneously, each application may have its own
default timeout period. Allowing each application to initiate a session timeout could result in a
frustrating user experience. To prevent multiple user sign-ins that would result, the single sign-on
solution, and not the individual applications, should control session timeouts.

Subsequent Sign In
For situations in which the user’s session times out, Communicator Web Access provides a Sign In
Again button. However, when the Sign In Again button is clicked after a session timeout, ISA Server
2006 prompts the user to reenter his or her credentials, because the cached credentials have expired.
You use the Microsoft.Rtc.WebControl.LoginCtrl.LogonByIWA method to sign the user in to
Communicator Web Access through SSO-enabled ISA Server 2006. This logon method should only be
used if SSO-enabled ISA Server 2006 is deployed in front of the ISV server and the Communicator
Web Access server. This method assumes that the client has already logged on to the ISV site through
SSO-enabled ISA Server 2006.

Using Third Party Pluggable Authentication Solution

A third-party pluggable solution is one in which added authentication functionality is added to the
Communicator Web Access solution using a small plug-in, usually a DLL as an ISAPI filter in IIS. For
guidance in creating ISAPI filters for IIS 6.0, see:
14 | Microsoft Office Communicator Web Access Authentication Guide

http://msdn.microsoft.com/library/default.asp?url=/library/en-us/iissdk/html/77b95fc9-e7de-471a-
8de9-fee27c816cc3.asp
Once you have built the plug-in ISAPI filter, you must load it in IIS using the procedure at:
http://support.microsoft.com/kb/150312.

Using Two Factor Authentication

With the Public Beta release of Communicator Web Access (2007 release), two factor authentication
implemented by ISA Server 2006 and other third party solutions is supported. Two factor
authentication requires two separate elements to successfully authenticate a user. For ISA Server 2006,
see the ISA documentation at: http://www.microsoft.com/technet/isa/2006/authentication.mspx. For
other third party solutions, see the respective vendor documentation. Also see:
• Microsoft Authentication Partners at:
http://www.microsoft.com/isaserver/partners/authentication.mspx
• An overview of Internet Security and Acceleration Server 2006 and Intelligent Application
Gateway 2007 at: http://www.microsoft.com/forefront/edgesecurity/saa.mspx
• The Secure Access Using Smart Cards Planning Guide, at:
http://www.microsoft.com/technet/security/guidance/networksecurity/securesmartcards/default.ms
px

Selecting HTTPS or HTTP

There are a number of configuration scenarios that require you to select between HTTP and HTTPS. In
all cases, HTTPS is strongly recommended. In one case, it is required. Let’s look at each scenario.

Scenario 1: Creating the Virtual Server

When you create an internal or an external virtual server, regardless of the authentication mode, using
HTTPS is strongly recommended.
Figure 7: Select Connection Type
 Authorization| 15

Scenario 2: Configuring the ISA Server 2006 Web

Publishing Rule
When you use ISA Server 2006 to Web publish a virtual server for external users, HTTPS is strongly
recommended for the connection from ISA Server 2006 to the published virtual server. You specify
this on the Server Connection Security page of the Web publishing rule wizard, and from the
Bridging tab of the Web Publishing Rule Properties page. However, your choice here is dictated by
your choice in Scenario 1.

Figure 8: Web Publishing Rule Wizard Figure 9: Bridging Tab

Scenario 3: Creating the ISA Server 2006 Web

Listener
When you use ISA Server 2006 to Web publish a virtual server for external users, HTTPS is required
on the Web listener for the external interface of ISA Server 2006. This is initially specified in the
wizard used to create the listener. However, you can modify the setting from the connections tab of the
Web listener properties page in the ISA MMC. Changing the connection type to HTTP is unsupported.
16 | Microsoft Office Communicator Web Access Authentication Guide

Figure 10: Web Listener Wizard Figure 11: Connections Tab

Integrating Communicator Web Access

Controls
Using the Communicator Web Access controls, an application developer can create an AJAX Service
client by simply instantiating the controls, setting appropriate properties, and invoking the desired
methods. The common functionality required of a Communicator Web Access AJAX Service client
includes creating and maintaining the communication channels, signing in to a server, embedding the
display of a user presence in a Web page, starting an IM conversation, etc.
Integrating the Communicator Web Access (2007 release) AJAX Service API and the Communicator
Web Access (2007 release) Controls with other applications requires you to implement one or more of
the supported authentication and integration methods. You can provide custom solutions by:
• Integrating Parallel Integrated Windows authentication
• Integrating Passback authentication
• Integrating SSO authentication using ISA Server 2006 and SSO mode
• Integrating Server Proxying authentication
• Integrating Quick Sign-in

Integrating Parallel Integrated Windows

Authentication
You might want to integrate the Communicator Web Access Controls with internal corporate websites
that use Integrated Windows authentication, for example a corporate team portal using the Microsoft
Office SharePoint® Team Services. Integrated Windows authentication is uniquely convenient for
many internal sites because Integrated Windows authentication allows the browser to immediately
authenticate using the identity of the currently logged on user and in most cases can avoid an annoying
prompt for the user’s credentials.
As the authentication process for SharePoint is transparent to the user, you can add Communicator
Web Access Controls to the SharePoint site that access Communicator Web Access without an
authentication prompt. The Communicator Web Access site and the SharePoint site might be on
different servers (or at least different websites) so the browser performs separate authentications to
 Authorization| 17

these servers, services, or sites and the browsers maintain separate credential caches for each different
website.
To give an example of the logon flow here, the user contoso\bob first accesses the SharePoint Web site.
The browser receives an Integrated Windows authentication challenge and is automatically
authenticated using the identity of contoso\bob since he is logged on to the local machine. Included in
the SharePoint HTML response is the URLs that request the UI controls from the Communicator Web
Access server. As the page is being rendered by the browser and it requests content from the server,
Integrated Windows authentication is again challenged for credentials, this time from a different
website. The browser once again will use credentials for contoso\bob to successfully authenticate.
This type of control authentication relies on domain users being logged on to their machines with their
domain user account and it also relies on the default Integrated Windows authentication mechanism
being enabled for Internet Explorer on the client machine. Therefore, it might not be ideal for all
situations. For example, if contoso\bob is logged onto his machine as a local administrator and
accesses SharePoint, the logon flow changes. Bob first will be prompted for domain credentials from
SharePoint. Upon entering his correct domain credentials, Bob will once again be prompted for
credentials from Communicator Web Access. This is not an optimal user experience, and also
introduces the possibility for the user to use different accounts and credentials to log on to different
Web sites existing within the same Web page. In this scenario, integrating the controls with the server
proxying authentication might be a better choice.

Integrating Proxy Authentication

Proxy authentication, also known as ISVProxy authentication, is one way that ISVs can integrate
Communicator Web Access (2007 release) and automatic sign-in functionality into their applications.
In proxy authentication, the ISV server calls into the Logon function and returns the ticket to the
client. The client then initiates the session by calling InitiateSession.
The ISV can alternatively call InitiateSession on the ISV server and return both the ticket and the
security ID (SID) to the client. For a sample code snippet, see the Communicator Web Access (2007
release) Software Development Kit (SDK) documentation and samples at:
• ..\Samples\WebControls\Source\ServerProxy.ashx

Integrating Passback Authentication

Passback authentication, like proxy authentication, is a way for ISVs to integrate Communicator Web
Access (2007 release) and automatic sign-in functionality into their applications. In Passback
authentication, the authentication call to Communicator Web Access originates from the browser.
Passback authentication works for both the Communicator Web Access Controls and for accessing the
Communicator Web Access (2007 release) AJAX Service API directly.
One requirement to use Passback authentication is that the ISV server on which the application is
running must have access to the credentials that were used to authenticate the user on the ISV server.
When the user authenticates on the ISV server, the ISV’s Web page that is sent to the client also passes
the credentials, in plain text, along with the Web page. Script within the page that the ISV has added
will call the LogonByForm method. For a sample code snippet, see the Communicator Web Access
(2007 release) Software Development Kit (SDK) documentation and samples at:
• ..\Samples\WebControls\Source\Passback.ashx
Once the user is authenticated, the session ticket that is returned by Communicator Web Access (2007
release) is cached. The cached credentials are used to call the CWAInitiateSession to establish a
session between the client and Communicator Web Access. Passback authentication is especially
suited for implementing the Communicator Web Access Controls.
18 | Microsoft Office Communicator Web Access Authentication Guide

The benefits of Passback authentication are relative ease of implementation and possible server load
reduction. However, the fact that credentials are passed in plain text must be considered by the
application developer.

Accessing the API from the Client

A Communicator Web Access (2007 release) AJAX Service API client is any application that uses the
Communicator Web Access AJAX Service to access Communicator Web Access. A client application
can be a stand-alone executable, for example, a Microsoft .NET-connected application written in C#.
The client can also be a browser-based Web application driven by JavaScript or other scripts embedded
in a Web page. If the Web application is an ASP.NET application, C# and other .NET-compatible
language, code can be running behind the Web pages, as well.
The Communicator Web Access AJAX Service API exposes a set of methods and events. Methods are
actions performed by the server, and events are the action results or other updates returned to the
client.
The combination of supported authentication methods and supported integration methods provides
multiple client entry points to the Communicator Web Access AJAX Service API. Client access to the
Communicator Web Access AJAX Service API requires a session ticket. Communicator Web Access
does not use a cookie to contain the session ticket. All clients that access Communicator Web Access
are responsible for manually attaching the session ticket to the HTTP header with each and every
function call.
A session ticket is an HTTP header that is returned by the authentication module after a user has signed
in and that is used to uniquely identify the user on all subsequent function calls.
A client can have the following Communicator Web Access entry points:
• Login through an unmodified, supported browser client
• Login through a client developed by an ISV and which accesses the Communicator Web Access
(2007 release) AJAX Service API
• Login using the Communicator Web Access (2007 release) Controls integrated within the ISV’s
application
• Login through ISA Server 2006 enabled for SSO and with SSO enabled for the Communicator
Web Access (2007 release) external virtual server
• Custom authentication solutions
An ISV application client can have the following end user entry points:
• Communicator Web Access (2007 release) sign-in page – Used to initiate the Communicator Web
Access client
• User login control – Used to initiate Communicator Web Access Controls
• Third-party interface – Supplied by ISV to handle login for 3rd party application
• Custom authentication solutions
The Schema file can be run against a code generation tool such as xsd.exe to generate classes and
serializers to use against the Communicator Web Access AJAX Service API. The generated classes
include enumerated items as well as the ability to extend the rich presence model with the messages
provided. The cwaRequests are:
Table 4: cwaRequests
Request Request Request Request
acceptImSession acknowledgeSubscr addContact addGroup
 Authorization| 19

ibers
deleteGroup deleteContact conference initiateImSession
initiateSession terminateSession logon logoff
acceptImSession terminateImSession sendInfo sendMessage
notifyComposing inviteParticipants updateContact updateGroup
publishRawCategori ejectParticipant promoteParticipant Lock
es
voIPRedirect voIPTerminate voIPRedirectToVoice voIPReplyWithIM
mail
queryPresence updateContainer publishSelfPresence subscribePresence
unSubscribePresenc search
e
The following code snippet gives an example.
<cwaRequests xmlns="http://schemas.microsoft.com/2006/09/rtc/cwa">
<initiateSession rid="1">
<securityMode>private</securityMode>
<userStateAvailability>3500</userStateAvailability>
<options autoPublishMachineState="true"</options>
</initiateSession>
< queryPresence rid="2">
<uris>
<uri>sip:bob@contoso.com</uri>
<uri>sip:carol@contoso.com</uri>
</uris>
</queryPresence>
</cwaRequests>
For details, see the Communicator Web Access (2007 release) AJAX Service API SDK

Testing Authentication
Implementations
This section discusses using the SDK to test your authentication solution.

Using the Software Development Kit

The Communicator Web Access (2007 release) AJAX Service Software Development Kit (SDK) is
provided as a reference for ISVs. It contains detailed information about the concepts discussed in this
guide, and contains three samples to illustrate them.

Installing the Software Development Kit

The SDK includes Web-based samples and samples based on the Microsoft Win32® application
programming interface. To install the SDK, double-click the SetupSE.exe or SetupEE.exe file on the
Office Communications Server 2007 installation media, click Deploy Other Server Roles, click
Deploy Communicator Web Access, click the Download the Communicator Web Access SDK
link, and then follow the instructions. The SDK default installation folder is %windir%/Program Files/
Office Communications Server 2007/ Communicator Web Access/SDK. Two subfolders are installed,
/Docs and /Samples.
20 | Microsoft Office Communicator Web Access Authentication Guide

Communicator Web Access provides an AJAX Service API, Communicator Web Access Controls, and
an SDK. These items provide the ISV with a starting point for developing applications that access the
Communicator Web Access AJAX Service API and integrate the controls. The API and controls enable
customers and ISVs to develop applications with enhanced presence conferencing. The SSO capability
of the combination of Communicator Web Access and ISA Server 2006 enables customers and ISVs to
develop applications with an SSO experience for their customers.
Any integrated development environment can be used to develop these applications. However, some of
the SDK code samples require the Microsoft Visual Studio® 2005 integrated development
environment.

Accessing the Communicator Web Access AJAX Service API

The Communicator Web Access (2007 release) AJAX Service SDK includes a Communicator Web
Access API sample.
Figure 12: The CwaApiViewer SDK Sample

AJAX stands for Asynchronous JavaScript and XML. It is a programming model for building
interactive Web applications. Communication between a client and server uses standard HTTP and
HTTPS request and response transactions. Supported transport formats are XML, JSON (JavaScript
Object Notation), or plain text. Unlike the traditional HTTP programming practice, an AJAX
transaction does not require that an entire Web page be transported over the wire for every change on a
Web page. The server provides modularized functionality through different access channels that are
exposed as different URLs on the same Web site. Communicator Web Access (2007 release) AJAX
Service API supports applications that use the AJAX programming model.
Communicator Web Access (2007 release) provides an AJAX Service application programming
interface (API) that publicly exposes methods and events for Communicator Web Access (2007
release). ISVs can develop applications by following the AJAX programming patterns. Various
programming languages, platforms, and operating systems, are supported. The Communicator Web
Access AJAX Service API uses XML as the data format and supports modularized access of the
following functionality:
• A Communicator Web Access AJAX Service API client signs in to Communicator Web Access by
using Forms-based authentication.
• A Communicator Web Access AJAX Service API client signs in to Communicator Web Access
using Integrated Windows authentication.
• A Communicator Web Access AJAX Service API client signs in to Communicator Web Access by
using single sign-on authentication.
• The AJAX client posts methods to Communicator Web Access.
 Authorization| 21

• The client receives events from Communicator Web Access.

Applications developed by using the AJAX programming model can enable users to do the following:
• Sign in and out of Communicator Web Access using a supported client.
• Manage and share presence information.
• Manage contacts and groups.
• Send and receive instant messages.
• Search for users within an enterprise.
These clients can be a browser-based Web application (for example, an ASP.NET v2.0 application) or
a standalone network application (for example, a .NET-connected executable, a Win32-based
standalone application, or a UNIX-based C++ application). Because the Communicator Web Access
AJAX Service API is based on the flexible AJAX programming model, the client applications are not
limited to running on Microsoft Windows® operating systems and can readily be deployed to desktop,
laptop, or other devices.
Communicator Web Access (2007 release) does not use a cookie to contain the session ticket. All
clients are responsible for manually attaching the session ticket on a HTTP header with each and every
function call.
Creating an application that accesses the Communicator Web Access AJAX Service API involves
implementing the following:
• The ISV application must sign in to a Communicator Web Access server using either Forms-based
authentication, Integrated Windows authentication, or single sign-on authentication
• The client must then contact the Communicator Web Access server to initiate the session.
• The client must post one or more AJAX methods to the Communicator Web Access server to do
the following:
• Manage contacts or groups.
• Set or query presence.
• Configure access control.
• Find users.
• Start an instant messaging session, send and receive text messages, or close the IM session.
• The client must be able to receive AJAX events from the server to do the following:
• Execute a method and return the result.
• Respond to a change in the server load and return a new query timeout value.
• Sign a contact in or out and return the affected contact information.
• Invite a user to join an IM conversation, accept the IM invitation, or send and receive instant
messages during a conversation.
• The client must sign out of the service and terminate the session.

Accessing the API Using the Web Controls

The Communicator Web Access (2007 release) AJAX Service SDK includes a Communicator Web
Access Control sample. The Communicator Web Access Controls are a collection of JavaScript classes
that inherit from classes in the Communicator Web Access AJAX Service API.
The controls encapsulate commonly used functionality for programming with the Communicator Web
Access AJAX Service API. This functionality includes maintaining the necessary communication
channels, signing in to or out of Communicator Web Access, querying and displaying the presence of a
22 | Microsoft Office Communicator Web Access Authentication Guide

user, and starting an IM conversation. Help utilities are also provided to support robust event handling
and error discovery.
Customers and ISVs can use the Communicator Web Access controls to integrate presence and Instant
Message features into their own Web-based applications. The Communicator Web Access Controls can
be used for:
• Enabling presence viewing from a Web page: A Web page can embed a presence control in an
HTML page to display the presence of a tracked user by simply dropping a presence control
instance to the HTML page and setting the appropriate SIP URI.
• Implementing cross-platform browser support
• Using the rapid application development paradigm
• Developing enhanced authentication experience applications
Integrating the Communicator Web Access Controls does not require deployment of any
Communicator Web Access (2007 release) files onto the ISV server. However, the ISV must add script
tags to their web pages in order to download the Communicator Web Access Controls. The client script
on the ISV Web site is also responsible for calling the entry point in the controls to pass any necessary
initialization parameters and begin execution.
You can use a number of sign-in methods when integrating the Communicator Web Access Controls
within your custom solutions. Communicator Web Access (2007 release) supports implementations
using the following:
• Parallel Integrated Windows authentication
• Passback authentication
• Proxy authentication
• Forms-based or Integrated Windows authentication for Automatic sign-in
Communicator Web Access controls use the JavaScript object XmlHttpRequest to send HTTP requests
to Communicator Web Access and to receive the corresponding HTTP responses. To minimize the
security concerns involved in cross-domain scripting, Internet Explorer enforces the same-origin safety
check on an XmlHttprequest instance to prevent the object from accessing resources residing in a
domain different from the one hosting the calling script.

Cross-Domain Solutions and Restrictions

In a Communicator Web Access (2007 release) deployment where Communicator Web Access is
installed in one domain (referred to as the server Web site) and a client application and the controls in
another domain (referred to as the ISV Web site), the Communicator Web Access Controls provide a
workaround to enable the cross-domain solution with the following restrictions:
• The ISV Web site and the server Web site must use the same protocol. That is, either HTTP or
HTTPS must be used for the both sites. (HTTPS is strongly recommended)
• The ISV Web site and the server Web site must be within a common parent domain. For example,
appHost.contoso.com and cwaServer.contoso.com are within a common parent domain,
contoso.com; however, appHost.fabrikam.com and cwaServer.contoso.com do not have a common
parent domain. The latter situation is not allowed. Domain names such as a.com and b.com do not
share a common parent domain.
• The application should use the fully qualified domain name to refer to the ISV Web site when
referencing the control files. NetBIOS name or IP address are not allowed. The following line of
code in an application's Web page illustrates the use of the full domain name.
<script src="http://app.contoso.com/WebControls/code.aspx"></script>
Do not use the following line of code in the Web page.
 Authorization| 23

<script src="http://app/WebControls/code.aspx"></script>
Or
<script src="http://202.3.4.5/WebControls/code.aspx"></script>
• Users must access the ISV Web site using the fully qualified domain name, for example,
http://appHost.contoso.com. Do not use NetBIOS name, IP address or "localhost", for example,
http://appHost, http://202.3.4.5 or http://localhost.
The above restrictions do not apply when an ISV Web site uses server proxy or server HTTP
redirection to handle the cross-domain request. In this situation, the ISV Web site and the server Web
site are considered to be within the same domain as far as the client is concerned. In this situation, a
client application must provide the server proxy path when calling the controls’ Initialize function.
Users who have already been authenticated should be able to access Communicator Web Access
functionality without being prompted again for credentials. The single sign-on capabilities in
Communicator Web Access make this experience possible. Enabling the single sign-on authentication
method removes the requirement for users to sign in to each part of the portal individually.
The subsequent sign-in is achieved by using the LogonByForm and LogonByIWA methods of the
Microsoft.Rtc.WebControl.LoginCtrl control, and cached credentials on ISA Server 2006, which is
required when SSO is enabled on the Communicator Web Access external virtual server.
When a control is used to interact with Communicator Web Access, user input of the credentials every
time the connection is made would be required in the absence of automatic logon. This would
downgrade the usability of the application. To maintain a high level of usability, automatic logon
should be used.
Another option for using Communicator Web Access Controls to login to Communicator Web Access
is to use the LogonByFORM, LogonByIWA or LogonBySSO methods on the
Microsoft.Rtc.WebControl.LoginCtrl control. The LogonByFORM method requires the input of user
credentials, whereas the other two methods do not. All the three methods are asynchronous. The caller
must provide a callback function in each method call in order for the control to return the result,
namely, a valid session ticket if the user is successfully signed in or an error if the user failed to sign
in. Once the ticket is obtained, it is used to initialize the presence control.
By default, connection is made directly to Communicator Web Access in which the controls are
hosted. In the situation where the connection must go through a proxy, the initialization must be called
explicitly on the proxy server.
When logon finishes, the Communicator Web Access Control will call this function with the following
input parameter:
• ticket: it will be null, if logon failed.
• error: it will be null, if logon succeeded.
For complete code samples and detailed explanation, see the Communicator Web Access (2007
release) AJAX Service SDK.

Note
The Web Controls do not render correctly in a frameset when
viewed in the Safari browser.

Authorization
As a result of a change to the Office Communications Server 2007 schema, Communicator Web
Access (2007 release) no longer must retrieve a user’s SIP URI during sign-in. This means that the
user name and password are the only pieces of information that need to be provided during sign-on.
24 | Microsoft Office Communicator Web Access Authentication Guide

Because Communicator Web Access (2007 release) does not require users to enter their SIP address
when signing in, Communicator Web Access can use the same set of credentials that are used to sign
into other applications. This ability to reuse credentials allows Communicator Web Access to be used
in conjunction with automatic sign-in solutions.
The user must be enabled for Microsoft Office Communications Server 2007 and for remote access in
the Active Directory Users and Computers snap-in for internal and remote access, respectively.