TIBCO Runtime Agent Authentication API Users Guide

Software Release 5.7 November 2010

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 THE LICENSE FILE) 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. TIBCO, The Power of Now, TIBCO ActiveMatrix BusinessWorks, and TIBCO Administrator are either registered trademarks or trademarks of TIBCO Software Inc. in the United States and/or 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 1999-2010 TIBCO Software Inc. ALL RIGHTS RESERVED. TIBCO Software Inc. Confidential Information

| iii

Contents

Related Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . vi TIBCO Administrator Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . vi TIBCO Runtime Agent Documentation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . vi Typographical Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . vii How to Contact TIBCO Support. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ix Feature Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 API Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 Getting Started with the API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 Compiling Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 Running Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 Running the Samples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 Using the API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 Common Aspects of the API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 Objects and Factory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 AuthenticationSubject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 RoleMembershipConfig and RoleMembership . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 AuthUtils . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 Best Practices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 General Tips . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

TIBCO Runtime Agent Authentication API Users Guide

iv

| Contents

TIBCO Runtime Agent Authentication API Users Guide

|v

Preface

The TIBCO Runtime Agent Authentication API provides an API that enables users to create custom scripts and applications.

Topics
Related Documentation, page vi Typographical Conventions, page vii How to Contact TIBCO Support, page ix

TIBCO Runtime Agent Authentication API Users Guide

vi

| Related Documentation
Related Documentation
This section lists documentation resources you may find useful.

TIBCO Administrator Documentation

The following documents form the TIBCO Administrator documentation set: TIBCO Administrator Users Guide Read this manual to gain an understanding of the product that you can apply to the various tasks you may undertake. TIBCO Administrator Server Configuration Guide Read this manual for server configuration information. TIBCO Administrator Installation Read this manual for instructions on site preparation and installation. TIBCO Administrator 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.

TIBCO Runtime Agent Documentation

The following documents form the TIBCO Runtime Agent documentation set: TIBCO Runtime Agent Installation Read this manual for instructions on site preparation and installation. TIBCO Runtime Agent Installing Into a Cluster Read this manual for instructions on installing TIBCO applications into a cluster environment. TIBCO Runtime Agent Domain Utility Users Guide Read this manual for instructions on using TIBCO Domain Utility to create and manage administration domains. TIBCO Runtime Agent Scripting Deployment Users Guide Read this manual for instructions on using the AppManage scripting utility to deploy applications. TIBCO Runtime Agent 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.

TIBCO Runtime Agent Authentication API Users Guide

Preface vii

Typographical Conventions
The following typographical conventions are used in this manual. Table 1 General Typographical Conventions Convention
TIBCO_HOME

Use Many TIBCO products must be installed within the same home 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. TIBCO Administrator installs into a directory within TIBCO_HOME. This directory is referenced in documentation as TIBCO_TRA_HOME. The value of TIBCO_TRA_HOME depends on the operating system. For example on Windows systems, the default value is C:\tibco\tra\5.7. The version of TIBCO Runtime Agent currently installed is referenced in documentation as TIBCO_TRA_VERSION, for example, 5 . 7 . TIBCO_DOMAIN_HOME is where TIBCO domain-related files (such as logs, configuration, and startup files) are stored. If TIBCO_HOME is C : \ t i b c o , then TIBCO_DOMAIN_HOME is normally C : \ t i b c o \ t r a \ d o m a i n . For instance, if the domain name is m y d o m a i n then its domain specific files will be stored in C:\tibco\tra\domain\mydomain. TIBCO_TPCL_VERSION indicates the version number of third-party class libraries included with TIBCO Runtime Agent.

TIBCO_TRA_HOME TIBCO_TRA_VERSION TIBCO_DOMAIN_HOME TIBCO_TPCL_VERSION

code font

Code font identifies commands, code examples, filenames, pathnames, and output displayed in a command window. For example: Use M y C o m m a n d to start the foo process.

TIBCO Runtime Agent Authentication API Users Guide

viii

| Typographical Conventions
Table 1 General Typographical Conventions (Contd) Convention
bold code font

Use 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, M y C o m m a n d 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: M y C o m m a n d 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. 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.

TIBCO Runtime Agent Authentication API Users Guide

Preface ix

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.

TIBCO Runtime Agent Authentication API Users Guide

| How to Contact TIBCO Support

TIBCO Runtime Agent Authentication API Users Guide

|1
Chapter 1

Using the TIBCO Runtime Agent Authentication API

This chapter explains the need for TIBCO Runtime Agent Authentication API, and contains instructions for its use.

Topics
Feature Overview, page 2 API Overview, page 3 Getting Started with the API, page 4 Common Aspects of the API, page 6 Best Practices, page 7

TIBCO Runtime Agent Authentication API Users Guide

| Chapter 1

Using the TIBCO Runtime Agent Authentication API

Feature Overview
This is an API that can be used to create custom scripts and applications. This API includes Javadocs, viewable in a web browser.

TIBCO Runtime Agent Authentication API Users Guide

API Overview 3

API Overview
This API can be used to create custom scripts and applications. Javadocs for this API are contained in the following directory: TIBCO_TRA_HOME/doc/auth/javadoc For explanations of the meaning of variables like TIBCO_TRA_HOME, TIBCO_DOMAIN_HOME, TIBCO_TRA_VERSION, and so on, please refer to the table on Typographical Conventions on page vii of the Preface. While most TIBCO Runtime Agent and TIBCO Runtime Agent (TRA) requirements are addressed by the capabilities available through Runtime Agent Console and other TRA utilities, this API allows you to provide programmatic access to the functionality available through Runtime Agent Console. This API provides a framework for doing the following: User authentication Retrieve users Retrieve roles and role memberships

TIBCO Runtime Agent Authentication API Users Guide

| Chapter 1

Using the TIBCO Runtime Agent Authentication API

Getting Started with the API

This section provides information that will be useful to you as you begin to work with the API.

Compiling Programs
In order to compile your scripts and applications, you will need to include the following jar files in your classpath: TIBCO_TRA_HOME/ l i b / T I B C O A u t h A P I . j a r

Running Programs
In order to run your scripts and applications, your system must meet the requirements described in this section. Note that an API program cannot be run remotely from the command-line. You must run it on a machine where this Authentication API is installed. Running Programs: Environment Variables Required To run a program or application that uses this API , you must set the following environment variables:
TIBCO_TRA_VERSION=TIBCO_TRA_VERSION TIBCO_TRA_HOME=TIBCO_TRA_HOME T I B C O _ D O M A I N _ N A M E = Your-Domain-Name TIBCO_DOMAIN_HOME=TIBCO_DOMAIN_HOME

Running Programs: JAR Files Required You must also ensure that the following JAR files are on your classpath: TRA jar files from following directory: TIBCO_TRA_HOME/ l i b These files include T I B C O A u t h A P I . j a r and T I B C O A u t h A P I i m p l . j a r HAWK Jar files from following directory: TIBCO_HOME/ h a w k / l i b

TIBCO Runtime Agent Authentication API Users Guide

Getting Started with the API 5

RV jar files from following directory: TIBCO_HOME/ t i b r v / 8 . 1 / l i b

TPCL jar files from following directories: TIBCO_HOME/ t p c l / TIBCO_TPCL_VERSION/ l i b TIBCO_HOME/ t p c l / TIBCO_TPCL_VERSION/ j d b c

Running the Samples

A sample has been provided with compile and run scripts. This sample provides all the environment variables required to run this program. The sample is available in the following directory: TIBCO_TRA_HOME/ s a m p l e / a u t h Please refer to the r e a d m e . t x t in that directory for the instructions on compiling and running the sample.

Using the API

For learning how to use this API, please refer to: Javadocs from the following directory
TIBCO_TRA_HOME/doc/auth/javadoc

SampleAuthAPIUsage.java

from a subdirectory within the following

samples source directory:

TIBCO_TRA_HOME/sample/auth/src

TIBCO Runtime Agent Authentication API Users Guide

| Chapter 1

Using the TIBCO Runtime Agent Authentication API

Common Aspects of the API

For more details on the objects and classes referenced in the section ahead, refer to the Javadocs as described in the section API Overview on page 3.

Objects and Factory

Two main objects are User and Role. The factory classes UserFactory and RoleFactory provide methods to retrieve the User and Role objects respectively.

AuthenticationSubject
An object of the AuthenticationSubject class represents an authenticated user, and contains such information as the user name, password, and whether or not the user is authenticated. This is not used for validating the authentication for the username and password specified here. This is only used for such purposes as identifying the user or checking role memberships for a user. For information on checking authorization, refer to AuthUtils on page 6.

RoleMembershipConfig and RoleMembership

There are two major portions of the API: model and runtime. The model portion of the API deals with managing the configuration of the Object. The runtime portion of the API contains utilities you can use to compute something or take some action. RoleMembershipConfig is the model component that provides details necessary for computing the membership of the role. RoleMembership is the runtime component that provides logic for computing the membership of a Role. The runtime portion of the API is generally useful only in the context of custom Role Membership Plug ins. You will not have the necessary context to run this runtime API in a command-line context.

AuthUtils
The model objects such as User and Role are purely data objects with no behavior exposed. This utility class exposes the behavior for these objects. For example, it provides role membership, taking into account the membership inherited from child roles. The single instance of this utility class is obtained by calling i n s t a n c e ( ) .
TIBCO Runtime Agent Authentication API Users Guide

Best Practices 7

Best Practices

General Tips
The following sections provide some general tips for developers. Log Files When a program written using these API does not behave as expected, make sure you check the TIBCO_DOMAIN_HOME\ TIBCO_DOMAIN_NAME\ l o g s \ A d m i n i s t r a t o r . l o g file. It may indicate what exceptions or errors have been encountered.

TIBCO Runtime Agent Authentication API Users Guide

| Chapter 1

Using the TIBCO Runtime Agent Authentication API

TIBCO Runtime Agent Authentication API Users Guide

|9

Index

A
API Overview 3

U
Using the API 5

C
Compiling Programs 4 customer support ix

G
Getting Started with the API 4

R
Running Programs 4 Running the Samples 5

S
support, contacting ix

T
technical support ix TIBCO_HOME vii

TIBCO Runtime Agent Authentication API Users Guide