tibco ...wcf service probe helps to integrate tibco activematrix® service performance manager with...

TIBCO ActiveMatrix®

Management Agent for WCF

User’s GuideSoftware Release 1.2.0July 2009

Important Information

SOME TIBCO SOFTWARE EMBEDS OR BUNDLES OTHER TIBCO SOFTWARE. USE OF SUCH EMBEDDED OR BUNDLED TIBCO SOFTWARE IS SOLELY TO ENABLE THE FUNCTIONALITY (OR PROVIDE LIMITED ADD-ON FUNCTIONALITY) OF THE LICENSED TIBCO SOFTWARE. THE EMBEDDED OR BUNDLED SOFTWARE IS NOT LICENSED TO BE USED OR ACCESSED BY ANY OTHER TIBCO SOFTWARE OR FOR ANY OTHER PURPOSE.USE OF TIBCO SOFTWARE AND THIS DOCUMENT IS SUBJECT TO THE TERMS AND CONDITIONS OF A LICENSE AGREEMENT FOUND IN EITHER A SEPARATELY EXECUTED SOFTWARE LICENSE AGREEMENT, OR, IF THERE IS NO SUCH SEPARATE AGREEMENT, THE CLICKWRAP END USER LICENSE AGREEMENT WHICH IS DISPLAYED DURING DOWNLOAD OR INSTALLATION OF THE SOFTWARE (AND WHICH IS DUPLICATED IN LICENSE.PDF) OR IF THERE IS NO SUCH SOFTWARE LICENSE AGREEMENT OR CLICKWRAP END USER LICENSE AGREEMENT, THE LICENSE(S) LOCATED IN THE “LICENSE” FILE(S) OF THE SOFTWARE. USE OF THIS DOCUMENT IS SUBJECT TO THOSE TERMS AND CONDITIONS, AND YOUR USE HEREOF SHALL CONSTITUTE ACCEPTANCE OF AND AN AGREEMENT TO BE BOUND BY THE SAME.This document contains confidential information that is subject to U.S. and international copyright laws and treaties. No part of this document may be reproduced in any form without the written authorization of TIBCO Software Inc.TIB, TIBCO, TIBCO Adapter, Predictive Business, Information Bus, The Power of Now, TIBCO ActiveMatrix BusinessWorks, TIBCO Administrator, TIBCO Runtime Agent, TIBCO Enterprise Message Service, TIBCO Designer, TIBCO ActiveMatrix, TIBCO ActiveMatrix Policy Manager are either registered trademarks or trademarks of TIBCO Software Inc. in the United States and/or other countries.EJB, Java EE, J2EE, and all Java-based trademarks and logos are trademarks or registered trademarks of Sun Microsystems, Inc. in the U.S. and other countries.All other product and company names and marks mentioned in this document are the property of their respective owners and are mentioned for identification purposes only.THIS SOFTWARE MAY BE AVAILABLE ON MULTIPLE OPERATING SYSTEMS. HOWEVER, NOT ALL OPERATING SYSTEM PLATFORMS FOR A SPECIFIC SOFTWARE VERSION ARE RELEASED AT THE SAME TIME. SEE THE README.TXT FILE FOR THE AVAILABILITY OF THIS SOFTWARE VERSION ON A SPECIFIC OPERATING SYSTEM PLATFORM.THIS DOCUMENT IS PROVIDED “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT.THIS DOCUMENT COULD INCLUDE TECHNICAL INACCURACIES OR TYPOGRAPHICAL ERRORS. CHANGES ARE PERIODICALLY ADDED TO THE INFORMATION HEREIN; THESE CHANGES WILL BE INCORPORATED IN NEW EDITIONS OF THIS DOCUMENT. TIBCO SOFTWARE INC. MAY MAKE IMPROVEMENTS AND/OR CHANGES IN THE PRODUCT(S) AND/OR THE PROGRAM(S) DESCRIBED IN THIS DOCUMENT AT ANY TIME.THE CONTENTS OF THIS DOCUMENT MAY BE MODIFIED AND/OR QUALIFIED, DIRECTLY OR INDIRECTLY, BY OTHER DOCUMENTATION WHICH ACCOMPANIES THIS SOFTWARE, INCLUDING BUT NOT LIMITED TO ANY RELEASE NOTES AND "READ ME" FILES.Copyright © 2008-2009 TIBCO Software Inc. ALL RIGHTS RESERVED.TIBCO Software Inc. Confidential Information

| iii

Contents

Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . vii

Changes from the Previous Release of this Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . viii

Related Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ixTIBCO ActiveMatrix Management Agent for WCF Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ixOther TIBCO Product Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ixThird Party Documentation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ix

Typographical Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xi

How to Contact TIBCO Support. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiii

Chapter 1 Introduction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

Product Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

Prerequisites and Dependencies. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

Deployment Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

Combination Scenarios . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8WCF Calls WCF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8WCF Calls BusinessWorks. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8BusinessWorks Calls WCF. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9ActiveMatrix Node Calls WCF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9WCF Calls ActiveMatrix Node . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

Availability of Policy Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

TIBCO ActiveMatrix Policy Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12Service Status Indicators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

TIBCO ActiveMatrix Service Performance Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13Monitoring Web Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

WCF Custom Security Permissions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

Chapter 2 Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

Navigating the Installation Directories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

Configuration Checklist . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

Adding Management Agent for WCF Snap-in to MMC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

Configuring Management Agent for WCF and WCF Service Probe . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20Policy Agent Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20Configuring the WCF Service Probe . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

TIBCO ActiveMatrix Management Agent for WCF User’s Guide

iv | Contents

Creating an AMMA Agent Instance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

Chapter 3 Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

Starting the Management Agent and WCF Service Probe . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

Stopping the Management Agent and WCF Service Probe . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

Removing the Management Agent for WCF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

Chapter 4 Security Context . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40Background . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40Capabilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40Implementation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

Programmer’s Checklist for Security Context . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41Install . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41Compile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41Deploy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

Enabling the Security Context API: Administrative Task . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42

SecurityContext . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43SecurityContext.GetAttributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44SecurityContext.GetRoles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45SecurityContext.SetSecurityContext . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46

Custom Metrics on Security Context propagated by TIBCO ActiveMatrix Policy Manager. . . . . . . . . . . . . . . . . . 47Authentication Policy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47Custom Metrics Script Example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48

Appendix A Registering the .Net Keystore Set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52Supported Platform . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52

Registering .Net Keystore Set. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53Register .Net Certificate Stores . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53Registering ASP.NET 2.0 with IIS and WCF handler for .svc extension . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56

Appendix B Registering ASP.NET 2.0 with IIS and WCF Handler for .svc Extension . . . . . . . 59

Steps to Register ASP.NET 2.0 with IIS and WCF handler for .svc extension . . . . . . . . . . . . . . . . . . . . . . . . . . . 60To register all ASP.NET extension in IIS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60To register WCF handler for .svc extension in IIS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60

Appendix C Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61


Contents | v

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65


vi | Contents


| vii

Preface

TIBCO ActiveMatrix® Management Agent for WCF extends policy enforcement and monitoring to services deployed using Microsoft WCF (Windows Communication Foundation) in IIS (Microsoft Internet Information Services) Server. The management agent is a plug-in component within WCF components, and provides integration with TIBCO ActiveMatrix Policy Manager and TIBCO ActiveMatrix Service Performance Manager.

WCF Service Probe helps to integrate TIBCO ActiveMatrix® Service Performance Manager with TIBCO ActiveMatrix® Management Agent for WCF to monitor and manage WCF (Window Communication Foundation) services.

Readers of this document must already be familiar with TIBCO ActiveMatrix Policy Manager software, TIBCO ActiveMatrix Service Performance Manager software and with Windows Communication Foundation (WCF) software.

Topics

• Changes from the Previous Release of this Guide, page viii

• Related Documentation, page ix

• Typographical Conventions, page xi

• How to Contact TIBCO Support, page xiii


viii | Changes from the Previous Release of this Guide

Changes from the Previous Release of this Guide

This section itemizes the major changes from the previous release of this guide.

WCF Service Probe

• This release features the WCF Service Probe for monitoring the WCF services in the TIBCO ActiveMatrix Service Performance Manager dashboard.


Preface | ix

Related Documentation

This section lists documentation resources you may find useful.

TIBCO ActiveMatrix Management Agent for WCF DocumentationThe following documents form the TIBCO ActiveMatrix Management Agent for WCF documentation set:

• TIBCO ActiveMatrix Management Agent for WCF Installation This book presents instructions for installing the product.

• TIBCO ActiveMatrix Management Agent for WCF User’s Guide This book describes ActiveMatrix Management Agent for WCF software, and presents instructions for configuring and using the product.

• TIBCO ActiveMatrix Management Agent for WCF Samples This book includes instructions for sample example that is included in the release.

• TIBCO ActiveMatrix Management Agent for WCF Release Notes Read the release notes for a list of new and changed features. This document also contains lists of known issues and closed issues for this release.

Other TIBCO Product DocumentationYou may find it useful to read the documentation for the following TIBCO products:

• TIBCO ActiveMatrix® Policy Manager

• TIBCO EMS Transport Channel for WCF

• TIBCO ActiveMatrix® Service Grid

• TIBCO ActiveMatrix® Registry

• TIBCO Enterprise Message Service™

• TIBCO Administrator™

• TIBCO ActiveMatrix® Service Performance Manager

Third Party Documentation

Microsoft IIS 6.0Documentation

http://www.microsoft.com/technet/prodtechnol/WindowsServer2003/Library/IIS/003ed2fe-6339-4919-b577-6aa965994a9b.mspx?mfr=true




x | Related Documentation

Microsoft WCFDocumentation

http://msdn.microsoft.com/en-us/library/aa388579(vs.85).aspx

Web ServicesStandards

Management Agent for WCF supports web services standards sponsored by the following standards bodies:

• World Web Web Consortium web services activityhttp://www.w3.org/2002/ws/

— WSDL 1.1 http://www.w3.org/TR/wsdl

• OASIS web services committeeshttp://www.oasis-open.org/committees/tc_cat.php?cat=ws

• Web Services Interoperability http://www.ws-i.org/


http://msdn.microsoft.com/en-us/library/aa388579(vs.85).aspx

http://www.w3.org/2002/ws/

http://www.w3.org/TR/wsdl

http://www.oasis-open.org/committees/tc_cat.php?cat=ws

http://www.ws-i.org/

Preface | xi

Typographical Conventions

The following typographical conventions are used in this manual.

Table 1 General Typographical Conventions

Convention Use

TIBCO_HOME All TIBCO products are installed under the same directory. This directory is referenced in documentation as TIBCO_HOME. The value of TIBCO_HOME depends on the operating system. For example, on Windows systems, the default value is C:\tibco.

code font Code font identifies commands, code examples, filenames, pathnames, and output displayed in a command window. For example:

Use MyCommand to start the foo process.

bold code

font Bold code font is used in the following ways:

• In procedures, to indicate what a user types. For example: Type admin.

• In large code samples, to indicate the parts of the sample that are of particular interest.

• In command syntax, to indicate the default parameter for a command. For example, if no parameter is specified, MyCommand is enabled: MyCommand [enable | disable]

italic font Italic font is used in the following ways:

• To indicate a document title. For example: See TIBCO ActiveMatrix BusinessWorks Concepts.

• To introduce new terms For example: A portal page may contain several portlets. Portlets are mini-applications that run in a portal.

• To indicate a variable in a command or code syntax that you must replace. For example: MyCommand pathname

Key combinations

Key name separated by a plus sign indicate keys pressed simultaneously. For example: Ctrl+C.

Key names separated by a comma and space indicate keys pressed one after the other. For example: Esc, Ctrl+Q.

The note icon indicates information that is of special interest or importance, for example, an additional action required only in certain circumstances.


xii | Typographical Conventions

The tip icon indicates an idea that could be useful, for example, a way to apply the information provided in the current section to achieve a specific result.

The warning icon indicates the potential for a damaging situation, for example, data loss or corruption if certain steps are taken or not taken.

Table 1 General Typographical Conventions (Cont’d)

Convention Use

Table 2 Syntax Typographical Conventions

Convention Use

[ ] An optional item in a command or code syntax.

For example:

MyCommand [optional_parameter] required_parameter

| A logical OR that separates multiple items of which only one may be chosen.

For example, you can select only one of the following parameters:

MyCommand para1 | param2 | param3

{ } A logical group of items in a command. Other syntax notations may appear within each logical group.

For example, the following command requires two parameters, which can be either the pair param1 and param2, or the pair param3 and param4.

MyCommand {param1 param2} | {param3 param4}

In the next example, the command requires two parameters. The first parameter can be either param1 or param2 and the second can be either param3 or param4:

MyCommand {param1 | param2} {param3 | param4}

In the next example, the command can accept either two or three parameters. The first parameter must be param1. You can optionally include param2 as the second parameter. And the last parameter is either param3 or param4.

MyCommand param1 [param2] {param3 | param4}


Preface | xiii

How to Contact TIBCO Support

For comments or problems with this manual or the software it addresses, please contact TIBCO Support as follows.

• For an overview of TIBCO Support, and information about getting started with TIBCO Support, visit this site:

http://www.tibco.com/services/support

• If you already have a valid maintenance or support contract, visit this site:

https://support.tibco.com

Entry to this site requires a user name and password. If you do not have a user name, you can request one.


http://www.tibco.com/services/support

https://support.tibco.com

xiv | How to Contact TIBCO Support


| 1

Chapter 1 Introduction

This chapter presents the Management Agent for WCF, its limitations, prerequisites and general operation.

Topics

• Product Overview, page 2

• Prerequisites and Dependencies, page 3

• Limitations, page 5

• Deployment Structure, page 6

• Combination Scenarios, page 8

• Availability of Policy Types, page 11

• TIBCO ActiveMatrix Policy Manager, page 12

• TIBCO ActiveMatrix Service Performance Manager, page 13

• WCF Custom Security Permissions, page 14


2 | Chapter 1 Introduction

Product Overview

TIBCO ActiveMatrix® Management Agent for WCF extends policy management to web services deployed using Microsoft WCF (Windows Communication Foundation) in IIS (Microsoft Internet Information Services) Server. The management agent is a plug-in component within WCF components, and cooperates with TIBCO ActiveMatrix Policy Manager.

Windows Communication Foundation (WCF) is Microsoft's unified programming model for building service-oriented applications with managed code. It extends the .NET Framework to enable developers to build secure and reliable transacted Web services that integrate across platforms and interoperate with existing investments.

TIBCO ActiveMatrix Management Agent for WCF provides agent software that:

• Extends policy-based governance to WCF services deployed in Microsoft Internet Information Services Server (IIS).

• Provides tools to configure, deploy, and run agents.

• Extends management and monitoring of the WCF services deployed in IIS and standalone server or Windows console using the TIBCO ActiveMatrix Service Performance Manager dashboard through the WCF Service Probe feature.

The Management Agent for WCF relies on ActiveMatrix Policy Manager console to define policies, and works in concert with ActiveMatrix Policy Manager central services to distribute policies to agents.

For example, if you have previously developed and deployed services using Microsoft's WCF model, you can still use policies to govern them as part of an integrated ActiveMatrix SOA solution.

In the XACML usage model, each management agent acts as a policy decision point (PDP) and a policy enforcement point (PEP). Meanwhile, Policy Manager software provides the policy administration point (PAP) and policy repository point (PRP) components.


Prerequisites and Dependencies | 3

Prerequisites and Dependencies

General Management Agent for WCF requires the following software:

• TIBCO ActiveMatrix Policy Manager 3.0—It is optional for installing Management Agent for WCF but required policy managing for WCF services. If you want to policy manage WCF services, then Policy Manager must be installed before configuring the Agent instance.

• Microsoft Windows Server 2003 Tools

• Microsoft Web Services Enhancements (WSE) v2.0 SP2

• Microsoft SQL Server 2005 Enterprise Edition or Oracle 10g Release 1 (10.1) or 2 (10.2)

• Microsoft Management Console 3.0 (MMC)

• Microsoft Internet Information Services Server (IIS) (optional)

You must install and configure this feature pack before installing Management Agent for WCF.

WCF Service Probe requires the following:

• TIBCO ActiveMatrix Service Performance Manager 1.2 - for managing services.

• TIBCO Enterprise Message Service™ version 4.4.3 or newer

Installation of the C# Client and its installation in the GAC depends on the version of TIBCO Enterprise Message Service as follows:

• When using TIBCO Enterprise Message Service 4.4.3:

a. Select Custom installation of TIBCO Enterprise Messaging Service.

b. Select C# Client from the list of features that can be installed. (Selecting a "Typical" installation will also install the C# Client.)

c. After installing the C# Client, you must install the C# Client’s DLL (TIBCO.EMS.dll) in the GAC.

This can be done either by using the Windows Global Assembly Cache Utility (gacutil) or you can drag and drop the TIBCO.EMS.dll file from

You must have TIBCO Enterprise Message Service C# Client on your machine, if WCF Service probe feature is selected while installing the WCF agent. However, the only feature of TIBCO Enterprise Message Service required by WCF Service probe is the C# Client. Hence, the C# Client must also be installed in the Windows Global Assembly Cache (GAC).



the EMSInstallDir\clients\cs folder to the C:\WINDOWS\assembly folder. The assembly folder is a special folder where .NET Framework stores the assemblies for the GAC.

(You must drag and drop the file into the assembly folder as you cannot opy it.)

• When using TIBCO Enterprise Message Service 5.x:

Install the "runtime" version, which automatically installs the C# Client’s DLL (TIBCO.EMS.dll) in the GAC.

TIBCO EnterpriseMessaging

Service

Only if your WCF services communicate using SOAP/JMS as the transport, you need to install the TIBCO EMS Transport Channel for WCF product for messaging. See TIBCO EMS Transport Channel for WCF documentation for more details.

Platform In this release, Management Agent for WCF supports only one operating system and hardware platform—Windows 2003 Server.


Limitations | 5

Limitations

• TIBCO ActiveMatrix Management Agent for WCF does not start and initialize itself once Microsoft Internet Information Services Server (IIS) is restarted.

You can send the request to any service deployed in the corresponding Virtual Directory to start the agent. The requested service need not be a managed service. The request can be sent for a WSDL too.

• TIBCO ActiveMatrix Management Agent for WCF supports only basic http binding.

• WCF https services can be managed from Management Agent for WCF snap-in to MMC only using the file based approach.

• For authentication by Identity Management System (IMS) policy, use SOAP headers to send user credentials.



Deployment Structure

The Management Agent for WCF deploys the following components:

• Agent The agent is a message handler, which intercepts messages and enforces policies for web services deployed within the IIS server.

• Management Service The management service is part of agent. It is started when the agent starts up. The management service has two main tasks:

— It acts as a communications intermediary between Policy Manager and the agent. Examples include requests to manage endpoints; requests to add, delete, enable and disable policies; requests to query log data.

— It responds to other management agents when they request information required to construct implicit complementary policies for client-side policy enforcement. (For background information about complementary policies, see TIBCO ActiveMatrix Policy Manager Policy Reference.)

• Agent Snap-in for MMC This component lets you configure the agent and register endpoints of services deployed within the IIS server or as Standalone Service.

• WCF Service Probe This component lets you integrate TIBCO ActiveMatrix Service Performance Manager with TIBCO ActiveMatrix Management for WCF to monitor and manage WCF Services. The WCF Service Probe does not publish the details about the policies applied. This is done by the Policy Agent. However, it is responsible for capturing all the lifecycle events of the Service.

WCF Agent provides information to the Service probe on:

• Service Probe Start and Stop Event. (Start after Agent Start and Stop before Agent gets down).

• Application Domain, Deployment Type (as "IIS" for IIS hosted services and as "Windows Console Application" for Standalone i.e. service hosted as console application or as Windows service), Assembly, OS and Host name.

• Discover all Services of application domain, after the Service Probe Start event.

— Application Domain, Deployment type, Assemblies, and Services details

When the Service Probe is configured with SSL enabled admin, the user must import the administrator’s public certificate under the Trusted Root CA of Windows certificate store.


Deployment Structure | 7

• Assembly load and unload event, Discover Services.

— Application Domain, Deployment type, Assembly, and Services details

Figure 1 illustrates this structure, and the communication flows involved in these tasks.

Figure 1 Deployment Structure

In case of IIS, discovers all the services deployed in a virtual directory whereas for standalone services, discovers all the services from the host directory.

Agent

W CF Services

Management Service

Consumer

Embedded Client Side

Proxy Agent

Enforce Policy

Register services

W indows 2003 Server

Policy Manager

Enforce Policy

Server Side Agent

Management Agent for W CF Snap-in

W CF Services

PM Requests

Service Probe

JMS (EMS Server)

ActiveMatrix Admin Server

Login to ActiveMatrix Admin Server Retrieve Service probe monitoring configuration and Custom Metrics.

Receive notification for Service probe monitoring configuration changes and Custom metric (add/delete/edit)Connect to JMS (EMS Server) and publish stats

Publish notification for Service Probe monitoring configuration changes and Custom metric (add/delete/edit)



Combination Scenarios

Management Agent for WCF enables interoperation with services deployed using TIBCO ActiveMatrix Service Grid and TIBCO BusinessWorks. This section presents several use cases of Management Agent for WCF in combination with these other products.

WCF Calls WCFFigure 2 highlights two roles of the management agent:

• Embedded Client Side Proxy Agent intercepts outbound request messages from a consumer and inbound reply or fault messages returning from the provider.

• Server Side agent intercepts inbound request messages to a provider and outbound reply or fault messages returning to the consumer.

Figure 2 WCF Calls WCF

WCF Calls BusinessWorksProviders deployed in BusinessWorks (as a stand-alone product) require an instance of TIBCO ActiveMatrix Policy Agent to act as a provider-side proxy agent.

Embedded Client Side Proxy agents do not negotiate with other agents to automatically apply complementary client side policies. For a complete explanation, see Chapter 6, Cryptography in TIBCO ActiveMatrix Policy Manager Policy Reference.

Windows 2003 Server

EmbeddedClient Side

Proxy Agent

Windows 2003 Server

Server-Side Agent

ServicesConsumer


Combination Scenarios | 9

Figure 3 WCF Calls BusinessWorks

BusinessWorks Calls WCFConsumers deployed in BusinessWorks (as a stand-alone product) require an instance of TIBCO ActiveMatrix Policy Agent to act as a client-side proxy agent.

Proxy agents do not negotiate with other agents to automatically apply complementary client-side policies. For a complete explanation, see Chapter 6, Cryptography in TIBCO ActiveMatrix Policy Manager Policy Reference.

Figure 4 BusinessWorks Node Calls WCF

ActiveMatrix Node Calls WCFConsumers deployed in ActiveMatrix Service Grid require an instance of TIBCO ActiveMatrix Policy Agent to act as a client-side proxy agent.

BusinessWorksWindows 2003 Server

Consumer

Server-Side Proxy Agent

Provider

EmbeddedClient-Side

Proxy Agent

W indows 2003 Server

Server-Side Agent

BusinessW orks

Consumer

Client-Side

Proxy AgentProvider



Proxy agents do not negotiate with other agents to automatically apply complementary client-side policies. For a complete explanation, see Chapter 6, Cryptography in TIBCO ActiveMatrix Policy Manager Policy Reference.

Figure 5 ActiveMatrix Node Calls WCF

WCF Calls ActiveMatrix NodeOn consumer side, the Embedded Client Side Proxy Agent feature exposes the service reference endpoint on which you can apply the explicit client-side policies.

Figure 6 WCF Calls ActiveMatrix Node

This is true only for ActiveMatrix Service Grid version 2.0.x and below. In ActiveMatrix Service Grid 2.1, you do not need the instance of Policy Agent (as shown in Figure 5), as it already has an embedded client side proxy agent. This agent, like proxy agent, does not negotiate with other agents to automatically apply the complementary policies.

Windows 2003 Server

Server-Side Agent

ActiveMatrix Node

Consumer Provider

EmbeddedClient-Side

Proxy Agent

Windows 2003 Server ActiveMatrix Node

Consumer Provider

Server-Side Agent

EmbeddedClient-Side

Proxy Agent


Availability of Policy Types | 11

Availability of Policy Types

Management Agent for WCF supports the following policy types:

• Logging policies—no restrictions

• Authentication policies—no support for SiteMinder

• Authorization policies—no restrictions

• Censor Response policies—no restrictions

• Credential Mapping policies

• Cryptographic policies—no restrictions

Unavailable Policy Types

Management Agent for WCF does not support the following policy types:

• Routing policies



TIBCO ActiveMatrix Policy Manager

Service Status IndicatorsThe Policy Manager console displays information about WCF services and the policies that pertain to them.

Policy Manager indicates the status of a service with a colored dot (green or red).


TIBCO ActiveMatrix Service Performance Manager | 13

TIBCO ActiveMatrix Service Performance Manager

The rules are triggered, actions are enabled and alerts are sent based on the condition defined on the services. The dashboard shows all the output data related to rules, services, and infrastructure. For detailed information on "SIBCO ActiveMatrix Service Performance Manager Dashboard", refer to the TIBCO ActiveMatrix Service Performance Manager User’s Guide.

Monitoring Web ServiceService information is logged and is viewable to the user in the SPM dashboard. For each virtual directory incase of IIS hosted service and host directory incase of standalone service, all the information is logged in a common node.

To monitor the web service and to initialize the Service Probe, the user must have virtual directory access to the WSDL or .svc file.



WCF Custom Security Permissions

If the Management Agent for WCF runs in IIS server, the security environment for agent is determined by the user profile that is used for running IIS server. When starting up, the agent starts the management service. The management service of the agent listens to management requests from Policy Manager and other agents using a http port. Explicit granting of permissions to this http may be required.

• To grant permissions for a http port to a user, first find out the SID for the user. The SID for the user can be found out by running the command:

getsid \\<machine name> <user name> \\<machine name> <user name>

• Then grant permission to a http port using the command:

httpcfg set urlacl /u http://+:<agent port>/ /a D:(A;;GX;;;<user SID>)

When using X.509 certificates from Windows certificate store, you might need to grant authority to a certificate for user profile, use the command

winhttpcertcfg –g –a <user name> -c <certificate store> -s <certificate name> -p <certificate password>

While communicating with the administrator, the user must import the administrator’s public certificate under the Windows certificate store.


| 15

Chapter 2 Configuration

This chapter presents the steps required to configure Management Agent for WCF and WCF Service Probe.

Topics

• Navigating the Installation Directories, page 16

• Configuration Checklist, page 17

• Adding Management Agent for WCF Snap-in to MMC, page 18

• Configuring Management Agent for WCF and WCF Service Probe, page 20


16 | Chapter 2 Configuration

Navigating the Installation Directories

Table 3 presents the organization of the directories associated with Management Agent for WCF software.

Table 3 Management Agent for WCF Installation Directories

Directory Content

Directories associated with this product (ActiveMatrix Management Agent for WCF)tibco tibco_home, the root for TIBCO software

amma-wcf ActiveMatrix Management Agent for WCF software

1.2 Releaseconfig

bin Agent DLLsdocs

uninstaller_archives

Management Agent for WCF documentation

Uninstaller scripts and datasamples Samples

application

resources Setup data templates and Management Agent for WCF configuration files


Configuration Checklist | 17

Configuration Checklist

Before assigning policies to WCF services, you must explicitly register and manage those services. Using Management Agent for WCF Snap-in, you can register and manage each service individually.

Table 4 is a checklist of steps for configuring Management Agent for WCF software. Table 4 summarizes each step briefly; further detail is available in subsequent sections of this book.

Table 4 Installation and Configuration Checklist

Step Notes

1. Install the product See TIBCO ActiveMatrix Management Agent for WCF Installation.

2. Adding Management Agent for WCF Snap-in to MMC

3. Configuring Management Agent for WCF and WCF Service Probe

See Configuring Database on page 21.

Configuring Database on page 21

Configuring Message Inspection Library on page 22

4. Status—Displays the current status of the managed WCF services.



Adding Management Agent for WCF Snap-in to MMC

To add Management Agent for WCF Snap-in to MMC, you need to perform the following steps only once.

1. Open the command prompt at location C:\WINDOWS\Microsoft.NET\Framework\v2.0.50727

2. Install Snap-in by executing the command:

InstallUtil TIBCO_HOME\amma-wcf\<version_num>\bin\Tibco.PolicyAgent.SnapIn.dll

3. Make sure that Snap-in is installed properly.

Once installed, the snap-in can be launched using the following steps:

1. Launch Microsoft Management Console (MMC):

— Select Start > Run.

— Enter mmc.

A management console window is displayed.

2. To add the Snap-in for policy agent, select File -> Add/Remove Snap-in….

An Add/Remove Snap-in window is displayed.

3. Press Add on the Standalone tab.

The Add Standalone Snap-in window is displayed.

4. From the list of snap-ins, select TIBCO AMMA for WCF.

5. Click OK.

6. After policy agent snap-in is launched for the first time, it can be saved as a MMC document file.

a. Select File > Save As.

b. Navigate to the TIBCO_HOME\amma-wcf\<version_num>\bin directory.

c. Enter the file name as Tibco.PolicyAgent.SnapIn.msc.

d. Click Save.

You can launch the Snap-in for Policy Agent next time by double-clicking the Tibco.PolicyAgent.SnapIn.msc file in TIBCO_HOME\amma-wcf\<version_num>\bin.


Adding Management Agent for WCF Snap-in to MMC | 19

If you want to uninstall the snap-in, run the following command from the C:\WINDOWS\Microsoft.NET\Framework\v2.0.50727 directory:

InstallUtil /u TIBCO_HOME\amma-wcf\<version_num>\bin\Tibco.PolicyAgent.SnapIn.dll



Configuring Management Agent for WCF and WCF Service Probe

Before starting the Management Agent for WCF, the WCF agent needs to be configured using the MMC Snap-in.

To launch TIBCO ActiveMatrix Management Agent for WCF Snap-in in MMC,

1. Open Windows Explorer and select the TIBCO_HOME\amma-wcf\<version_num>\bin folder.

2. Double-click Tibco.PolicyAgent.SnapIn.msc.

TIBCO AMMA for WCF Snapin - Console appears as shown below.

Figure 7 TIBCO ActiveMatrix Management Agent for WCF Snap-in in MMC

The configuration of policy agent displays the following options in the right pane:

• Policy Agent Instances

• Policy Agent Configuration

• Service Probe Configuration

Before starting TIBCO ActiveMatrixManagement Agent for WCF, you need to configure it using the Policy Agent Configuration option.

Policy Agent ConfigurationThe policy agent configuration setup for WCF Management Agent for WCF consists of the following tasks:

• Configuring Database

• Configuring Message Inspection Library


Configuring Management Agent for WCF and WCF Service Probe | 21

Figure 8 Policy Agent Configuration

Configuring Database

Policy Manager uses database to store information about services and policies. The policy agent uses the database only when the logging policy is configured to store the message logs in the database. Otherwise, Policy Agents (including Management Agent for WCF) always stores the services and policies in its local cache file.

TIBCO ActiveMatrix Management Agent for WCF uses Microsoft SQL Server or Oracle as the database. See TIBCO ActiveMatrix Management Agent for WCF Installation for details on the supported database versions.



Using the Database Configuration dialog, you can configure the Management Agent for WCF to connect to the database.

Enter values for the following database configuration parameters:

• DB Driver—Select OleDbConncetion as the default driver to access the database.

• Connection—Specify the following parameters to connect to a database:

Provider—Enter the database connection name.

DataSource—Specify the database server name.

Initial Catalog—Enter the name of the database that can be used with Management Agent for WCF.

• DB User—Specify the user name to connect to the database.

• Password—Specify the password to authenticate the DB User.

After you enter all the above details, click Update Config to save the user input. It writes and stores database configuration from the AP_Plug-in_Agent.defaults file available in the TIBCO_HOME\amma-wcf\<version_num>\WEB-INF\application\resources folder.

Configuring Message Inspection Library

The WCF Agent Library for Message Inspector enables the Management Agent for WCF to intercept and process request/reply messages for a WCF service.

In order for Management Agent for WCF to intercept WCF service messages, you need to:

• Update the machine.config file available in the c:\WINDOWS\Microsoft.NET\Framework\v2.0.50727\CONFIG folder to use the message inspection library.

Updating Machine.Config

In this step, update the machine configuration file to enable interception of WCF service messages using the WCF Agent’s message inspection library.

Keep the Initial Catalog field empty if you are using Oracle database.

If you change any of the above parameters, click Reload to update the existing parameters and to connect to the database.



In the Update MACHINE.CONFIG dialog, click Update to update the machine.config file.

It updates the system.ServiceModel section in machine.config file located in the C:\WINDOWS\Microsoft.NET\Framework\v2.0.50727\CONFIG directory with the information of Management Agent for WCF.

Configuring the WCF Service ProbeConfigure the WCF Service Probe using the SnapIn console by providing the configuration details in the respective fields. See Figure 9.

Figure 9 Service Probe Configurations

When the WCF Management Agent for WCF Snap-in is launched, it detects whether machine configuration file is updated for the Message Inspection Library of WCF Agent. Based on the update status of the machine configuration file, you can update or undo updates in the machine configuration file.



• Incase of multiple ActiveMatrix admins in a cluster,the URLs must use semicolon as a delimiter.

• In order to override the default delimiter (;), the user must update the serviceprobe.config file located under the TIBCO_HOME/amma-wcf/<version_num>/config folder.



Creating an AMMA Agent Instance

To add an Agent instance,

1. Select Policy Agent Instances from the left pane and right-click.

Figure 10 Add Instance from MMC Snap-in

2. Select Add Instance from the popup menu.

A new instance named Added <current time> is added under the AMMA WCF Agent folder in the left pane.

3. Select the Added <current time> agent instance and right-click.

4. Select Rename from the popup menu and enter an instance name.

5. Select new agent instance in the left pane.

The WCF Policy Agent Instance Details for the new instance are displayed in the right pane. You can configure the new AMMA WCF Agent Instance using the following options:

— Configuring Policy Manager

— Managing Services

For every virtual directory in the Microsoft Internet Information Server and every self-hosted service, you must create an agent instance.



Figure 11 AMMA WCF Agent Instance



Configuring Policy Manager

Before configuring the Management Agent for WCF, you must first start the instance of Policy Manager central services to which the management agent will connect.

The configuration validates by contacting central services; if central services are unavailable, the configuration utility reports an error.

To configure the Management Agent for WCF to connect to the host computer on which Policy Manger is installed, provide the following configuration details.

Figure 12 Policy Manager - Policy Agent Configuration

Specify values for the following configuration parameters:

• Policy Manager Machine Name—The machine name on which TIBCO ActiveMatrix Policy Manager is running.

• Policy Manager Port—Socket port used by the Policy Manager services.

• Agent Port—Socket port used by the management service of Management Agent for WCF.

• Cache Dir— The cache directory for Management Agent for WCF. You can Browse and select a directory to be used as the cache directory.

• Service Location—The location of the IIS virtual directory or an executable file.



• Automanage—Allows you to discover and manage services automatically. Only HTTP URL services can be auto-managed using this option. It does not support TEMS WCF services.

• Shared Secret (optional)—It is an optional parameter and enables only after an agent is configured. Set this parameter only after you set and update the above configuration parameters.

The shared secret is used to communicate with Policy Manager. The value of shared secret must be identical to the shared secret value that you supplied to Policy Manager.

The shared secret enables a set of policy components to communicate with one another, while not interfering with other sets of policy components.

— Select Encrypt to supply the shared secret password as an encrypted string.

— Click Set to enable the shared secret for Management Agent for WCF. It first stores the encrypted shared secret in the properties file and then copies the properties files to the trust directory.

The location for the trust directory is TIBCO_HOME\amma-wcf\.trust\pm-host-port (where host and port specify the location of the Policy Manager instance to which the management agent connects).

The values specified for the above options except Shared Secret, are stored in the agent.config file in the TIBCO_HOME\amma-wcf\<version_num>\WEB-INF\application\resources directory. If this file does not exist, the Policy Agent Snap-in creates the configuration file.

The MMC console auto-manages all the discovered services when you click the Update Config button.

However, you must restart the Management Agent for WCF if you enable or disable the Automanage option at runtime. Also, when you update the web.config file to add or remove a service entry, the IIS unloads the AppDomain for that virtual directory and the Management Agent for WCF stops. You need to restart the WCF Agent for these changes to take effect.

If you select Shared Secret, you need to reload the Management Agent for WCF Snap-in.



After you enter all the above details, click Update Config to connect to the machine on which Policy Manager is running. It reads and stores the service instance configuration details from the agent.config file in the TIBCO_HOME\amma-wcf\<version_num>\WEB-INF\application\resources folder.

Once configured, you can update the parameters as follows:

• If you want to change any of the above parameters, click Update Config. If you have edited some fields and did not click Update Config, click Reload to revert to the previous values.

• After editing the parameters, you must click Reload to update the existing parameters and to connect to the WCF Policy Agent instance.

To remove Shared Secret from the WCF Agent Instance, do the following steps:

1. Go to <TIBCO_HOME>\amma-wcf\.trust . The .trust directory has the shared secret file.

2. Delete the pm-host-port folder which resides in the .trust directory.

This will delete the shared secret for a particular instance pointing to a particular Policy Manager.

Managing Services

After the Management Agent for WCF is configured and started, the request and reply messages for WCF services can be intercepted by managing the WCF services.

You can manage WCF services using the Manage Services task option in Management Agent for WCF Snap-in.

You must reload the MMC Console and Management Agent for WCF to get the desired results.

If you remove the shared secret for an instance but the Policy Manager is still using the shared secret, the communication will not work.



Figure 13 Manage Services

To manage services,

1. For Service WSDL Location, enter the WSDL URL for WCF service that needs to be managed. Alternately, you can Browse and select WSDL path for a WCF service.

A WSDL URL for a WCF service can be one of the following:

— http://URL or

— A file or a directory name specified as a simple name or file://URL.

If a directory name is specified, all files with extension .wsdl are read and the specified services are managed.

2. Click Manage to use the specified WSDL URL and manage it using Management Agent for WCF.

Under Managed WSDLs, a list of all successfully managed WCF services is displayed in a grid. The grid shows the following service parameters:

WSDL Path—Displays the WSDL path of the managed WCF services.

Status—Displays the current status of the managed WCF services.

To manage services hosted in multiple virtual directories of Microsoft Internet Information Services Server, you must create multiple AMMA WCF Agent Instances.



3. Click Reference Out to apply embedded client-side proxy policy types to the services being managed.

Reloading the Configuration Parameters

If you change any configuration parameters, click the Reload button to reload the previous configuration parameters set in the tasks, Configuring Database and Configuring Policy Manager, from their respective configuration files.

The configuration for Policy Agent is read from the agent.config file and configuration for database settings is read from the AP_Plug-in_Agent.defaults file available in the TIBCO_HOME\amma-wcf\<version_num>\WEB-INF\application\resources folder.

For any new configuration parameters to take effect, you must restart Management Agent for WCF.


| 33

Chapter 3 Tasks

This chapter presents tasks related to management agents and WCF.

Topics

• Starting the Management Agent and WCF Service Probe, page 34

• Stopping the Management Agent and WCF Service Probe, page 35

• Removing the Management Agent for WCF, page 36


34 | Chapter 3 Tasks

Starting the Management Agent and WCF Service Probe

To initialize the Management Agent for WCF and WCF Service Probe, you need to query WSDL URL for a WCF service which is hosted in IIS server.

To start the agent, perform these steps:

1. Locate the virtual directory on IIS server.

2. Find the name of any WCF service hosted in that virtual directory.

3. Query for that WCF service as follows:

http://machine_name:port_number/virtual_directory/service_name.svc?wsdl

Where,

• machine_name is IIS Server Name

• port_number is port number of the IIS website

If the query is successful, the WSDL is displayed in the browser which means the Management Agent for WCF has started.

If the browser displays an error, it signifies that Management Agent for WCF has not started.


Stopping the Management Agent and WCF Service Probe | 35

Stopping the Management Agent and WCF Service Probe

Stopping an IIS server automatically stops its management agent.

To stop the management agent, reset the IIS server using the command:

iisreset



Removing the Management Agent for WCF

To remove a management agent from MMC, perform these steps:

1. Login as an administrator.

2. Navigate to the TIBCO_HOME\amma-wcf\<version_num>\bin directory.

3. Launch Management Agent for WCF Snap-in in MMC by double-clicking the Tibco.PolicyAgent.SnapIn.msc file.

The configuration of policy agent displays the following options:

— Policy Agent Instances

— Policy Agent Configuration

— Service Probe Configuration

4. From the Policy Agent Instance folder, select the agent instance that you want to remove.

The WCF Policy Agent Instance Details of the selected agent instance are displayed in the right pane. The Manage Services dialog displays the list of WCF services that are being managed by Management Agent for WCF.


Removing the Management Agent for WCF | 37

Figure 14 Manage Services

5. Unregister the Management Agent for WCF by clicking the Unregister button below the Unregister WCF Agent task.

6. Restart IIS server by running the iisreset command.

7. In the TIBCO ActiveMatrix Management Agent for WCF console, double-click the Policy Agent Configuration option from the left panel.

8. Locate the Update MACHINE.CONFIG task and click Remove.

It removes MACHIN.CONFIG modifications related to Management Agent for WCF.

Before performing step 8, you must repeat steps 4 and 5 for all Agent Instances.


| 39

Chapter 4 Security Context

This chapter presents a compact API for accessing and forwarding security context objects, which are associated with message exchanges.

Topics

• Overview, page 40

• Programmer’s Checklist for Security Context, page 41

• Enabling the Security Context API: Administrative Task, page 42

• Custom Metrics on Security Context propagated by TIBCO ActiveMatrix Policy Manager, page 47


40 | Chapter 4 Security Context

Overview

BackgroundSome security policies attach a security context object to each message exchange. Security context objects can contain user role and attribute information. For example, an authentication policy might obtain user roles from an identity management system (IMS). The provider service might access and use this information. Alternatively, another policy at another policy agent might need this same information, and rather than retrieving it from the IMS a second time, it would be more efficient to re-use the information.

CapabilitiesThis chapter presents a .NET API that allows WCF services to access the security context information, and to forward the security context information to another provider for re-use.

Forwarding is always the result of an explicit method call; it is never automatic.

ImplementationThese methods arrange to forward security context information in a message header named com.tibco.security.userinformation.


Programmer’s Checklist for Security Context | 41

Programmer’s Checklist for Security Context

Developers of web service programs can use this checklist during the four phases of the development cycle: installing Management Agent for WCF software, coding your C# program, compiling your C# program, and deploying your program as a WCF service.

Install• Install the Management Agent for WCF software release, which automatically

includes the .NET assembly file Tibco.PolicyAgent.dll, which contains class Tibco.PolicyAgent.Security.SecurityContext.

Code• Use namespace Tibco.PolicyAgent.Security

• Use appropriate methods from SecurityContext class in the code.

Compile• Reference to assembly Tibco.PolicyAgent.dll needs to be added for

successful compilation.

DeployYou must ensure that Tibco.PolicyAgent.DLL is available in web service’s bin directory or in GAC.



Enabling the Security Context API: Administrative Task

SecurityContext methods require that the management agent’s forwardUserInfoContextDoc parameter is set to true. You must explicitly set this parameter in each management agent instance that manages a service that uses any SecurityContext methods.

For complete instructions, see the task Forwarding User Information in TIBCO ActiveMatrix Policy Manager User’s Guide.


SecurityContext | 43

SecurityContextClass

Declaration class Tibco.PolicyAgent.Security.SecurityContext

Purpose Interface methods to access and forward security-related information associated with message exchanges.

Remarks Programs do not create instances of SecurityContext. Instead, WCF service programs use its static methods to get information from existing message exchange objects, and transfer (forward) security context information to new outbound request messages.

Method Description Page

SecurityContext.GetAttributes Get user attributes from the security context in a web service context object.

44

SecurityContext.GetRoles Get user roles from the security context in a web service context object.

45

SecurityContext.SetSecurityContext Forward the security context object to another web service provider.

46



SecurityContext.GetAttributesMethod

Declaration static System.Collections.Generic.Dictionary.<String,String> GetAttributes

Purpose Get user attributes from the security context in a web service context object.


SecurityContext.GetRoles | 45

SecurityContext.GetRolesMethod

Declaration static System.Collections.Generic.<String> GetRoles

Purpose Get user roles from the security context in a web service context object.



SecurityContext.SetSecurityContextMethod

Declaration static void SetSecurityContext(ref System.ServiceModel.Channels.Message message)

static void SetSecurityContext(System.Xml.XmlDocument message)

Purpose Forward the security context object to another web service provider.

Remarks This method copies the security context information from a web service context object onto an outbound request message.

Parameter Descriptionmessage Copy the security context to this outbound request

message.


Custom Metrics on Security Context propagated by TIBCO ActiveMatrix Policy Manager | 47

Custom Metrics on Security Context propagated by TIBCO

ActiveMatrix Policy Manager

If you use TIBCO ActiveMatrix Policy Manager for Authentication policies and enable Security Context Propagation (see ActiveMatrix Policy Manager documentation for details), you can register custom metrics using ActiveMatrix Service Performance Manager to extract user information forwarded by the Policy.

Authentication PolicyIf an authentication policy was applied in the TIBCO ActiveMatrix Policy Manager, refer to the user information is available in the Amberpoint User Information document.

Here is a snippet of the Amberpoint user information document:

<?xml version="1.0" encoding="UTF-8"?>

<ap:userInformation

xmlns:ap="http://namespace.amberpoint.com/amf">

<ap:userIdentity>pmuser</ap:userIdentity>

<ap:userRoles />

<ap:clientAddress>10.97.98.163</ap:clientAddress>

<ap:claimedIdentity

xmlns:ap="http://namespace.amberpoint.com/amf"

authenticationMechanism="urn:oasis:names:tc:SAML:2.0:ac:classes:Pa

ssword"

authenticatorRef="AuthnProvider_794A62E4_9F3A_11DD_9CF5_76AFA2FFAA

77"

authenticationStatus="success"

type="com.amberpoint.security.authn.identity.BaseClaimedIdentity"

authenticationProviderHash="244139661">

<ap:userIdentity>pmuser</ap:userIdentity>

<ap:userRoles>

<ap:role name="Accounting Managers"

attributeInfoProviderRef="AttrInfoProvider_794A62E4_9F3A_11DD_9CF5

_76AFA2FFAA77" />

<ap:role name="SeanPMGroup2"

attributeInfoProviderRef="AttrInfoProvider_794A62E4_9F3A_11DD_9CF5

_76AFA2FFAA77" />



</ap:userRoles>

<ap:userAttributes />

</ap:claimedIdentity>

</ap:userInformation>

You can write the following custom metric expressions to extract classifiers for the user name and role:

{{flow=input,document=userInformation}}//ap:userInformation/ap:userIdentity

{{flow=input,document=userInformation}}//ap:userInformation/ap:claimedIdentity/ap:userRoles/ap:role/@name

where the prefix ’ap’ is associated with the namespace‘http://namespace.amberpoint.com/amf’

Custom Metrics Script Example<CustomMetricBundle name="WCFBookOrderMetrics">

<MonitoredObjectRef>

<WCFServiceOperation domainName="WCF"

assemblyName="BookWCF.DLL"

serviceName="BookStoreService"

serviceContractName="IBookStoreServiceSoap_EP"

operationName="GetBook">

</WCFServiceOperation>

</MonitoredObjectRef>

<NamespacePrefixMap>

<MapEntry prefix="ns0" namespace="http://tempuri.org/" ></MapEntry>

<MapEntry prefix="ns1" namespace="http://schemas.datacontract.org/2004/07/BookOrderWCF" ></MapEntry>

<MapEntry namespace="http://namespace.amberpoint.com/amf" prefix="ap" ></MapEntry>

</NamespacePrefixMap>

<ClassifierCustomMetric name="InputTitle" xpath="{{flow=input,document=input}}//ns0:GetBook/ns0:Title">

<NamespacePrefixOverrideMap></NamespacePrefixOverrideMap>

</ClassifierCustomMetric>

<ClassifierCustomMetric name="User1" displayName="User1" xpath="{{flow=input,document=userInformation}}//ap:userInformation/ap:userIdentity">



Custom Metrics on Security Context propagated by TIBCO ActiveMatrix Policy Manager | 49

</ClassifierCustomMetric>

<InstrumentCustomMetric name="OutputQtyOrdered"

xpath="{{flow=output,document=output}}//ns0:GetBookResponse/ns0:GetBookResult/ns1:QtyOrdered"

keepHistory="true" unit="USD" unitDisplayName="$">


<MetricFunction>sum</MetricFunction>

</InstrumentCustomMetric>

</CustomMetricBundle>


| 51

Appendix A Registering the .Net Keystore Set

This appendix presents the information about how to register the .Net keystore set in TIBCO ActiveMatrix Policy Manager console.

Topics

• Introduction, page 52

• Registering .Net Keystore Set, page 53


52 | Appendix A Registering the .Net Keystore Set

Introduction

Supported PlatformThe only supported platform for this product is:

• Windows Server 2003

For certificates management related tasks for Windows Server 2003, go to:

http://technet.microsoft.com/en-us/library/cc778411(WS.10).aspx


http://technet.microsoft.com/en-us/library/cc778411(WS.10).aspx

Registering .Net Keystore Set | 53

Registering .Net Keystore Set

To register the .Net keystore set, do the following:

1. In the Policy Manager Console, click Infrastructure.

2. Click Register.

3. From the drop-down menu, select Keystore Set > .Net Certificate Stores as shown in Figure 15.

Figure 15 Selecting Keystore Set in Policy Manager Console

Register .Net Certificate StoresThe Register .Net Certificate stores consists of the following sections.

.Net Certificate Store Info

Figure 16 shows the fields required to be updated in this section. They are:

Name - Name of the .Net store

Version - Version of the Certificate

Notes - User can add specific notes here



Figure 16 .Net Certificate Stores Info

Settings

This section consists of:

• Specification of Certificates available for Encryption

• Specifictions of the Key to use for Signing

• Specifications of the Trusted SAML Authority Certificate Store

Specification of Certificates available for Encryption

Figure 17 Certificates available for encryption

• Store Location - Location of the store can be "Computer Account" or "User Account".



• Store Name - Select a specific certificate from the drop-down menu.

— Private Keys and associated certificates establish a trusted identity for an entity using the public key-based services and applications. These are the certificates that have been issued to the user, or to the computer or service for which you are managing certificates.

— Trusted Enterprise Certificates are used to digitally sign and encrypt communications and also to control access to web resources.

— Other People'e Entity's certificates are issued to the user or end entities that are explicitly trusted.

Specifictions of the Key to use for Signing

Figure 18 Keys to use for signing

• Store Location - Location of the store can be "Computer Account" or "User Account".

• Name of the Signature Key Certificate - Specify name of the certificate using the context (CN) information.

When store name is set to Private Keys and associated certificates option, ’Personal' certificate store is used.

When store name is set to Trusted Enterprise Certificates option, 'Enterpise Trust' certificate store is used.

When store name is set to Other People'e Entity's certificates option, 'Other People' certificate store is used.



Specifications fo the Trusted SAML Authority Certificate Store

Figure 19 Trusted SAML Authority Certificate Store

Store Location - Location of the store can be "Computer Account" or "User Account".

Store Name - For details, refer to the section, Specification of Certificates available for Encryption on page 54.

Criteria

Click Apply to for applying the criteria to the all agents.

Click add clause for adding the clause to the policy agents

To add criteria, click Add Criterion.

Figure 20 Criteria for the policy

Registering ASP.NET 2.0 with IIS and WCF handler for .svc extensionCertain special steps are required for registering ASP.NET 2.0 with IIS and WCF handler for .svc extension.

To register all ASP.NET extension in IIS

1. Change to C:\WINDOWS\Microsoft.NET\Framework\v2.0.50727 directory.

2. Run aspnet_regiis –i utility.

This will register all ASP.NET extension in IIS.



3. Open IIS manager.

4. Expand node for local computer.

5. Expand node for Web Sites.

6. Right-click on Default Web Site and select Properties.

7. Select ASP.NET tab. The version of ASP.NET must be 2.0.

To register WCF handler for .svc extension in IIS

1. Change to C:\WINDOWS\Microsoft.NET\Framework\v3.0\Windows Communication Foundation directory

2. Run ServiceModelReg –i utility.

This will register WCF handler for .svc extension in IIS.

Once you have registered ASP.NET 2.0 with IIS and WCF handler for .svc extension:

1. Start IIS Manager.

2. In the left-side pane, expand and navigate to Web Service Extensions node and click on it.

Ensure that web service extensions for ASP.NET v2.0.50727 are allowed.


| 59

Appendix B Registering ASP.NET 2.0 with IIS and WCF Handler for .svc Extension

This appendix presents the information about how to register . ASP.NET 2.0 with IIS and WCF handler for .svc extension.

Topics

• Steps to Register ASP.NET 2.0 with IIS and WCF handler for .svc extension, page 60


60 | Appendix B Registering ASP.NET 2.0 with IIS and WCF Handler for .svc Extension

Steps to Register ASP.NET 2.0 with IIS and WCF handler for .svc

extension

Certain steps are required for registering ASP.NET 2.0 with IIS and WCF handler for .svc extension.

To register all ASP.NET extension in IIS 1. Change to C:\WINDOWS\Microsoft.NET\Framework\v2.0.50727 directory.

2. Run aspnet_regiis –i utility.

This will register all ASP.NET extension in IIS.

3. Open IIS manager.

4. Expand node for local computer.

5. Expand node for Web Sites.

6. Right-click on Default Web Site and select Properties.

7. Select ASP.NET tab. The version of ASP.NET must be 2.0.

To register WCF handler for .svc extension in IIS 1. Change to C:\WINDOWS\Microsoft.NET\Framework\v3.0\Windows

Communication Foundation directory

2. Run ServiceModelReg –i utility.

This will register WCF handler for .svc extension in IIS.

Once you have registered ASP.NET 2.0 with IIS and WCF handler for .svc extension:

1. Start IIS Manager.

2. In the left-side pane, expand and navigate to Web Service Extensions node and click on it.

Ensure that web service extensions for ASP.NET v2.0.50727 are allowed.


| 61

Appendix C Troubleshooting

Problem When starting the TIBCO ActiveMatrix Management Agent for WCF for WCF services deployed in IIS, the agent may encounter authority related errors and may not start. This is indicated by a red sphere status displayed next to TIBCO ActiveMatrix Management Agent for WCF in policy manager console and also indicated by incomplete initialization logs.

To check whether an authority related error was encountered by the agent:

1. Launch Event Viewer application as follows:

a. Select Start > Run.

b. Enter eventvwr.msc.

An Event Viewer window is displayed.

2. Click on Application event log from left pane.

3. In the right pane, check if an error event with id 1334 is displayed. If the event is present, double click on the event.

Figure 21 Event Viewer


62 | Appendix C Troubleshooting

Solution This error typically occurs because of insufficient authority to user under which IIS runs. To resolve this problem, perform following steps:

1. Find IIS Server user.

a. Right-click Windows task bar. Select Task Manager option.

b. Click on Processes tab.

c. Check user under User Name column for w3wp.exe process.

2. Find user security id (SID) for the user. Utility command getsid is part of Windows 2003 Support Tools package. To run this command:

a. Select Start > Programs > Windows Support Tools > Command Prompt.

A command prompt window is displayed.

b. Run the command:

getsid \\<machine name> <user name> \\<machine name> <user name>

3. Grant permission for TIBCO ActiveMatrix Management Agent for WCF HTTP port as follows:

a. Select Start > Programs > Windows Support Tools > Command Prompt.

A command prompt window is displayed.

b. Run command

httpcfg set urlacl /u http://+:<agent port>/ /a D:(A;;GX;;;<user SID>)

4. To restart IIS Server:


b. Enter iisreset.

5. Restart TIBCO TIBCO ActiveMatrix Management Agent for WCF.

Problem Why does the TIBCO ActiveMatrix Management Agent for WCF stop after 15-20 minutes if it does not get any requests?

Solution TIBCO ActiveMatrix TIBCO ActiveMatrix Management Agent for WCF seems to stop after 15-20 minutes if it does not get any requests. After 15-20 minutes of idle time, the agent status shows Red in Policy Manager console (but agent managed service status shows Running).

After this idle time, when you try to get the WSDL for the agent managed service or try to invoke agent managed service, it takes 15-20 seconds to respond to the first request. All the subsequent requests do not have this problem.

To configure this idle time, follow these steps:


Troubleshooting | 63

1. Right-click Application Pools in the IIS Manager.

2. Go to Performance tab.

3. Disable the Shutdown worker process after being idle for option or enter a high value to increase the time period.

Problem How to ensure that the WCF Agent and WCF Service Probe has started?

Solution The Start and Stop status of WCF Agent is shown in the Policy Manager > Services tab in green and red to indicate start and stop respectively.

To check Start and Stop status of the WCF Service Probe:

1. Launch Event Viewer application as follows:


b. Enter eventvwr.msc.

An Event Viewer window is displayed.

2. Click on Tibco.MessageInspector from left pane to check the following:

— Creating Tibco.MessageInspector.MessageInspectionBehavior instance

— Loading Tibco.PolicyAgent assembly

— Directory path of AGENT_HOME : c:\tibco_HOME\amma-wcf\<version_num>

3. Click on Tibco.SPM.ServiceProbe from the left pane to check the following:

— ServiceProbe : Enabled monitoring

— WCF Service Probe started on (IIS/Web Site 2/BookOrderService)

— WCF Service Probe stopped on (IIS/Web Site 2/BookOrderService)


64 | Appendix C Troubleshooting


| 65

Index

A

ActiveMatrix node 10agent 6amma-wcf (directory) 16

B

BusinessWorks 8

C

configuration checklist 17custom security permissions 14

D

directories 16

F

forwarding user information 40forwardUserInfoContextDoc 42

G

getAttributes 44getRoles 45

I

IIS 2installation

directories 16

M

Machine.Config 22management service 6Message Inspection Library 22MMC 3, 18

P

PAP, PDP, PEP, PRP 2policy types, support for 11prerequisites 3

S

security context API 39security permissions 14SecurityContext 43

getAttributesF 44getRoles 45setSecurityContext 46

setSecurityContext 46


66 | Index

T

TIBCO_HOME xitibco_home (directory) 16

U

user information, forwarding 40

W

WCF 2WCF security permissions 14


tibco ...wcf service probe helps to integrate tibco activematrix® service performance manager with...

Documents