TIBCO Runtime Agent™

Authentication API
User’s Guide
Software Release 5.10
August 2015

Two-Second Advantage®
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, Two-Second Advantage, TIBCO Hawk, TIBCO Rendezvous, TIBCO Runtime Agent, TIBCO
ActiveMatrix BusinessWorks, TIBCO Administrator, TIBCO Designer, TIBCO ActiveMatrix Service Gateway,
TIBCO BusinessEvents, TIBCO BusinessConnect, and TIBCO BusinessConnect Trading Community
Management are either registered trademarks or trademarks of TIBCO Software Inc. in the United States and/or
other countries.
Enterprise Java Beans (EJB), Java Platform Enterprise Edition (Java EE), Java 2 Platform Enterprise Edition
(J2EE), and all Java-based trademarks and logos are trademarks or registered trademarks of Oracle Corporation
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 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.
This Product is covered by U.S. Patent No. 6,970,981.
Copyright © 1998-2015 TIBCO Software Inc. ALL RIGHTS RESERVED.
TIBCO Software Inc. Confidential Information
 | iii

Contents

Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .v
Changes from the previous Release of this Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . vi
Related Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . vii
TIBCO Runtime Agent Documentation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . vii
Other TIBCO Product Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . vii
Typographical Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ix
Connecting with TIBCO Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xii
How to Join TIBCOmmunity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xii
How to Access TIBCO Documentation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xii
How to Contact TIBCO Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xii

Chapter 1 Using the TIBCO Runtime Agent Authentication API . . . . . . . . . . . . . . . . . . . . . . . . . .1

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

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9

TIBCO Runtime Agent Authentication API User’s Guide

iv
| Contents

TIBCO Runtime Agent Authentication API User’s Guide

 |v

Preface

This manual explains how to use TIBCO Runtime Agent™ Authentication API.

Topics

• Changes from the previous Release of this Guide, page vi

• Related Documentation, page vii
• Typographical Conventions, page ix
• Connecting with TIBCO Resources, page xii

TIBCO Runtime Agent Authentication API User’s Guide

vi
| Changes from the previous Release of this Guide

Changes from the previous Release of this Guide

There are no changes from the previous release of this guide.

TIBCO Runtime Agent Authentication API User’s Guide

 Preface vii
|

Related Documentation

This section lists documentation resources you may find useful.

TIBCO Runtime Agent Documentation

The TIBCO Runtime Agent™ software suite is a prerequisite for other TIBCO
software products. In addition to Runtime Agent components, the software suite
includes the third-party libraries used by other TIBCO products, TIBCO
Designer™, Java Runtime Environment (JRE), TIBCO Rendezvous®, and TIBCO
Hawk®.
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™ Upgrading to Release 5.10.0 Read this manual for
instructions on upgrading from release 5.x to release 5.10.0.
• TIBCO Runtime Agent™ Domain Utility User’s Guide Read this manual for
instructions on using TIBCO Domain Utility to create and manage
administration domains.
• TIBCO Runtime Agent™ Scripting Deployment User’s Guide Read this manual
for instructions on using the AppManage scripting utility to deploy
applications.
• TIBCO Runtime Agent™ Authentication API User's Guide Read this manual for
instructions on using Authentication API.
• 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.

Other TIBCO Product Documentation

You may find it useful to read the documentation for the following TIBCO
products:
• TIBCO Administrator™ : TIBCO Administrator allows you to manage users,
machines and applications defined in a TIBCO administration domain. The
TIBCO Administrator graphical user interface enables users to deploy,
monitor, and start and stop TIBCO applications.

TIBCO Runtime Agent Authentication API User’s Guide

viii
| Related Documentation

• TIBCO Designer™: This graphical user interface is used for designing and
creating integration project configurations and building an Enterprise Archive
(EAR) for the project. The EAR can then be used by TIBCO Administrator for
deploying and running the application.
• TIBCO Hawk®: This is a tool for monitoring and managing distributed
applications and operating systems.
• TIBCO Rendezvous®: Rendezvous enables programs running on many
different kinds of computers on a network to communicate seamlessly. It
includes two main components: the Rendezvous application programming
interface (API) in several languages, and the Rendezvous daemon.
• TIBCO Enterprise Message Service™: This software lets application programs
send and receive messages using the Java Message Service (JMS) protocol. It
also integrates with TIBCO Rendezvous and TIBCO SmartSockets®
messaging products.
• TIBCO ActiveMatrix BusinessWorks™: ActiveMatrix BusinessWorks is a
scalable, extensible, and easy to use integration platform that allows you to
develop integration projects. ActiveMatrix BusinessWorks includes a GUI for
defining business processes and an engine that executes the process.
• TIBCO® Adapter software: TIBCO Runtime Agent is a prerequisite for TIBCO
Adapter products. You will therefore find TIBCO Adapter product
documentation useful.

TIBCO Runtime Agent Authentication API User’s Guide

 Preface ix
|

Typographical Conventions

The following typographical conventions are used in this manual.

Table 1 General Typographical Conventions

Convention Use
ENV_NAME TIBCO products are installed into an installation environment. A product
installed into an installation environment does not access components in other
TIBCO_HOME
installation environments. Incompatible products and multiple instances of the
TRA_HOME same product must be installed into different installation environments.
An installation environment consists of the following properties:
• Name Identifies the installation environment. This name is referenced in
documentation as ENV_NAME. On Microsoft Windows, the name is
appended to the name of Windows services created by the installer and is a
component of the path to the product shortcut in the Windows Start > All
Programs menu.
• Path The folder into which the product is installed. This folder is referenced
in documentation as TIBCO_HOME.
TIBCO Runtume Agent installs into a directory within a TIBCO_HOME. This
directory is referenced in documentation as <ProductAcronym>_HOME. The
default value of <ProductAcronym>_HOME depends on the operating system.
For example on Windows systems, the default value is
C:\tibco\<ProductAcronym>\<ReleaseNumber>.

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 Bold code font is used in the following ways:

font
• 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]

TIBCO Runtime Agent Authentication API User’s Guide

x
| Typographical Conventions

Table 1 General Typographical Conventions (Cont’d)

Convention Use
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 Key name separated by a plus sign indicate keys pressed simultaneously. For
combinations 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.

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 param1 | param2 | param3

TIBCO Runtime Agent Authentication API User’s Guide

 Preface xi
|

Table 2 Syntax Typographical Conventions (Cont’d)

Convention Use
{ } 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}

TIBCO Runtime Agent Authentication API User’s Guide

xii
| Connecting with TIBCO Resources

Connecting with TIBCO Resources

How to Join TIBCOmmunity

TIBCOmmunity is an online destination for TIBCO customers, partners, and
resident experts. It is a place to share and access the collective experience of the
TIBCO community. TIBCOmmunity offers forums, blogs, and access to a variety
of resources. To register, go to http://www.tibcommunity.com.

How to Access TIBCO Documentation

You can access TIBCO documentation here:
http://docs.tibco.com

How to Contact TIBCO Support

For comments or problems with this manual or the software it addresses, 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 User’s 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 User’s Guide

2
| 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 User’s 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:
TRA_HOME/doc/auth/javadoc

For explanations of the meaning of variables like TRA_HOME,

TIBCO_DOMAIN_HOME, TIBCO_TRA_VERSION, and so on, please refer to the
table on Typographical Conventions on page ix 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 User’s Guide

4
| 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:
— TRA_HOME/lib/TIBCOAuthAPI.jar

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:
TRA_VERSION=TRA_VERSION

TRA_HOME=TRA_HOME
DOMAIN_NAME=Your-Domain-Name

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:
— TRA_HOME/lib
— These files include TIBCOAuthAPI.jar and TIBCOAuthAPIimpl.jar
• HAWK Jar files from following directory:
— TIBCO_HOME/hawk/lib

TIBCO Runtime Agent Authentication API User’s Guide

 Getting Started with the API 5
|

• RV jar files from following directory:

— TIBCO_HOME/tibrv/TIBCO_RV_VERSION/lib
• TPCL jar files from following directories:
— TIBCO_HOME/tpcl/TIBCO_TPCL_VERSION/lib
— TIBCO_HOME/tpcl/TIBCO_TPCL_VERSION/jdbc

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:
— TRA_HOME/sample/auth
Please refer to the readme.txt 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
TRA_HOME/doc/auth/javadoc
— SampleAuthAPIUsage.java from a subdirectory within the following
samples source directory:
TRA_HOME/sample/auth/src

TIBCO Runtime Agent Authentication API User’s Guide

6
| 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 instance().

TIBCO Runtime Agent Authentication API User’s 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\logs\Administrator.log
file. It may indicate what exceptions or errors have been encountered.

TIBCO Runtime Agent Authentication API User’s Guide

8
| Chapter 1 Using the TIBCO Runtime Agent Authentication API

TIBCO Runtime Agent Authentication API User’s Guide

 |9

Index

A T
API Overview 3 technical support xii
TIBCO_HOME ix

C
U
Compiling Programs 4
customer support xii Using the API 5

E
ENV_NAME ix

G
Getting Started with the API 4

R
Running Programs 4
Running the Samples 5

S
support, contacting xii

TIBCO Runtime Agent Authentication API User’s Guide