Cwa Alg

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 platformindependent, 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

Unified Communications Managed API (UCMA)

A .NET Framework-based (managed) API for creating and deploying server-like or middletiered real-time communications applications. It is especially useful for application with high scalability requirements. Communicator Web Access is a server-based application that uses UCMA.

Unified Communications Client Platform API

A COM-based API for creating and deploying client side real-time collaboration applications. It is interoperable with the .NET Framework and is 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

Office Communicator API

A COM Automation API to enable programmatic access to Office Communicator. It is useful for applications that extend Office Communicator to offer customized functionalities.

Communicator Web Access AJAX Service API

An AJAX Service-based API for creating browserbased client applications. Communicator Web Access controls are based on the AJAX service API. It is especially useful for applications that must be operating system independent.

Office Communications Server API

For managing server and creating server 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 System

Browser

Authentication Mechanism

Windows® 2000 SP4

Microsoft Internet Explorer® 6 SP1

Forms-based NTLM Custom

Windows XP SP2

Internet Explorer 6 SP2 Windows Internet Explorer 7 Firefox 2.0.latest

Forms-based NTLM Kerberos Custom

Authorization| 5

Windows Vista™

Internet Explorer 7 Firefox 2.0.latest

Forms-based NTLM 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

Safari 2.0.latest

Forms-based Kerberos Custom

Firefox 2.0.latest

Forms-based NTLM Kerberos Custom

Mac OS X 10.4.8

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 formsbased 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. com

isv.contoso.co m

192.168.1 0.1

80/44 3

Communicator Web Access

https://cwa.contos o.com

cwa.contoso. com

192.168.1 0.2

80/44 3

Outlook Web Access

https://owa.contos o.com

mail.contoso. com

192.168.1 0.3

80/44 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-471a8de9-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 acceptImSession

Request acknowledgeSubscr

Request addContact

Request addGroup

Authorization| 19

ibers deleteGroup

deleteContact

conference

initiateImSession

initiateSession

terminateSession

logon

logoff

acceptImSession

terminateImSession

sendInfo

sendMessage

notifyComposing

inviteParticipants

updateContact

updateGroup

publishRawCategori es

ejectParticipant

promoteParticipant

Lock

voIPRedirect

voIPTerminate

voIPRedirectToVoice mail

voIPReplyWithIM

queryPresence

updateContainer

publishSelfPresence

subscribePresence

unSubscribePresenc e

search

The following code snippet gives an example. <securityMode>private <userStateAvailability>3500 < queryPresence rid="2"> sip:[email protected] sip:[email protected]

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">

Do not use the following line of code in the Web page.

Authorization| 23

<script src="http://app/WebControls/code.aspx"> Or <script src="http://202.3.4.5/WebControls/code.aspx">

•

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.