Authorization Java Classes Developer Reference - IBM€¦ · Chapter 1. Introduction to ... the users and objects associated with the Tivoli Access Manager for e ... Authorization

Tivoli® Access Manager for e-businessVersion 6.1.1

Authorization Java Classes DeveloperReference

SC23-6516-01

��

Tivoli® Access Manager for e-businessVersion 6.1.1

Authorization Java Classes DeveloperReference

SC23-6516-01

��

NoteBefore using this information and the product it supports, read the information in Appendix D, “Notices,” on page 49.

Edition notice

This edition applies to version 6, release 1, modification 1 of IBM Tivoli Access Manager (product number5724-C87) and to all subsequent releases and modifications until otherwise indicated in new editions.

All rights reserved.

© Copyright IBM Corporation 2002, 2010.US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contractwith IBM Corp.

Contents

About this publication . . . . . . . . vIntended audience . . . . . . . . . . . . vPublications . . . . . . . . . . . . . . v

IBM Tivoli Access Manager for e-business library vRelated products and publications. . . . . . viiAccessing terminology online . . . . . . . viiiAccessing publications online . . . . . . . viiiOrdering publications . . . . . . . . . . ix

Accessibility . . . . . . . . . . . . . . ixTivoli technical training . . . . . . . . . . ixTivoli user groups . . . . . . . . . . . . ixSupport information . . . . . . . . . . . . xConventions used in this publication . . . . . . x

Typeface conventions . . . . . . . . . . xOperating system-dependent variables and paths xi

Chapter 1. Introduction to theauthorization API . . . . . . . . . . . 1Accessing the Javadoc HTML documentation . . . 2Authorization API components . . . . . . . . 2Requirements for developing Java applications . . . 4

Tivoli Access Manager software requirements . . 4JRE requirements . . . . . . . . . . . . 4Configuring the Tivoli Access Manager Runtimefor Java component to a particular environment . 5Security requirements . . . . . . . . . . 5

Deploying a Java authorization API application. . . 6

Chapter 2. Authorization API Javaclasses overview . . . . . . . . . . . 7Classes from com.tivoli.pd.jazn package . . . . . 8

PDAuthorizationContext: method and constructorsummary . . . . . . . . . . . . . . 8PDLoginModule: method and constructorsummary . . . . . . . . . . . . . . 8PDPermission: method and constructor summary 9PDPrincipal: method and constructor summary. . 9

Classes from com.tivoli.pd.jutil package . . . . . 11PDAttrs: method and constructor summary. . . 11PDAttrValue: method and constructor summary 12PDAttrValueList: method and constructorsummary . . . . . . . . . . . . . . 12PDAttrValues: method and constructor summary 13PDStatics . . . . . . . . . . . . . . 13

Chapter 3. Java security . . . . . . . 15Java 2 security with Tivoli Access Manager . . . . 16Java Authentication and Authorization Service(JAAS) model. . . . . . . . . . . . . . 17

Authenticating users and obtaining credentials 17Authorizing access requests . . . . . . . . 18

Chapter 4. Java applicationdevelopment . . . . . . . . . . . . 21

Configuring a Java application into the securedomain . . . . . . . . . . . . . . . . 22

Configuring an application server . . . . . . 23Unconfiguring an application server . . . . . 24Adding a policy or authorization server . . . . 24Removing a policy or authorization server . . . 24Changing a policy or authorization server . . . 25Replacing a certificate . . . . . . . . . . 25Setting the port . . . . . . . . . . . . 25Setting the database directory . . . . . . . 25Setting the database refresh interval . . . . . 25Setting the application listening mode . . . . 25Setting the certificate refresh option . . . . . 26

Configuring the Java Authentication andAuthorization Service . . . . . . . . . . . 27

Creating a login configuration file . . . . . . 27Specify the login file location . . . . . . . 27

Developing a resource manager . . . . . . . 28Making authorization decisions outside of Java 2 . . 29Obtaining entitlements for a specified user . . . . 30

Appendix A.com.tivoli.pd.jcfg.SvrSslCfg. . . . . . 33–action config . . . . . . . . . . . . . 36–action unconfig . . . . . . . . . . . . . 37–action addsvr . . . . . . . . . . . . . 37–action rmsvr. . . . . . . . . . . . . . 37–action chgsvr . . . . . . . . . . . . . 37–action replcert . . . . . . . . . . . . . 38–action setport . . . . . . . . . . . . . 38–action setdbdir . . . . . . . . . . . . . 38–action setdbref . . . . . . . . . . . . . 38–action setdblisten . . . . . . . . . . . . 38–action setcertref. . . . . . . . . . . . . 39

Appendix B. Deprecated Java classesand methods . . . . . . . . . . . . 41

Appendix C. Support information . . . 43Searching knowledge bases . . . . . . . . . 43

Searching information centers . . . . . . . 43Searching the Internet . . . . . . . . . . 43

Obtaining fixes . . . . . . . . . . . . . 43Registering with IBM Software Support . . . . . 44Receiving weekly software updates . . . . . . 44Contacting IBM Software Support . . . . . . . 45

Determining the business impact . . . . . . 45Describing problems and gathering information 46Submitting problems . . . . . . . . . . 46

Appendix D. Notices . . . . . . . . . 49Trademarks . . . . . . . . . . . . . . 51

Glossary . . . . . . . . . . . . . . 53

© Copyright IBM Corp. 2002, 2010 iii

Index . . . . . . . . . . . . . . . 63

iv Authorization Java Classes Developer Reference

About this publication

IBM® Tivoli® Access Manager for e-business provides an access controlmanagement solution to centralize network and application security policy fore-business applications.

This reference contains information about how to use Tivoli Access Managerauthorization Java™ classes and methods to enable an application toprogrammatically perform Tivoli Access Manager authorization tasks. Thisdocument describes the Java implementation of the Tivoli Access Managerauthorization API. See the IBM Tivoli Access Manager for e-business: AuthorizationJava Classes Developer Reference for information regarding the Java implementationof these APIs.

Information about the pdadmin command-line interface (CLI) can be found in theIBM Tivoli Access Manager for e-business: Command Reference.

Intended audienceThis reference is for application programmers writing programs in and Javaprogramming language to authorize the users and objects associated with theTivoli Access Manager for e-business product.

Readers must be familiar with:v Microsoft® Windows® and UNIX® operating systemsv Database architecture and conceptsv Security managementv Internet protocols, including HTTP, TCP/IP, File Transfer Protocol (FTP), and

Telnetv The user registry that Tivoli Access Manager is configured to usev Lightweight Directory Access Protocol (LDAP) and directory services, if used by

your user registryv Authentication and authorization

To enable Secure Sockets Layer (SSL) communication, you must be familiar withSSL protocol, key exchange (public and private), digital signatures, cryptographicalgorithms, and certificate authorities.

PublicationsThis section lists publications in the IBM Tivoli Access Manager for e-businesslibrary and related documents. The section also describes how to access Tivolipublications online and how to order Tivoli publications.

IBM Tivoli Access Manager for e-business libraryThe following documents are in the Tivoli Access Manager for e-business library:v IBM Tivoli Access Manager for e-business: Quick Start Guide, GI11-9333

Provides steps that summarize major installation and configuration tasks.v IBM Tivoli Access Manager for e-business: Release Notes , GC23-6501

© Copyright IBM Corp. 2002, 2010 v

Provides information about installing and getting started, system requirements,and known installation and configuration problems.

v IBM Tivoli Access Manager for e-business: Installation Guide, GC23-6502Explains how to install and configure Tivoli Access Manager for e-business.

v IBM Tivoli Access Manager for e-business: Upgrade Guide, SC23-6503Upgrade from version 5.0, 6.0, or 6.1 to version 6.1.1.

v IBM Tivoli Access Manager for e-business: Administration Guide, SC23-6504Describes the concepts and procedures for using Tivoli Access Manager. Providesinstructions for performing tasks from the Web Portal Manager interface and byusing the pdadmin utility.

v IBM Tivoli Access Manager for e-business: WebSEAL Administration Guide,SC23-6505Provides background material, administrative procedures, and referenceinformation for using WebSEAL to manage the resources of your secure Webdomain.

v IBM Tivoli Access Manager for e-business: Plug-in for Edge Server AdministrationGuide, SC23-6506Provides instructions for integrating Tivoli Access Manager with the IBMWebSphere® Edge Server application.

v IBM Tivoli Access Manager for e-business: Plug-in for Web Servers AdministrationGuide, SC23-6507Provides procedures and reference information for securing your Web domainusing a Web server plug-in.

v IBM Tivoli Access Manager for e-business: Shared Session ManagementAdministration Guide, SC23-6509Provides deployment considerations and operational instructions for the sessionmanagement server.

v IBM Global Security Kit: Secure Sockets Layer Introduction and iKeyman User's Guide,SC23-6510Provides information for enabling SSL communication in the Tivoli AccessManager environment.

v IBM Tivoli Access Manager for e-business: Auditing Guide, SC23-6511Provides information about configuring and managing audit events using thenative Tivoli Access Manager approach and the Common Auditing andReporting Service. You can also find information about installing andconfiguring the Common Auditing and Reporting Service. Use this service forgenerating and viewing operational reports.

v IBM Tivoli Access Manager for e-business: Command Reference, SC23-6512Provides reference information about the commands, utilities, and scripts thatare provided with Tivoli Access Manager.

v IBM Tivoli Access Manager for e-business: Administration C API Developer Reference,SC23-6513Provides reference information about using the C language implementation ofthe administration API to enable an application to perform Tivoli AccessManager administration tasks.

v IBM Tivoli Access Manager for e-business: Administration Java Classes DeveloperReference, SC23-6514Provides reference information about using the Java language implementation ofthe administration API to enable an application to perform Tivoli AccessManager administration tasks.

vi Authorization Java Classes Developer Reference

v IBM Tivoli Access Manager for e-business: Authorization C API Developer Reference,SC23-6515Provides reference information about using the C language implementation ofthe authorization API to enable an application to use Tivoli Access Managersecurity.

v IBM Tivoli Access Manager for e-business: Authorization Java Classes DeveloperReference, SC23-6516Provides reference information about using the Java language implementation ofthe authorization API to enable an application to use Tivoli Access Managersecurity.

v IBM Tivoli Access Manager for e-business: Web Security Developer Reference,SC23-6517Provides programming and reference information for developing authenticationmodules.

v IBM Tivoli Access Manager for e-business: Error Message Reference, GC27-2717Provides problem determination information.

v IBM Tivoli Access Manager for e-business: Troubleshooting Guide, GI11-8157Provides explanations and recommended actions for the messages and returncode.

v IBM Tivoli Access Manager for e-business: Performance Tuning Guide, SC23-6518Provides performance tuning information for an environment consisting of TivoliAccess Manager with the IBM Tivoli Directory Server as the user registry.

Related products and publicationsThis section lists the IBM products that are related to and included with a TivoliAccess Manager solution.

IBM Global Security KitTivoli Access Manager provides data encryption through the use of the GlobalSecurity Kit (GSKit), version 7.0. GSKit is included on the IBM Tivoli AccessManager Base CD for your particular platform, as well as on the IBM Tivoli AccessManager Web Security CDs, the IBM Tivoli Access Manager Shared Session ManagementCDs, and the IBM Tivoli Access Manager Directory Server CDs.

The GSKit package provides the iKeyman key management utility, gsk7ikm, whichcreates key databases, public-private key pairs, and certificate requests. The IBMGlobal Security Kit: Secure Sockets Layer Introduction and iKeyman User's Guide isavailable on the Tivoli Information Center Web site in the same section as theTivoli Access Manager product documentation.

IBM Tivoli Directory ServerIBM Tivoli Directory Server, version 6.1, is included on the IBM Tivoli AccessManager Directory Server set of CDs for the required operating system.

You can find additional information about Tivoli Directory Server at:

http://www.ibm.com/software/tivoli/products/directory-server/

IBM Tivoli Directory IntegratorIBM Tivoli Directory Integrator, version 6.1.1, is included on the IBM TivoliDirectory Integrator CD for the required operating system.

You can find additional information about IBM Tivoli Directory Integrator at:

About this publication vii

http://www.ibm.com/software/tivoli/products/directory-server

http://www-306.ibm.com/software/tivoli/products/directory-integrator/

IBM DB2 Universal DatabaseIBM DB2 Universal Database™ Enterprise Server Edition, version 9.1, is providedon the IBM Tivoli Access Manager Directory Server set of CDs and is installed withthe Tivoli Directory Server software. DB2® is required when using Tivoli DirectoryServer or z/OS® LDAP servers as the user registry for Tivoli Access Manager. Forz/OS LDAP servers, you must separately purchase DB2.

You can find additional information about DB2 at:

http://www.ibm.com/software/data/db2

IBM WebSphere Application ServerWebSphere Application Server, version 6.1, is included on the IBM Tivoli AccessManager WebSphere Application Server set of CDs for the required operating system.WebSphere Application Server enables the support of the following applications:v Web Portal Manager interface, which administers Tivoli Access Manager.v Web Administration Tool, which administers Tivoli Directory Server.v Common Auditing and Reporting Service, which processes and reports on audit

events.v Session management server, which manages shared session in a Web security

server environment.v Attribute Retrieval Service.

You can find additional information about WebSphere Application Server at:

http://www.ibm.com/software/webservers/appserv/infocenter.html

Accessing terminology onlineThe Tivoli Software Glossary includes definitions for many of the technical termsrelated to Tivoli software. The Tivoli Software Glossary is available at the followingTivoli software library Web site:

http://publib.boulder.ibm.com/tividd/glossary/tivoliglossarymst.htm

The IBM Terminology Web site consolidates the terminology from IBM productlibraries in one convenient location. You can access the Terminology Web site athttp://www.ibm.com/software/globalization/terminology .

Accessing publications onlineThe documentation CD contains the publications that are in the product library.The format of the publications is PDF, HTML, or both. Refer to the readme file onthe CD for instructions on how to access the documentation.

The product CD contains the publications that are in the product library. Theformat of the publications is PDF, HTML, or both. To access the publications usinga Web browser, open the infocenter.html file. The file is in the appropriatepublications directory on the product CD.

IBM posts publications for this and all other Tivoli products, as they becomeavailable and whenever they are updated, to the Tivoli Documentation CentralWeb site at http://www.ibm.com/tivoli/documentation.

viii Authorization Java Classes Developer Reference

http://www-306.ibm.com/software/tivoli/products/directory-integrator/

http://www.ibm.com/software/data/db2

http://www.ibm.com/software/webservers/appserv/was

http://publib.boulder.ibm.com/tividd/glossary/tivoliglossarymst.htm

http://www.ibm.com/software/globalization/terminology

http://www.ibm.com/tivoli/documentation

Note: If you print PDF documents on other than letter-sized paper, set the optionin the File → Print window that allows Adobe Reader to print letter-sizedpages on your local paper.

Ordering publicationsYou can order many Tivoli publications online at http://www.elink.ibmlink.ibm.com/publications/servlet/pbi.wss.

You can also order by telephone by calling one of these numbers:v In the United States: 800-879-2755v In Canada: 800-426-4968

In other countries, contact your software account representative to order Tivolipublications. To locate the telephone number of your local representative, performthe following steps:1. Go to http://www.ibm.com/e-business/linkweb/publications/servlet/pbi.wss.2. Select your country from the list and click Go.3. Click About this site in the main panel to see an information page that

includes the telephone number of your local representative.

AccessibilityAccessibility features help users with a physical disability, such as restrictedmobility or limited vision, to use software products successfully. With this product,you can use assistive technologies to hear and navigate the interface. You can alsouse the keyboard instead of the mouse to operate all features of the graphical userinterface.

Visit the IBM Accessibility Center at http://www.ibm.com/alphaworks/topics/accessibility/ for more information about IBM's commitment to accessibility.

For additional information, see the Accessibility Appendix in IBM Tivoli AccessManager for e-business Installation Guide.

Tivoli technical trainingFor Tivoli technical training information, refer to the following IBM TivoliEducation Web site at http://www.ibm.com/software/tivoli/education.

Tivoli user groupsTivoli user groups are independent, user-run membership organizations thatprovide Tivoli users with information to assist them in the implementation ofTivoli Software solutions. Through these groups, members can share informationand learn from the knowledge and experience of other Tivoli users. Tivoli usergroups include the following members and groups:v 23,000+ membersv 144+ groups

Access the link for the Tivoli Users Group at http://www.tivoli-ug.org/.

About this publication ix

http://www.ibm.com/e-business/linkweb/publications/servlet/pbi.wss

http://www.ibm.com/e-business/linkweb/publications/servlet/pbi.wss

http://www.ibm.com/alphaworks/topics/accessibility/

http://www.ibm.com/alphaworks/topics/accessibility/

http://www.ibm.com/software/tivoli/education

http://www.tivoli-ug.org/

Support informationIf you have a problem with your IBM software, you want to resolve it quickly. IBMprovides the following ways for you to obtain the support you need:

OnlineAccess the Tivoli Software Support site at http://www.ibm.com/software/sysmgmt/products/support/index.html?ibmprd=tivman. Access the IBMSoftware Support site at http://www.ibm.com/software/support/probsub.html .

IBM Support AssistantThe IBM Support Assistant is a free local software serviceability workbenchthat helps you resolve questions and problems with IBM softwareproducts. The Support Assistant provides quick access to support-relatedinformation and serviceability tools for problem determination. To installthe Support Assistant software, go to http://www.ibm.com/software/support/isa.

Troubleshooting GuideFor more information about resolving problems, see the IBM Tivoli AccessManager for e-business Installation Guide.

Conventions used in this publicationThis publication uses several conventions for special terms and actions, operatingsystem-dependent commands, and paths.

Typeface conventionsThis publication uses the following typeface conventions:

Bold

v Lowercase commands and mixed case commands that are otherwisedifficult to distinguish from surrounding text

v Interface controls (check boxes, push buttons, radio buttons, spinbuttons, fields, folders, icons, list boxes, items inside list boxes,multicolumn lists, containers, menu choices, menu names, tabs, propertysheets), labels (such as Tip:, and Operating system considerations:)

v Keywords and parameters in text

Italic

v Citations (examples: titles of publications, diskettes, and CDsv Words defined in text (example: a nonswitched line is called a

point-to-point line)v Emphasis of words and letters (words as words example: "Use the word

that to introduce a restrictive clause."; letters as letters example: "TheLUN address must start with the letter L.")

v New terms in text (except in a definition list): a view is a frame in aworkspace that contains data.

v Variables and values you must provide: ... where myname represents....

Monospace

v Examples and code examplesv File names, programming keywords, and other elements that are difficult

to distinguish from surrounding textv Message text and prompts addressed to the user

x Authorization Java Classes Developer Reference

http://www.ibm.com/software/sysmgmt/products/support/index.html?ibmprd=tivman

http://www.ibm.com/software/sysmgmt/products/support/index.html?ibmprd=tivman

http://www.ibm.com/software/support/probsub.html


http://www.ibm.com/software/support/isa

http://www.ibm.com/software/support/isa

v Text that the user must typev Values for arguments or command options

Operating system-dependent variables and pathsThis publication uses the UNIX convention for specifying environment variablesand for directory notation.

When using the Windows command line, replace $variable with % variable% forenvironment variables and replace each forward slash (/) with a backslash (\) indirectory paths. The names of environment variables are not always the same inthe Windows and UNIX environments. For example, %TEMP% in Windowsenvironments is equivalent to $TMPDIR in UNIX environments.

Note: If you are using the bash shell on a Windows system, you can use the UNIXconventions.

About this publication xi

xii Authorization Java Classes Developer Reference

Chapter 1. Introduction to the authorization API

The IBM Tivoli Access Manager Runtime for Java component includes the Javalanguage version of a subset of the Tivoli Access Manager authorization API. Theauthorization API consists of a set of classes that provide Java applications withthe ability to interact with Tivoli Access Manager to make authentication andauthorization decisions.

This chapter contains the following topics:v “Accessing the Javadoc HTML documentation” on page 2v “Authorization API components” on page 2v “Requirements for developing Java applications” on page 4v “Deploying a Java authorization API application” on page 6

© Copyright IBM Corp. 2002, 2010 1

Accessing the Javadoc HTML documentationApplication developers can use the Javadoc information available in the TivoliAccess Manager application developer kit (ADK) along with this book and otherJava reference materials, to add Tivoli Access Manager authorization and securityservices to new or existing Java applications.

Application developers updating an existing Tivoli Access Manager applicationmust consult the Javadoc HTML documentation for deprecated Java APIs beforemodifying the code.

Copy the Javadoc HTML information with the entire AM_BASE/nls/javadocsdirectory to another location on your development system. Uninstall the TivoliAccess Manager ADK and runtime components. Tivoli Access Manager Runtimefor Java component is the only component required for running Java applications.See Table 1 for the Javadoc installation location.

Authorization API componentsThe authorization API Java classes are installed as part of the Tivoli AccessManager Runtime for Java component. These classes communicate directly withthe Tivoli Access Manager authorization server by establishing an authenticated,Secure Sockets Layer (SSL) session with the authorization server process. Theauthorization server services these requests in the same manner that it servicesrequests from the authorization C API.

Table 1 lists the files related to the authorization API that are installed as part ofthe Tivoli Access Manager Runtime for Java component. The Javadoc information,even though it is installed as part of the Tivoli Access Manager ADK component, islisted in the table for completeness.

Table 1. Files associated with the Tivoli Access Manager Runtime for Java and ADK components

Directory Files File description

AM_BASE/nls/javadocs/pdjrte/index.html

index.html

(and many others)

Javadoc HTML documentation for the Javaclasses and methods provided with theTivoli Access Manager Java runtimecomponent.

JAVA_HOME/lib/ext PD.jar The Java Archive (JAR) file containing theclasses and methods associated with theadministration APIs.Note: When you use the pdjrtecfgcommand-line interface to configure theTivoli Access Manager Java runtimecomponent to a particular JRE, this archivefile is copied to JAVA_HOME/lib/ext.Therefore, there is no need to modify theCLASSPATH in your environment to accessthe classes and methods defined in thisarchive file.

AM_BASE/example/pdadminapi_demo/java

README.PDAdminDemoPDAdminDemo.javaPDAdminDemo.classPDAdminDemo$ConsoleEraser.class

A demonstration program is provided toillustrate the use of the administration JavaAPIs. You can copy the demonstrationprogram to any directory. The readme fileexplains how to run and recompile thedemonstration program.

2 Authorization Java Classes Developer Reference

Table 1. Files associated with the Tivoli Access Manager Runtime for Java and ADK components (continued)

Directory Files File description

AM_BASE/example/authz_demo/java

PDCallbackHandler.classPDDemoSetup.classPDDemoSetup.javaPDJaasDemo$1.classPDJaasDemo.classPDJaasDemo.javaPDListObjectsDemo.classPDListObjectsDemo.javaPDPermissionDemo.classPDPermissionDemo.javaREADME.JaznDemo

These files consist of various demosillustrating the use of Tivoli Access ManagerJava authorization APIs. Please readREADME.JaznDemo for a description on how torun the various demonstrations.

AM_BASEexample/local_remote_demo/java

PDLRAuthzDemo1.classPDLRAuthzDemo1.javaPDLRAuthzDemo2$1.classPDLRAuthzDemo2$2.classPDLRAuthzDemo2.classPDLRAuthzDemo2.javaPDLRExerciseDialog$1.classPDLRExerciseDialog$2.classPDLRExerciseDialog$3.classPDLRExerciseDialog$4.classPDLRExerciseDialog.classPDLRExerciseDialog.javaPDLRTestDemo.classPDLRTestDemo.javaPDtamdemoException.classPDtamdemoException.javaPDTimer.classPDTimer.javaREADME.PDLocalRemoteDemo

These file consist of a demonstration thatillustrates the use of both the local andremote modes of Tivoli Access Manageradministration and authorization APIs. Thedemo provides a graphical user interface fordefining the various setup parameters.Please see the README.PDlocalRemoteDemo fora description on how to generate thedocumentation for the demo classes.

To make the JAR files listed in Table 1 on page 2 available to a particular JRE, see“Configuring the Tivoli Access Manager Runtime for Java component to aparticular environment” on page 5.

Chapter 1. Introduction to the authorization API 3

Requirements for developing Java applicationsTo develop Java applications that use the Tivoli Access Manager authorization API,you must install and configure the required software.

Tivoli Access Manager software requirementsYou must install and configure a Tivoli Access Manager secure domain. If you donot have a Tivoli Access Manager secure domain installed, install one beforebeginning application development. The minimum installation consists of a singlesystem with the following Tivoli Access Manager components installed:v Tivoli Access Manager runtime environmentv Tivoli Access Manager Runtime for Java componentv Tivoli Access Manager policy serverv Tivoli Access Manager authorization serverv Tivoli Access Manager ADK

If you already have a Tivoli Access Manager secure domain installed and want toadd a development system to the domain, the minimum Tivoli Access Managerinstallation consists of the following components:v Tivoli Access Manager runtime environment (see Note 1 on page 4)v Tivoli Access Manager Runtime for Java componentv Tivoli Access Manager ADK

For Tivoli Access Manager installation instructions, refer to the section of the IBMTivoli Access Manager for e-business: Installation Guide for your operating systemplatform.

Notes:

1. The Tivoli Access Manager runtime environment component is not needed fordeveloping or deploying a Tivoli Access Manager Java application.

2. You can copy the Javadoc HTML information, consisting of the entireAM_BASE/nls/javadocs directory tree, to another location on yourdevelopment system and then uninstall the Tivoli Access Manager ADK andruntime components. Only the Tivoli Access Manager Runtime for Javacomponent is necessary for running Java applications.

3. To use the Tivoli Access Manager runtime environment for an authorization CAPI application, install the client for the IBM Tivoli Directory Server if anLDAP server is being used as the user registry in the secure domain.

JRE requirementsThe installation of an appropriate JRE is required when using the Tivoli AccessManager authorization API Java classes and methods. The base installation CDcontains an optionally installable JRE. You can use either of the supported JREslisted in the IBM Tivoli Access Manager for e-business: Release Notes for developingand deploying your Tivoli Access Manager Java applications. After you haveinstalled a suitable JRE, configure it for use with Tivoli Access Manager as outlinedin the next section, “Configuring the Tivoli Access Manager Runtime for Javacomponent to a particular environment” on page 5.


Configuring the Tivoli Access Manager Runtime for Javacomponent to a particular environment

Configure the Tivoli Access Manager Runtime for Java component to use theproper JRE on the system by using the pdjrtecfgcommand. The pdjrtecfgcommand copies the Tivoli Access Manager JAR files to the JAVA_HOME/lib/extdirectory of the JRE, automatically making the Tivoli Access Manager classes andmethods available. The CLASSPATH in your environment does not need to bemodified. The Tivoli Access Manager Runtime for Java component can beconfigured to several different JREs on the same system, if desired. See the IBMTivoli Access Manager for e-business: Command Reference for details.

Security requirementsThe PD.jarfile is signed and verified in this version of Tivoli Access Manager.

The SvrSslCfgJava class (com.tivoli.pd.jcfg.SvrSslCfg) must be used to createconfiguration files that are to be used by Java applications. See “Configuring a Javaapplication into the secure domain” on page 22 for details on using the SvrSslCfgclass.

Note: The svrsslcfg command line interface and the SvrSslCfg Java utility are notinterchangeable. Do not use the svrsslcfg command line interface to createconfiguration files that are to be used with Java applications. Do not use theSvrSslCfg Java class to create configuration files for use by C applications.

Chapter 1. Introduction to the authorization API 5

Deploying a Java authorization API applicationAfter you have developed and tested your Java application that uses the TivoliAccess Manager authorization API, you can deploy the application to systems thatare configured as part of a Tivoli Access Manager secure domain.

The Tivoli Access Manager Runtime for Java component is the only Tivoli AccessManager component that must be installed on a system to run a Tivoli AccessManager Java application.

The Tivoli Access Manager Runtime for Java component is not needed for runningJava applications.

Note: Information about installing the Tivoli Access Manager Runtime for Javacomponent can be found in the IBM Tivoli Access Manager for e-business:Installation Guide.

For information about troubleshooting Java applications with Tivoli AccessManager, see the IBM Tivoli Access Manager for e-business: Troubleshooting Guide.


Chapter 2. Authorization API Java classes overview

This chapter provides an overview of the Tivoli Access Manager authorization APIJava classes:v “Classes from com.tivoli.pd.jazn package” on page 8v “Classes from com.tivoli.pd.jutil package” on page 11

Refer to the Javadoc information in the Tivoli Access Manager ADK for detaileddocumentation about all these classes.

Review Appendix B, “Deprecated Java classes and methods,” on page 41 beforemodifying an existing Java application. A number of classes and methods havebeen deprecated in this version of Tivoli Access Manager.


Classes from com.tivoli.pd.jazn packagev “PDAuthorizationContext: method and constructor summary” on page 8v “PDLoginModule: method and constructor summary” on page 8v “PDPermission: method and constructor summary” on page 9v “PDPrincipal: method and constructor summary” on page 9

PDAuthorizationContext: method and constructor summaryThe PDAuthorizationContext class

Refer to the Javadoc information in the Tivoli Access Manager ADK for detaileddocumentation about this class.

Table 2. Methods and constructor for PDAuthorizationContext class

Methods and Constructors Description

PDAuthorizationContext Constructor that creates an instance of thePDAuthorizationContext class.

close Close this context.

getMode Return the mode this application isconfigured for.

PDLoginModule: method and constructor summaryThe PDLoginModule class handles the authentication of a Tivoli Access Manageruser using the Java Authentication and Authorization Service (JAAS) and creates aPDPrincipal object containing the Tivoli Access Manager user credentials whenauthentication is successful.


Table 3. Methods and constructor for PDLoginModule class


PDLoginModule Constructor that creates an instance of thePDLoginModule class.

abort Abort the authentication (second phase).

commit Commit the authentication (second phase).

getDefaultAuthorizationContext Get default Tivoli Access Managerauthorization context for all instances of thePDLoginModule class.

initialize Initialize this LoginModule.

login Authenticate the user (first phase).

logout Logout the user.

setDefaultAuthorizationContext Set default Tivoli Access Managerauthorization context for all instances of thePDLoginModule class.


PDPermission: method and constructor summaryThe PDPermission class represents an authorization permission for accessing aresource object in the secure domain. PDPermission uses Tivoli Access Manager asthe authorization engine for normal Java 2 permission checks.


Table 4. Methods and constructors for PDPermission class


PDPermission Constructors that create an instance of thePDPermission class.

equals Determines whether this PDPermission isequivalent to the input object.

getActions Returns a String representation of this object.

getPDException Provides access to any exception informationreceived on the last implies (Permission)call.

hashCode Returns the hash code value for this object.

implies Methods that determine if Tivoli AccessManager grants the permissions in thisPDPermission object to the specifiedPDPrincipal.

PDPrincipal: method and constructor summaryThe PDPrincipal class implements the Principal interface and contains thecredentials of an authenticated Tivoli Access Manager user.


Table 5. Methods and constructors for PDPrincipal class


PDPrincipal Constructors that create an instance of thePDPrincipal class.

addAttribute Return a new PDPrincipal that contains theadded credential attribute.

addAttrlist Return a new PDPrincipal that contains themodified credential attribute list.

addGroupMemberships Return a new PDPrincipal that adds thesegroup memberships to the currentPDPrincipal

equals Compares the specified Object with thisPDPrincipal for equality.

getAttribute Return the values for a given attribute.

getAttributeNames Return the attribute names in the credentialattribute list.

getAttributeValue Return the value for a given attribute.

Chapter 2. Authorization API Java classes overview 9

Table 5. Methods and constructors for PDPrincipal class (continued)


getAttrlist Return a copy of the credential attribute listfor this principal.

getEntitlements Return all the objects to which thisPDPrincipal has the specified access.

getName Return a string name of this PDPrincipal.

getPAC Obtain an architecture and networkindependent encoding of this principal.

hashCode Return a hash code for this PDPrincipal.

implies Check if the specified Subject is implied bythis object.

readExternal Read the state of the PDPrincipal instancefrom a stream.

removeAttribute Return a new PDPrincipal that does notcontain the named attribute.

setAttribute Return a new PDPrincipal that contains themodified attribute.

setAttrlist Return a new PDPrincipal that contains themodified credential attribute list.

setContext Set the authorization context of thisPDPrincipal instance.

toString Return a string representation of thisPDPrincipal.

writeExternal Save the state of the PDPrincipal instance toa stream (that is, serialize it).


Classes from com.tivoli.pd.jutil packagev “PDAttrs: method and constructor summary” on page 11v “PDAttrValue: method and constructor summary” on page 12v “PDAttrValueList: method and constructor summary” on page 12v “PDAttrValues: method and constructor summary” on page 13v “PDStatics” on page 13

PDAttrs: method and constructor summaryThe PDAttrs class represents a collection of attributes. Attributes are used toencapsulate input and output data sent to and received from authorization andadministration service functions. Each attribute consists of entries that have a nameand one or more values. The names are Strings, and the values can of type String,byte array, Long, or PDAdmSvcPobj.

Several of the constructors for this class use the context parameter, of classcom.tivoli.pd.jutil.PDBasicContext. This class is a superclass of the Tivoli AccessManager contexts. The context to be passed for the authorization APIs is a subclasssuch as PDContext.


Table 6. Methods and constructors for PDAttrs class


PDAttrs Constructors that create an instance of thePDAttrs class.

add Methods for adding the specified value tothe collection of values for the specifiedname in this PDAttrs.

addAll Adds all the elements in the specifiedPDAttrs to this PDAttrs.

allowDups Returns the current value of allowDups.

clear Clears the current PDAttrs.

clone Clones the current PDAttrs.

delete Removes the named attribute from thePDAttrs.

entrySet Return a Set view of the entries in thePDAttrs.

equals Indicates whether some other Object is equalto this one.

get Deprecated. Use getValues instead.

getAttrlist_t Method getAttrlist_t.

getNames Method getNames.

getQoP Returns the current value of QoP.

getValues Returns the values to which this PDAttrsmaps the specified key.

hashCode Returns a hashcode for the current object.


Table 6. Methods and constructors for PDAttrs class (continued)


iKeySet Method iKeySet.

keySet Returns a set view of the keys contained inthis PDAttrs.

setAttrlist_t Method getAttrlist_t.

setQoP Sets the current value of QoP.

size Returns the number of key-values mappingsin the current PDAttrs.

toString Returns a String representation of this object.

PDAttrValue: method and constructor summaryThe PDAttrValue class represents the value of a Tivoli Access Manager attribute. Avalue may be a String, a byte array, a Long, or a PDAdmSvcPobj.


Table 7. Methods and constructors for PDAttrValue class


PDAttrValue Constructors that create an instance of thePDAttrValue class.

clone Returns a clone of the object.


getType Returns the type of the current attributevalue.

getValue Returns the value of the current attribute,which can then be examined.



PDAttrValueList: method and constructor summaryThe PDAttrValueList class represents the list of values for one attribute. Each valuemust be a PDAttrValue. The list is ordered and allows duplicates.


Table 8. Methods and constructors for PDAttrValueList class


PDAttrValueList Constructors that create an instance of thePDAttrValueList class.

add Methods for inserting the specified elementat the specified position in this list, movingall subsequent elements to a higher index.


Table 8. Methods and constructors for PDAttrValueList class (continued)


addAll Methods for inserting all the elements in thespecified collection into this list, starting atthe specified offset, shifting any subsequentelements to a higher index.

clone Returns a clone of this object.



set Replaces the element at the specifiedposition in this list with the specifiedelement.


PDAttrValues: method and constructor summaryThe PDAttrValues class represents a collection of values for a particular PDAttr.This particular implementation is a Set, so duplicates are not allowed in aparticular PDAttrValues object.


Table 9. Methods and constructors for PDAttrValues class


PDAttrValues Constructors that create an instance of thePDAttrValues class.

add Methods for adding the input PDAttrValueto this PDAttrValues.

addAll Adds all the elements in the specifiedcollection to this collection.

clone Returns a clone of this object.

encode




PDStaticsThe PDStatics class contains various constants used in the Java administration andauthorization classes.




Chapter 3. Java security

The Tivoli Access Manager authorization Java classes provide an implementationof Java security code that is fully compliant with the Java 2 security model and theJava Authentication and Authorization Service (JAAS).

This chapter contains the following topics:v “Java 2 security with Tivoli Access Manager” on page 16v “Java Authentication and Authorization Service (JAAS) model” on page 17


Java 2 security with Tivoli Access ManagerThe Java 2 security architecture is policy-based, and allows for fine-grained accesscontrol. When code is loaded, it is assigned permissions based on the security policycurrently in effect. Each permission specifies a permitted access to a particularresource, such as read access to a specified file, or connect access to a specified hostand port. The policy specifies which permissions are available for code fromvarious signers and locations. The policy can be initialized from an externalconfiguration file.

Code can access a resource only if the permission that guards the resource givesthe code explicit permission. These new concepts of permission and policy enablethe Java 2 to offer fine-grained, highly configurable, flexible, and extensible accesscontrol. Such access control can now be specified for all Java code, includingapplications, beans, and servlets.

The Tivoli Access Manager authorization server provides an SSL-based accessmode for handling remote authorization calls. The Tivoli Access Manager Javaauthorization API uses this socket-based capability to provide functionalityequivalent to that provided in the authorization C API by theazn_decision_access_allowed_ext() function.

The azn_decision_access_allowed_ext() function requires the followinginformation:v Authentication informationv Resource namev Access mode

The Java 2 permission model provides the resource name and the access mode.The Java Authentication and Authorization Service (JAAS) extensions to the Java 2model provide the authentication information.

Tivoli Access Manager functions as a back end for normal Java 2 permission checksby providing:v A custom JAAS LoginModule that manufactures authentication credentials.v A custom permission class that knows how to locate and call Tivoli Access

Manager.


Java Authentication and Authorization Service (JAAS) modelThe Java 2 permission model takes into account the following information:v The physical origin (the directory or URL) of the classes that are currently active.v The logical origin of those classes.v The identity of the organization that produced the classes, as proved by digital

signature.

This model serves well the browsers that first popularized Java, as it dealseffectively with the issues of mobile code.

JAAS augments the current Java 2 runtime with knowledge of the user who istrying to run the application. This knowledge provides the authenticationinformation needed when implementing the security model.

JAAS augments the Java 2 security model to enable the following features:v Specification of permissions based on a user identity.v Enforcement of those permissions at application runtime.

These two features provide the authorization functionality needed whenimplementing the security model.

The following sections describe how Tivoli Access Manager authorization JavaClasses use the JAAS model:v “Authenticating users and obtaining credentials” on page 17v “Authorizing access requests” on page 18

Authenticating users and obtaining credentialsThe Tivoli Access Manager Java-based authentication feature is built around theJava Authentication and Authorization Services (JAAS) model.

Note: More information on the JAAS can be found at this Web site:http://java.sun.com/javase/technologies/security/

Tivoli Access Manager provides one JAAS LoginModule. You can use the module intwo different ways. You can use it to authenticate a user and obtain the usercredentials. Alternatively, you can use it just to obtain the user credentials.

Authenticating with a user name and passwordIn order to authenticate a user, the JAAS LoginModule requires that the callingapplication to provide the following:v A principal name, specified as either a short name or an X.500 name (DN)v A password

The LoginModule authenticates the principal and returns the Tivoli AccessManager credential. The LoginModule expects the calling application to provide thefollowing information:v The user name, through a javax.security.auth.callback.NameCallback.v The password, through a javax.security.auth.callback.PasswordCallback.

When the Tivoli Access Manager credential is successfully retrieved, theLoginModule creates a Subject and a PDPrincipal.

Chapter 3. Java security 17

http://java.sun.com/javase/technologies/security/

Retrieving credentials without authenticatingTo retrieve credentials without authenticating, the calling application can call theJAAS LoginModule with only a principal name specified as a short name or anX.500 distinguished name (DN).

The LoginModule expects the calling application to provide the user name througha javax.security.auth.callback.NameCallback.

The login configuration fileYou can use the optional entry nameOnly in the login configuration file to specifywhich of two login modes your application uses. You can configure the module torequire either a user name and a password (default behavior), or only a user name.

To require only the user name, specify nameOnly=true in the configuration file. SeeFigure 1 on page 27.

If nameOnly is omitted or specified to be "false", both the user name and thepassword are required.

Authorizing access requestsThe Tivoli Access Manager authorization Java classes are built around JAAS andthe Java 2 security model. The Tivoli Access Manager API closely follows the Java2 permission model.

Note: For more information on the Java 2 security model, see:http://java.sun.com/javase/technologies/security/

The Tivoli Access Manager authorization API Java classes provide a permissionclass named com.tivoli.pd.jazn.PDPermission . This class extends the abstractclass com.ibm.IBMPermission, which extends the abstract classjava.security.Permission. The PDPermission class establishes the SSL-protectedsocket communications protocol which is used to talk to Tivoli Access Manager.

An entry needs to be made in the JAAS policy file to ensure that the JAAS securitycode calls the implies() method in the PDPermission class described here. Thisentry could be made specific to particular codebase, as required.

You must define your JAAS policy in its own file and specify the URL in thejava.security file using the property auth.policy.url.X (where X is an integer). Forexample:auth.policy.url.1=file:${java.home}/lib/security/jaas.policy

Alternatively, you can use the Java interpreter -D flag to specify the JAAS policyfile. For example:java -Dauth.policy.url.1=file:/opt/PolicyDirector/etc/jaas.policy

You can specify the JAAS policy directly in the java.policy file found injava_home/lib/security.grant signedBy “xxx” codeBase “file:/E:/Program Files/aaa/bbb/ccc”principal com.tivoli.pd.jazn.PDPrincipal “*” {permission com.tivoli.pd.jazn.PDPermission “ignoreme” "a";};

The contents of the action string ignoreme are unimportant because thePDPermission class ignores them. This is because Tivoli Access Manager acts as the



repository for security policy. The intent of this entry is to have the Java securitycode call the implies() method when a resource manager checks to see if apermission is held.

The PDPermission class implements constructors and supporting methods,including:

implies()Checks whether Tivoli Access Manager grants the specified permissions.

equals()Determines if two PDPermission objects are equal.

getActions()Returns the canonical string representation of the actions.

hashCode()Returns the hash code value for the object.

The implies() method flow consists of the following steps:1. Use the static getSubject() method to retrieve the current Subject. (Subject

was created by the PDLoginModule class, and placed on the current thread ofexecution by the resource manager.)

2. If the Subject contains a Principal of type com.tivoli.pd.jazn.PDPrincipal,then the appropriate credentials are secured for the call to Tivoli AccessManager.

The following example illustrates one way a resource manager, such as a Webserver or Enterprise Java Beans container, would place the Subject on the currentthread of execution.Subject.doAs(whoami, new java.security.PrivilegedAction() {public java.lang.Object run() {}});

At this point the PDPermission class has all the information required to make theauthorization call to Tivoli Access Manager.

The following code sample shows a typical authorization check that invokes TivoliAccess Manager through the PDPermission class implementation. ThecheckPermission() method returns quietly unless it fails, in which case it throws ajava.lang.SecurityException.PDPermission perm = new PDPermission(“/MyResourceManager/private”,

“[simple]rT[newActionGroup1]Z”);

SecurityManager.checkPermission(perm);

Chapter 3. Java security 19


Chapter 4. Java application development

This chapter contains the following topics:v “Configuring a Java application into the secure domain” on page 22v “Configuring the Java Authentication and Authorization Service” on page 27v “Developing a resource manager” on page 28v “Making authorization decisions outside of Java 2” on page 29v “Obtaining entitlements for a specified user” on page 30


Configuring a Java application into the secure domainJava applications that use Tivoli Access Manager security must be configured intoa Tivoli Access Manager secure domain. Tivoli Access Manager provides a utilityclass called com.tivoli.pd.jcfg.SvrSslCfg that can be used to accomplish thenecessary configuration and unconfiguration tasks. This section describes thosetasks, and provides example command-line syntax for each task.

You can use SvrSslCfg to accomplish the following tasks:v “Configuring an application server” on page 23v “Unconfiguring an application server” on page 24v “Adding a policy or authorization server” on page 24v “Removing a policy or authorization server” on page 24v “Changing a policy or authorization server” on page 25v “Replacing a certificate” on page 25v “Setting the port” on page 25v “Setting the database directory” on page 25v “Setting the database refresh interval” on page 25v “Setting the application listening mode” on page 25v “Setting the certificate refresh option” on page 26

The examples in this chapter use the values shown in Table 10 on page 22:

Table 10. Sample information used for SvrSslCfg examples

Information Value

Administrator user ID sec_master

Administrator password secpw

Policy server, TCP/IP communications portnumber, and rank (default port is 7135)

ampolicy.myco.com:7135:1

This entry can also be used to specify apolicy server proxy. The location, port, andrank of the policy server proxy must bespecified. The default port for a proxy is7138.

Authorization server, TCP/IPcommunications port number, and rank(default port is 7136)

amazn.myco.com:7136:1

Host name of Java application system jsys.myco.com

TCP/IP port on which the application serverlistens for communications from the policyserver

999

Application server password pw

Tivoli Access Manager application ID PDPermissionjapp

The application ID must be unique. Otherinstances of the application running on thisor other systems must each be given aunique ID.

Tivoli Access Manager domain mydomain


Table 10. Sample information used for SvrSslCfg examples (continued)

Information Value

Configuration file (Windows example)c:\am\config_file.conf

Note that SvrSslCfg creates thisconfiguration file when called with –actionconfig. When SvrSslCfg is called with otheroptions (for example, –action addsvr), theconfiguration file is expected to exist.

Keystore file (Windows example)c:\am\keystore_file.ks

Note that SvrSslCfg creates this keystore filewhen called with –action config. WhenSvrSslCfg is called with other options (forexample, –action addsvr), the keystore fileis expected to exist.

A detailed command reference for the –action config class can be found inAppendix A, “com.tivoli.pd.jcfg.SvrSslCfg,” on page 33

Configuring an application serverTivoli Access Manager uses a self-generated and self-signed certificate toauthenticate its Secure Sockets Layer (SSL) communications. The Tivoli AccessManager authorization API Java classes must be able to determine the certificatethat Tivoli Access Manager is using in order to establish its SSL communication.You also must establish an identity for the Java application. The SvrSslCfg class isused to create a Tivoli Access Manager user account for an application server andto store the server configuration and certificate information in local configurationand keystore files.

After obtaining the necessary information, use the SvrSslCfg option -actionconfig to create the Tivoli Access Manager application name, the configuration file,and the keystore file. Configuring an application server creates user and serverinformation in the user registry as well as creates local configuration and keystorefiles.

When using -action config, you must also specify whether you are creating orreplacing the configuration and keystore files. The -cfg_action create option isused to initially create the configuration and keystore files. Use cfg_actionreplace if these files already exist. If the -cfg_action create option is used andthe configuration or keystore files already exist, an exception is thrown.

Tivoli Access Manager supports application servers in either remote mode or localmode. The following section shows a sample configuration command for eachmode.

Configuring remote modeBased on the sample information shown in Table 10 on page 22, the command toestablish an SSL connection between japp.myco.com and the Tivoli Access Managersecure domain, in remote mode, could be as follows:java com.tivoli.pd.jcfg.SvrSslCfg -action config

-admin_id sec_master -admin_pwd secpw-appsvr_id PDPermissionjapp -appsvr_pwd pw -host jsys.myco.com

Chapter 4. Java application development 23

-mode remote -port 999 -policysvr ampolicy.myco.com:7135:1-authzsvr amazn.myco.com:7136:1 -cfg_file c:/am/config_file.conf-key_file c:/am/keystore_file.ks -domain mydomain -cfg_action create-certrefresh true

Configuring local modeBased on the sample information shown in Table 10 on page 22, the command toestablish an SSL connection between the Java application and Tivoli AccessManager secure domain in local mode might be as follows:java com.tivoli.pd.jcfg.SvrSslCfg -action config

-admin_id sec_master -admin_pwd secpw-appsvr_id PDPermissionjapp -host jsys.myco.com-mode local -port 999 -policysvr ampolicy.myco.com:7135:1-authzsvr amazn.myco.com:7136:1 -cfg_file c:/am/config_file.conf-key_file c:/am/keystore_file.ks -domain mydomain -cfg_action create-certrefresh true

Unconfiguring an application serverThe -action unconfig option removes the user and server information from theuser registry, deletes the local keystore file and removes information for thisapplication from the configuration file but does not delete the configuration file.java com.tivoli.pd.jcfg.SvrSslCfg -action unconfig \

-admin_id sec_master -admin_pwd secpw \-appsvr_id PDPermissionjapp -host jsys.myco.com \-policysvr ampolicy.myco.com:7135:1 \-cfg_file c:/am/config_file.conf -domain mydomain

The unconfiguration operation fails only if the caller is unauthorized or the policyserver cannot be contacted.

Adding a policy or authorization serverThe -action addsvr option adds a policy or authorization server to the applicationserver configuration file.

To add a policy server:java com.tivoli.pd.jcfg.SvrSslCfg -action addsvr \

-policysvr ampolicy3.myco.com:7135:2 \-cfg_file c:/am/config_file.conf

To add an authorization server:java com.tivoli.pd.jcfg.SvrSslCfg -action addsvr \

-authzsvr am2azn.myco.com:7136:2 \-cfg_file c:/am/config_file.conf

Removing a policy or authorization serverThe -action rmsvr option to remove a policy or authorization server from theconfiguration file.

To remove a policy server:java com.tivoli.pd.jcfg.SvrSslCfg -action rmsvr \

-policysvr ampolicy.myco.com:7135:1 \-cfg_file c:/am/config_file.conf

To remove an authorization server:java com.tivoli.pd.jcfg.SvrSslCfg -action rmsvr \

-authzsvr amazn.myco.com:7136:1 \-cfg_file c:/am/config)file.conf


Changing a policy or authorization serverUse the -action chgsvr option to change the port or rank for a policy orauthorization server in the configuration file. Do not use this option to change thehost name.java com.tivoli.pd.jcfg.SvrSslCfg -action chgsvr \

-policysvr ampolicy2.myco.com:7135:2 \-cfg_file c:/am/config_file.conf

orjava com.tivoli.pd.jcfg.SvrSslCfg -action chgsvr \

-authzsvr amazn.myco.com:7136:1 \-cfg_file c:/am/config_file.conf

Replacing a certificateThe certificate in the keystore expires based on the certificate lifetime set on thepolicy server. After the certificate expires, the -action replcert option must be usedto generate a new certificate. The new certificate replaces the existing certificate inthe application server keystore file. If a certificate become compromised, -actionreplcert option can be used to invalidate an existing certificate.java com.tivoli.pd.jcfg.SvrSslCfg -action replcert \

-admin_id sec_master -admin_pwd secpw \-appsvr_id PDPermissionjapp -cfg_file c:/am/config_file.conf

Setting the portUse the -action setport option to set the port on which the application serverlistens. This only updates the application server configuration file.java com.tivoli.pd.jcfg.SvrSslCfg -action setport \

-port 4321 -cfg_file c:/am/configfile

Setting the database directoryUse the -action setdbdir option on local-mode application servers to set thedirectory where a local copy of the policy database is stored. This only updates theapplication server configuration file.java com.tivoli.pd.jcfg.SvrSslCfg -action setdbdir \

-dbdir c:/production/policy -cfg_file c:/am/config_file.conf

Setting the database refresh intervalUse the -action setdbref option on local-mode application servers to set therefresh interval for the local copy of the policy database. The time interval isspecified in seconds. This only updates the application server configuration file.The following example sets the interval to every 60 minutes.java com.tivoli.pd.jcfg.SvrSslCfg -action setdbref \

-dbrefresh 3600 -cfg_file c:/am/config_file.conf

Setting the application listening modeUse the -action setdblisten option on local-mode application servers to indicatewhether the application listens for policy database update notifications. This onlyupdates the application server configuration file.java com.tivoli.pd.jcfg.SvrSslCfg -action setdblisten \

-dblisten true -cfg_file c:/am/config_file.conf


Setting the certificate refresh optionUse the -action setcertref option on remote and local mode application serversto indicate whether the application server certificate is automatically renewed. Iftrue, the application server certificate is checked at application start time. If thecertificate age is greater than one half its lifetime, then the certificate is renewed.


Configuring the Java Authentication and Authorization ServiceThis section describes how to set up and use a login configuration file with theTivoli Access Manager authorization API Java classes. The Tivoli Access Managerconfiguration steps follow the configuration methods supported by the JavaAuthentication and Authorization Service (JAAS).

This section does not provide an overview of all the JAAS configuration options.To review the JAAS configuration information, see the following Web site:http://java.sun.com/products/jaas

Complete the instructions in the following sections:v “Creating a login configuration file” on page 27v “Specify the login file location” on page 27

Creating a login configuration fileUse the sample file shown in Figure 1 as the basis for creating a loginconfiguration file for use with Tivoli Access Manager. No default loginconfiguration file is shipped as part of Tivoli Access Manager.

Note that the last stanza allows applications that use pd-nopass in theirLoginContext constructor to simply supply user names but not passwords. Formore information about the PDLoginModule and nameOnly, see “The loginconfiguration file” on page 18 or see the Javadoc information forcom.tivoli.pd.jazn.PDLoginModule.

Specify the login file locationChoose one of the following ways to specify the location of the login file:v Point to the login configuration file from the JAVA_HOME/jre/lib/security/

java.security file.For example, a sample entry from the java.security file might look like this:login.config.url.1=file:d:/Java/j142ibm/jre/lib/security/config.pd

v Specify the appropriate -D option on the java command-line invocation, such as:–Djava.security.auth.login.config=./config.pd

For more information, see the JAAS configuration documentation.

//// config.pd: Login configuration file for PDLoginModule

pd-debug {com.tivoli.pd.jazn.PDLoginModule required debug=true;

};

pd {com.tivoli.pd.jazn.PDLoginModule required;

};

pd-nopass {com.tivoli.pd.jazn.PDLoginModule required nameOnly=true;};

Figure 1. JAAS login configuration file



Developing a resource managerA resource manager is a Java application that uses the JAAS and the Tivoli AccessManager authorization API Java classes to make access control decisions. Thesample code in Figure 2 illustrates the tasks that the resource manager mustperform.

// Identify the configuration status and callback routinelc = new LoginContext(“pd-debug”, np);

// Drive the login() and commit() methods of the LoginModule classlc.login();whoami = lc.getSubject();System.out.println(whoami);

// Become that userSubject.doAsPrivileged(whoami, new java.security.PrivilegedAction() {

public java.lang.Object run() {boolean worked;java.security.Permission perm = new PDPermission(“/test/private”, “a”);try {

// sm is a reference to a SecurityManagersm.checkPermission(perm);worked = true;

}catch (AccessControlException e) {

if (VERBOSE) e.printStackTrace();worked = false;

}if (worked) {

System.out.println(“user “ + user + “ has\”\””+perm.getActions()+”\” permission(s) to target“+perm.getName());

} else {System.out.println(“user “ + user + “ DOES NOT HAVE

\”\””+perm.getActions()+”\” permission(s) to target“+perm.getName());

}}

}, (java.security.AccessControlContext)null ) ;

Figure 2. Resource manager task example


Making authorization decisions outside of Java 2The Tivoli Access Manager authorization API Java classes also support acompletely Java-compliant usage of the Tivoli Access Manager authorization checkthat is outside of the Java 2 and JAAS framework.

The PDPrincipal class includes the implies() method for performing authorizationchecks. To construct a PDPrincipal, a PDAuthorizationContext specifying theappropriate domain is required. Specifying the user name and password on theconstructor results in authentication to Tivoli Access Manager during constructionof the object.

Specifying the user name and no password on the constructor results in a securitycheck on the current environment.

The permission that must be held is:permission javax.security.auth.AuthPermission “createPDPrincipal”

If authorized, the constructor retrieves the authentication information from TivoliAccess Manager for that entity. The names that are supported on these constructorscan either be Tivoli Access Manager short names, or distinguished names.

Before calling the implies() method, construct a PDAuthorization context andconstruct a PDPrincipal object for the specified entity. Next, construct aPDPermission with the name of the requested resource, the protected object, andthe requested action to be performed on that object.

Then invoke the PDPrincipal.implies(PDPermission) method to determine if therequested access to the specified object is allowed for the specified entity.

The sample in Figure 3 shows an example of how to perform these tasks.

PDAuthorizationContext ctxt = new PDAuthorizationContext(configURL);PDPrincipal whoIsIt = new PDPrincipal(ctxt, "tom", "letmein", toCharArray());PDPermission whatTheyWant = new PDPermission(ctxt, “everything”, “abT”);boolean haveAccess = whoIsIt.implies(whatTheyWant);if (haveAccess) {

// let them proceed...} else {

// deny the requested access}

Figure 3. Example showing authorization outside of Java 2


Obtaining entitlements for a specified userThe authorization API supports a service plug-in model that enables developers toadd modules that extend the capabilities of Tivoli Access Manager. Theentitlements service plug-in is the only type of plug-in that is callable from a Javaapplication at this time.

An entitlements service plug-in enables authorization API applications for aspecific Tivoli Access Manager secure domain to retrieve the entitlements for a userfrom the policy repository for that secure domain. An entitlements service allows athird-party application running in the secure domain to call a specific entitlementsservice based on its service ID. If no service ID is provided, the defaultentitlements service plug-in is called. An entitlements service plug-in, like otherauthorization service plug-ins, must be installed and configured before use.

Tivoli Access Manager provides a default entitlement service called the TivoliAccess Manager protected objects entitlements service that is specific to the TivoliAccess Manager environment. This entitlements service plug-in accepts a single,multi-valued string attribute that specifies one or more root nodes for searchingthe Tivoli Access Manager protected object space along with an indicator of whataccess permissions are required. The plug-in returns a multi-valued attribute list ofprotected objects meeting the search criteria.

This entitlement service can be called from a Java application by using thePDPrincipal.getEntitlements method, which is equivalent to using theazn_entitlements_get_entitlements() function from a C application. Figure 4shows a call to the protected objects entitlements service requesting a list of objectsin the /AppData/AccountData and /AppData/EmployeeData object trees to which theprincipal has view and modify permission.

PDAttrs attrsIn = new PDAttrs(myctxt, true);PDAttrs attrsOut = new PDAttrs(myctxt, true);

// Does user have view and modify access to desired resources?

attrsIn.add(PDStatics.AZN_ENT_SVC_PD_POBJ_PATH,"/AppData/AccountData");

attrsIn.add(PDStatics.AZN_ENT_SVC_PD_POBJ_PATH,"/AppData/EmployeeData");

attrsIn.add(PDStatics.AZN_ENT_SVC_PD_POBJ_REQD_OPS,"vm");

attrsOut = principal.jazn.getEntitlements(myctxt, PDStatics.AZN_ENT_SVC_PD_POBJ,attrsIn);

// Is user entitled to anything?

PDAttrValues results = attrsOut.getValues(PDStatics.AZN_ENT_SVC_PD_POBJ_MATCHES);

if ((results == null) || (results.isEmpty())) {System.out.println("Nothing found.");break major;

}

// Process String or byte array results...

Figure 4. Using the PDPrincipal.getEntitlements method


The protected objects entitlements service returns a multi-valued attribute list ofthe protected objects to which the principal has the specified access permission.The protected objects returned to the attribute list are either byte array or Stringentries. The sample code in Figure 5 demonstrates printing the results.

Additional information about the entitlements service plug-in as well as the othertypes of authorization service plug-ins can be found in the IBM Tivoli AccessManager for e-business: Authorization C API Developer Reference.

// Print output attributes if any returnedSet s = attrsOut.keySet();if(!s.isEmpty()){

System.out.println("Attributes returned: ");System.out.println(attrs);

} elseSystem.out.println("No attributes returned.");

Figure 5. Processing PDAttrs returned



Appendix A. com.tivoli.pd.jcfg.SvrSslCfg

This class is used to configure, unconfigure, and modify the configurationinformation associated with a Tivoli Access Manager Java application server.public class SvrSslCfg extends java.lang.Object {

public static void main (java.lang.String[] argv)throws PDException

}

The use of the com.tivoli.pd.jcfg.SvrSslCfg class can be summarized as follows:java com.tivoli.pd.jcfg.SvrSslCfg -action ( config | unconfig | addsvr |

rmsvr | chgsvr | setport |setdblisten | setdbref | replcert }

-admin_id admin_user_ID-admin_pwd admin_password-appsvr_id application_server_name-appsvr_pwd application_server_password-port port_number-mode { local | remote }-host Host_name_of_application_server-policysvr policy_server_name:port:rank [,...]-authzsvr authorization_server_name:port:rank [,...]-cfg_file fully_qualified_name_of_configuration_file-domain Tivoli_Acccess_Manager_domain-key_file fully_qualified_name_of_keystore_file-msg_id message_identifier-dblisten { true | false }-dbrefresh refresh_interval_in_seconds-dbdir name_of_directory_for_local_policy_database-cfg_action { create | replace }-certrefresh { true | false }

Compatibility Note: The com.tivoli.mts.SvrSslCfg class has been deprecated inTivoli Access Manager. Existing applications should bemodified to use the new com.tivoli.pd.jcfg.SvrSslCfg classas the deprecated class will be removed in a future version ofthe product.

After the successful configuration of a Tivoli Access Manager Java applicationserver, SvrSslCfg creates a user account and server entries representing the Javaapplication server in the Tivoli Access Manager user registry. In addition,SvrSslCfg creates a configuration file and a Java keystore file, which securelystores a client certificate, locally on the application server. This client certificatepermits callers to make authenticated use of Tivoli Access Manager services.Conversely, unconfiguration removes the user and server entries from the userregistry and cleans up the local configuration and keystore files.

The contents of an existing configuration file can be modified by using theSvrSslCfg class. The configuration file and the keystore file must already existwhen calling SvrSslCfg with all options other than –action config or –actionunconfig.

A complete list of the actions available in the SvrSslCfg class are outlinedfollowing the description of the parameters in Table 11 on page 34.


You can specify multiple policy servers and authorization servers, giving each onea numeric rank, in the -policysvr and -authzsvr options of thecom.tivoli.pd.jcfg.SvrSslCfg Java class.

The rank specifies in what order the application attempts to connect to the definedservers. For example, if two servers are specified, one with rank 1 and anotherwith rank 2, the application attempts to connect to the server with rank 1. If aconnection cannot be established to server 1, the application will failover andattempt to connect to the server with rank 2.

Even if only one server is specified, it still must have a rank setting.

Note: The following options are parsed and processed into the configuration file,but are otherwise ignored in this version of Tivoli Access Manager:v –portv –mode localv –dblistenv –dbdirv –dbrefresh

Table 11. Description of parameters for the SvrSslCfg configuration action.

SvrSslCfg Parameter Value

–admin_id user_ID A Tivoli Access Manager user with administrativeprivileges. This parameter is required.

–admin_pwd password Password associated with the Tivoli Access Manageradministrative user specified. This parameter is required.

–appsvr_id name The name of the application server. This parameter isrequired.

–port port_number The TCP/IP port which the application server listens tofor policy server notifications. This parameter is required.

–mode { local | remote } Indicates whether the application server processesrequests remotely or locally. This parameter is required.

–policysvr hostname:port:rank[,hostname2:port2:rank2...]

A list of Tivoli Access Manager policy servers to whichthe application server can communicate. Format of thisentry is host name, TCP/IP port number, and numericrank, separated by colons. Multiple servers can bespecified by separating them with commas.

For example, the following indicates two policy servers,both using default TCP/IP port 7135, are available:

primary.myco.com:7135:1,secondary.myco.com:7135:2

This parameter is required.


Table 11. Description of parameters for the SvrSslCfg configuration action. (continued)


–authzsvr hostname:port:rank[,hostname2:port2:rank2...]

A list of Tivoli Access Manager authorization servers towhich the application server can communicate. Format ofthis entry is host name, TCP/IP port number, andnumeric rank, separated by colons. Multiple servers canbe specified by separating them with commas.

For example, the following indicates 2 authorizationservers, both using default TCP/IP port 7136, areavailable:

secazn.myco.com:7136:2,primazn.myco.com:7136:1


–cfg_file file_name Fully qualified name of the configuration file on theapplication server. SvrSslCfg –action config creates thisfile. The filename should have a .conf suffix. You canspecify any valid name.


–key_file file_name Fully qualified name of the keystore file on theapplication server. SvrSslCfg –action config creates thisfile. The filename should have a .ks suffix. You canspecify any valid name.


–msg_id message_identifier An identifier that determines the directory in which tolocate the trace and log files that are generated whenusing this application server. This identifier is used onlyif Tivoli Common Directory logging is enabled for theTivoli Access Manager Runtime for Java. Refer to theIBM Tivoli Access Manager for e-business: TroubleshootingGuide for more information on Tivoli Common Directorylogging, message files and message file locations.

This parameter is optional. There is no default value.

–domain domain_name The Tivoli Access Manager domain for the applicationserver. This parameter is optional. The default value isthe local domain.

–appsvr_pwd password The password for the user account in the user registryassociated with the application server. This parameter isoptional. If it is specified, the password must meet thecurrent password rules in effect. If it is omitted, a defaultpassword is automatically generated.

–host host_name Host name of the application server. This parameter isoptional. The default value is the local host.

–desc description Description of the application server. This parameter isoptional. The default value is empty (no description).

–groups group_names The names of special groups the application serverbelongs to. This parameter is optional. The default valueis empty (no special groups).

–dblisten { true | false } Indicates whether the application server listens for policydatabase updates. This parameter is optional. The defaultvalue is true. This parameter is ignored when the modeparameter is set to remote.

Appendix A. com.tivoli.pd.jcfg.SvrSslCfg 35

Table 11. Description of parameters for the SvrSslCfg configuration action. (continued)


–dbdir directory_name The name of the directory to be used for the local copyof the policy database. This parameter is optional. If it isnot specified, the default directory is the db directory,located just under the Tivoli Access Manager installationdirectory:

installation_directory/db

This parameter is ignored when the mode parameter isset to remote.

–dbrefresh number_of_seconds Indicates the time interval, in seconds, that theapplication server polls the policy server for policydatabase updates. This parameter is optional. Value mustbe greater than or equal to zero. The default value is 600seconds, or every 10 minutes. This parameter is ignoredif the mode parameter is set to remote.

–cfg_action { create | replace } Indicates whether the configuration and keystore filesshould be created on the application server or replaced.This parameter is optional. The default action is replace.When the create option is specified but the files alreadyexist, an exception is raised. When the replace option isspecified, the configuration and keystore files mustalready exist.

–certrefresh { true | false } Indicates whether the application certificate must berenewed automatically at application startup. Thecertificate renewal is triggered when the certificatelifetime has past the half life point and has not alreadyexpired.

Note: The host name is used to build a unique name (identity) for the application.The pdadmin user list command displays the application identity name inthe following format:

server_name/host_name

The pdadmin server list command displays the server name in a slightlydifferent format:

server_name-host_name

–action configConfigures an application server. Configuring a server creates user and serverinformation in the user registry and creates local configuration and keystore fileson the application server. Use the –action unconfig option to reverse thisoperation.java com.tivoli.pd.jcfg.SvrSslCfg -action config

-admin_id admin_user_ID-admin_pwd admin_password-appsvr_id application_server_name-appsvr_pwd application_server_password-port port_number-mode { local | remote }[ -host Host_name_of_application_server ]-policysvr policy_server_name:port:rank [,...]


-authzsvr authorization_server_name:port:rank [,...]-cfg_file fully_qualified_name_of_configuration_file[ -domain Tivoli_Acccess_Manager_domain ]-key_file fully_qualified_name_of_keystore_file[ -cfg_action { create | replace } ]

–action unconfigUnconfigures an application server. Removes the user and server information fromthe user registry, deletes the local keystore file and removes information for thisapplication from the configuration file but does not delete the configuration file.The unconfiguration operation fails only if the caller is unauthorized or the policyserver cannot be contacted.java com.tivoli.pd.jcfg.SvrSslCfg -action unconfig

-admin_id admin_user_ID-admin_pwd admin_password-appsvr_id application_server_name[ -host host_name_of_application_server ]-policysvr policy_server_name:port:rank [,...]-cfg_file fully_qualified_name_of_configuration_file[ -domain Tivoli_Acccess_Manager_domain ]

Note: This action can succeed when there is no configuration file. When theconfiguration file does not exist, it is created and used as a temporary file tohold configuration information during the operation, and then the file isdeleted completely.

–action addsvrAdds a policy or authorization server to the application server configuration file.java com.tivoli.pd.jcfg.SvrSslCfg -action addsvr

{ -policysvr policy_server_name |-authzsvr authorization_server_name }

-cfg_file fully_qualified_name_of_configuration_file

The configuration file must exist when this action is called.

–action rmsvrRemoves a policy or authorization server from the application server configurationfile.java com.tivoli.pd.jcfg.SvrSslCfg -action rmsvr



–action chgsvrChanges the port or preference ranking of a policy or authorization server in theapplication server configuration file.java com.tivoli.pd.jcfg.SvrSslCfg -action chgsvr



The configuration file must already exist when this action is called.


–action replcertReplaces a certificate in the application server keystore file. The certificate in thekeystore expires based on the certificate lifetime set on the policy server. After thecertificate expires, the -action replcert option must be used to generate a newcertificate. If a certificate become compromised the -action replcert option alsocan be used to invalidate an existing certificate.java com.tivoli.pd.jcfg.SvrSslCfg -action replcert

-admin_id admin_user_ID-admin_pwd admin_password-appsvr_id application_server_name-cfg_file fully_qualified_name_of_configuration_file


–action setportSets the port on which the application server listens for policy databasenotifications. This only updates the application server configuration file.java com.tivoli.pd.jcfg.SvrSslCfg -action setport

-port port_number-cfg_file fully_qualified_name_of_configuration_file


–action setdbdirSets the database directory. This only updates the application server configurationfile.java com.tivoli.pd.jcfg.SvrSslCfg -action setdbdir

-dbdir name_of_directory_for_local_policy_database-cfg_file fully_qualified_name_of_configuration_file


–action setdbrefSets the database refresh interval, in seconds. This only updates the applicationserver configuration file.java com.tivoli.pd.jcfg.SvrSslCfg -action setdbref

-dbrefresh refresh_interval_in_seconds-cfg_file fully_qualified_name_of_configuration_file


–action setdblistenSets the application listening mode. This only updates the application serverconfiguration file.java com.tivoli.pd.jcfg.SvrSslCfg -action setdblisten

-dblisten { true | false }-cfg_file fully_qualified_name_of_configuration_file



–action setcertrefSets the application certificate refresh mode. Indicates whether the applicationcertificate must be renewed automatically. The renewal works only if the certificatelifetime has past the half life point and has not already expired.java com.tivoli.pd.jcfg.SvrSslCfg -action setcertref

-certrefresh {true|false}-cfg_file fully_qualified_name_of_configuration_file



Appendix B. Deprecated Java classes and methods

For information about the deprecated Java classes and methods, refer to theJavadoc HTML documentation. For details about accessing this HTMLdocumentation, see “Accessing the Javadoc HTML documentation” on page 2.

Existing Java applications must be changed to use the indicated replacement classor method.



Appendix C. Support information

This section describes the following options for obtaining support for IBMproducts:v “Searching knowledge bases”v “Obtaining fixes”v “Registering with IBM Software Support” on page 44v “Receiving weekly software updates” on page 44v “Contacting IBM Software Support” on page 45

Searching knowledge basesIf you encounter a problem, you want it resolved quickly. You can search theavailable knowledge bases to determine whether the resolution to your problemwas already encountered and is already documented.

Searching information centersIBM provides extensive documentation in an information center that can beinstalled on your local computer or on an intranet server. You can use the searchfunction of this information center to query conceptual information, instructionsfor completing tasks, reference information, and support documents.

Searching the InternetIf you cannot find an answer to your question in the information center, search theInternet for the latest, most complete information that might help you resolve yourproblem. To search multiple Internet resources for your product, perform thefollowing steps:1. Expand the product folder in the navigation frame on the left.2. Expand Troubleshooting and support.3. Expand Searching knowledge bases.4. Click Web search.

From this topic, you can search various resources, which includes the followingresources:v IBM Technotesv IBM downloadsv IBM Redbooks®

v IBM developerWorks®

v Forums and news groupsv Google

Obtaining fixesA product fix might be available to resolve your problem. To determine what fixesare available for your IBM software product, check the product support site byperforming the following steps:1. Go to the IBM Software Support site at the following Web address:


http://www.ibm.com/software/support2. Under Products A - Z, click the letter with which your product starts to open a

Software Product List.3. Click your product name to open the product-specific support page.4. Under Self help, follow the link to All Updates, where you have a list of fixes,

fix packs, and other service updates for your product. For tips on refining yoursearch, click Search tips.

5. Click the name of a fix to read the description.6. Optional, download the fix.

Registering with IBM Software SupportBefore you can receive weekly e-mail updates about fixes and other news aboutIBM products, you need to register with IBM Software Support. To register withIBM Software Support, follow these steps:1. Go to the IBM Software Support site at the following Web address:

http://www.ibm.com/software/support2. Click Register in the upper right corner of the support page to establish your

user ID and password.3. Complete the form, and click Submit.

Receiving weekly software updatesAfter registering with IBM Software Support, you can receive weekly e-mailupdates about fixes and other news about IBM products. To receive weeklynotifications, follow these steps:1. Go to the IBM Software Support site at the following Web address

http://www.ibm.com/software/support2. Click the My support link to open the Sign in page.3. Provide your sign in information, and click Submit to open your support page.4. Click the Edit profile tab.5. For each product about which you want to receive updates, use the filters to

choose your exact interests, and click Add products.6. Repeat step 5 for each additional product.7. After choosing all your products, click the Subscribe to email link.8. For each product category, use the filters and choose which updates you want

to receive, and click Update.9. Repeat step 8 for each additional product category.

For more information about the types of fixes that are available, see the IBMSoftware Support Handbook at the following Web address:

http://techsupport.services.ibm.com/guides/handbook.html


http://www.ibm.com/software/support



http://techsupport.services.ibm.com/guides/handbook.html

Contacting IBM Software SupportIBM Software Support provides assistance with product defects. Before contactingIBM Software Support, the following criteria must be met:v Your company has an active IBM software maintenance contract.v You are authorized to submit problems to IBM Software Support.

The type of software maintenance contract that you need depends on the type ofproduct that you have. Product types are one of the following categories:v For IBM distributed software products (including, but not limited to, Tivoli,

Lotus®, and Rational® products, as well as DB2 and WebSphere products thatrun on Windows, Linux®, or UNIX operating systems), enroll in PassportAdvantage® in one of the following ways:

OnlineGo to the IBM Software Passport Advantage site at the following Webaddress and click How to Enroll:

http://www.lotus.com/services/passport.nsf/WebDocs/Passport_Advantage_Home

By phoneFor the phone number to call in your country, go to the IBM SoftwareSupport site at the following Web address and click the name of yourgeographic region:

http://techsupport.services.ibm.com/guides/contacts.htmlv For IBM eServer™ software products (including, but not limited to, DB2 and

WebSphere products that run in System z®, pSeries®, and iSeries® environments),you can purchase a software maintenance agreement by working directly withan IBM sales representative or an IBM Business Partner. For more informationabout support for eServer software products, go to the IBM eServer TechnicalSupport Advantage site at the following Web address:

http://www.ibm.com/servers/eserver/techsupport.html

If you are not sure what type of software maintenance contract you need, call1-800-IBMSERV (1-800-426-7378) in the United States or, from other countries, go tothe contacts page of the IBM Software Support Handbook at the following Webaddress and click the name of your geographic region for phone numbers ofpeople who provide support for your location:

http://techsupport.services.ibm.com/guides/contacts.html

To contact IBM Software support, follow these steps:1. “Determining the business impact”2. “Describing problems and gathering information” on page 463. “Submitting problems” on page 46

Determining the business impactWhen you report a problem to IBM, you are asked to supply a severity level.Therefore, you need to understand and assess the business impact of the problemthat you are reporting. Use the following severity criteria:

Appendix C. Support information 45




http://www.ibm.com/servers/eserver/techsupport.html


Severity 1The problem has a critical business impact. You are unable to use theprogram, resulting in a critical impact on operations. This conditionrequires an immediate solution.

Severity 2The problem has a significant business impact. The program is usable, butit is severely limited.

Severity 3The problem has some business impact. The program is usable, but lesssignificant features that are not critical are unavailable.

Severity 4The problem has minimal business impact. The problem causes little impacton operations, or a reasonable circumvention to the problem wasimplemented.

Describing problems and gathering informationWhen explaining a problem to IBM, be as specific as possible. Include all relevantbackground information so that IBM Software Support specialists can help yousolve the problem efficiently. To save time, know the answers to these questions:v What software versions were you running when the problem occurred?v Do you have logs, traces, and messages that are related to the problem

symptoms? IBM Software Support is likely to ask for this information.v Can you create the problem again? If so, what steps were performed to

encounter the problem?v Was any change made to the system? For example, were there changes to the

hardware, operating system, networking software, and so on.v Are you currently using a workaround for this problem? If so, please be

prepared to explain it when you report the problem.

Submitting problemsYou can submit your problem to IBM Software Support in one of two ways:

OnlineGo to the Submit and track problems page on the IBM Software Supportsite at the following address, and provide your information into theappropriate problem submission tool:


By phoneFor the phone number to call in your country, go to the contacts page ofthe IBM Software Support Handbook at the following Web address and clickthe name of your geographic region:


If the problem you submit is for a software defect or for missing or inaccuratedocumentation, IBM Software Support creates an Authorized Program AnalysisReport (APAR). The APAR describes the problem in detail. Whenever possible,IBM Software Support provides a workaround that you can implement until theAPAR is resolved and a fix is delivered. IBM publishes resolved APARs on theIBM product support Web pages daily, so that other users who experience thesame problem can benefit from the same resolution.




For more information about problem resolution, see “Searching knowledge bases”on page 43 and “Obtaining fixes” on page 43.

Appendix C. Support information 47


Appendix D. Notices

This information was developed for products and services offered in the U.S.A.IBM may not offer the products, services, or features discussed in this document inother countries. Consult your local IBM representative for information on theproducts and services currently available in your area. Any functionally equivalentproduct, program, or service that does not infringe any IBM intellectual propertyright may be used instead. Any reference to an IBM product, program, or service isnot intended to state or imply that only that IBM product, program, or service maybe used. However, it is the user responsibility to evaluate and verify the operationof any non-IBM product, program, or service.

IBM may have patents or pending patent applications covering subject matterdescribed in this document. The furnishing of this document does not give youany license to these patents. You can send license inquiries, in writing, to:

IBM Director of LicensingIBM CorporationNorth Castle DriveArmonk, NY 10504-1785 U.S.A.

For license inquiries regarding double-byte (DBCS) information, contact the IBMIntellectual Property Department in your country or send inquiries, in writing, to:

IBM World Trade Asia CorporationLicensing2-31 Roppongi 3-chome, Minato-kuTokyo 106, Japan

The following paragraph does not apply to the United Kingdom or any othercountry where such provisions are inconsistent with local law:

INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THISPUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHEREXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIEDWARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESSFOR A PARTICULAR PURPOSE.

Some states do not allow disclaimer of express or implied warranties in certaintransactions, therefore, this statement might not apply to you.

This information could include technical inaccuracies or typographical errors.Changes are periodically made to the information herein; these changes will beincorporated in new editions of the publication. IBM may make improvementsand/or changes in the product(s) and/or the program(s) described in thispublication at any time without notice.

Any references in this information to non-IBM Web sites are provided forconvenience only and do not in any manner serve as an endorsement of those Websites. The materials at those Web sites are not part of the materials for this IBMproduct and use of those Web sites is at your own risk.


IBM may use or distribute any of the information you supply in any way itbelieves appropriate without incurring any obligation to you.

Licensees of this program who wish to have information about it for the purposeof enabling: (i) the exchange of information between independently createdprograms and other programs (including this one) and (ii) the mutual use of theinformation which has been exchanged, should contact:

IBM Corporation2Z4A/10111400 Burnet RoadAustin, TX 78758 U.S.A.

Such information may be available, subject to appropriate terms and conditions,including in some cases payment of a fee.

The licensed program described in this document and all licensed materialavailable for it are provided by IBM under terms of the IBM Customer Agreement,IBM International Program License Agreement or any equivalent agreementbetween us.

Any performance data contained herein was determined in a controlledenvironment. Therefore, the results obtained in other operating environments mayvary significantly. Some measurements may have been made on development-levelsystems and there is no guarantee that these measurements will be the same ongenerally available systems. Furthermore, some measurement may have beenestimated through extrapolation. Actual results may vary. Users of this documentshould verify the applicable data for their specific environment.

Information concerning non-IBM products was obtained from the suppliers ofthose products, their published announcements, or other publicly available sources.IBM has not tested those products and cannot confirm the accuracy ofperformance, compatibility, or any other claims related to non-IBM products.Questions on the capabilities of non-IBM products should be addressed to thesuppliers of those products.

All statements regarding IBM's future direction or intent are subject to change orwithdrawal without notice, and represent goals and objectives only.

This information is for planning purposes only. The information herein is subject tochange before the products described become available.

This information contains examples of data and reports used in daily businessoperations. To illustrate them as completely as possible, the examples include thenames of individuals, companies, brands, and products. All of these names arefictitious and any similarity to the names and addresses used by an actual businessenterprise is entirely coincidental.

COPYRIGHT LICENSE:

This information contains sample application programs in source language, whichillustrate programming techniques on various operating platforms. You may copy,modify, and distribute these sample programs in any form without payment toIBM, for the purposes of developing, using, marketing or distributing applicationprograms conforming to the application programming interface for the operatingplatform for which the sample programs are written. These examples have not


been thoroughly tested under all conditions. IBM, therefore, cannot guarantee orimply reliability, serviceability, or function of these programs. You may copy,modify, and distribute these sample programs in any form without payment toIBM for the purposes of developing, using, marketing, or distributing applicationprograms conforming to IBM‘s application programming interfaces.

Each copy or any portion of these sample programs or any derivative work, mustinclude a copyright notice as follows:

© (your company name) (year). Portions of this code are derived from IBM Corp.Sample Programs. © Copyright IBM Corp. _enter the year or years_. All rightsreserved.

If you are viewing this information in softcopy form, the photographs and colorillustrations might not be displayed.

TrademarksIBM, the IBM logo, AIX®, DB2, IBMLink, Tivoli, Tivoli Enterprise Console®, andTME are trademarks or registered trademarks of International Business MachinesCorporation in the United States, other countries, or both.

Adobe, the Adobe logo, Acrobat, PostScript and all Adobe-based trademarks areeither registered trademarks or trademarks of Adobe Systems Incorporated in theUnited States, other countries, or both.

Cell Broadband Engine is a trademark of Sony Computer Entertainment, Inc., inthe United States, other countries, or both and is used under license therefrom.

Intel®, Intel logo, Intel Inside®, Intel Inside logo, Intel Centrino®, Intel Centrinologo, Celeron®, Intel Xeon®, Intel SpeedStep®, Itanium®, and Pentium® aretrademarks or registered trademarks of Intel Corporation or its subsidiaries in theUnited States and other countries.

IT Infrastructure Library® is a registered trademark of the Central Computer andTelecommunications Agency which is now part of the Office of GovernmentCommerce.

ITIL® is a registered trademark, and a registered community trademark of theOffice of Government Commerce, and is registered in the U.S. Patent andTrademark Office.

Java and all Java-based trademarks and logos are trademarks orregistered trademarks of Sun Microsystems, Inc. in the United States,other countries, or both.

Linux is a trademark of Linus Torvalds in the United States, other countries, orboth.

Microsoft, Windows, Windows NT®, and the Windows logo are trademarks ofMicrosoft Corporation in the United States, other countries, or both.

Appendix D. Notices 51

UNIX is a registered trademark of The Open Group in the United States and othercountries.

Other company, product, and service names may be trademarks or service marksof others.


Glossary

This glossary defines the technical terms andabbreviations that are used in Tivoli AccessManager. If you do not find the term orabbreviation for which you are looking, refer tothe IBM Terminology Web site at the followingWeb address:

http://www.ibm.com/ibm/terminology

The following cross-references are used amongterms:

Contrast withRefers the reader to a term that has anopposed or substantively differentmeaning.

See Refers the reader to a term that is theexpanded form of an abbreviation oracronym or to a synonym or morepreferred term.

See alsoRefers the reader to a related term.

ObsoleteIndicates that the term should not be usedand refers the reader to the preferredterm.

Aaccess control. In computer security, the process ofensuring that only authorized users can access theresources of a computer system in authorized ways.

access control list (ACL). In computer security, a listwith an object that identifies all the subjects that canaccess the object and their access rights. For example,an access control list is a list that is associated with afile that identifies the users who can access the file andidentifies the users' access rights to that file.

access decision information (ADI). The data andattributes that are used by the authorization engine toevaluate a rule. Authorization API attributes arename-value pairs, form the basis of all ADI that can bereferenced in a rule or presented to the authorizationengine.

access permission. The access privilege that applies tothe entire object.

account. Information about an identity.

ACL. See access control list.

ACL entry. Data in an access control list that specifiesa set of permissions.

ACL policy. Part of the security policy that containsACL entries that control who can access which domainresources and perform which actions. See alsoauthorization rule and protected object policy.

action. An access control list (ACL) permissionattribute. See also access control list.

action group. A set of actions that are explicitlyassociated with a resource or set of resources.

ADI. See access decision information.

ADK. See application development kit

administration service. An authorization API runtimeplug-in that can be used to perform administrationrequests on a Tivoli Access Manager resource managerapplication. The administration service responds toremote requests from the pdadmin command toperform tasks, such as listing the objects under aparticular node in the protected object tree. Customersmay develop these services using the authorizationADK.

application development kit (ADK). A set of tools,APIs, and documentation to assist with thedevelopment of software in a specific computerlanguage or for a particular operating environment.

attribute. A characteristic or trait of an entity thatdescribes the entity. An attribute can have a type,which indicates the range of information given by theattribute, and a value, which is within a range. In XML,for example, an attribute consists of a name-value pairwithin a tagged element and modifies a feature of anelement.

attribute list. A linked list that contains extendedinformation that is used to make authorizationdecisions. Attribute lists consist of a set of name-valuepairs.

audit event. A record of an operation in the audit logor change history; for example, an audit entry iscreated when a resource is modified.

audit level. The types of user actions that arecurrently being audited for the entire system or forspecific users on the system. Actions that can beaudited include authority failures and restoring objects.A record of each action is written to the audit journal.

audit trail. A chronological record of events thatenables the user to examine and reconstruct a sequence


http://www.ibm.com/software/globalization/terminology

of events. Audit trails are useful for managing securityand for recovering lost transactions.

audit trail file. The file that contains the audit trail.

authentication. In computer security, the process thatverifies identity. Authentication is distinct fromauthorization; authorization is concerned with grantingand denying access to resources. See also multi-factorauthentication, network-based authentication, andstep-up authentication.

authorization. In computer security, the process thatgrants or denies access to resources. Security uses atwo-step process: after authentication has verified theidentity, authorization allows the resource or processaccess to various resources based on its identity.

authorization API. The Tivoli Access Managercomponent that passes requests for authorizationdecisions from the resource manager to theauthorization evaluator. See also authorization serverand authorization service.

authorization evaluator. The decision-making processthat determines whether a client can access a protectedresource based on the security policy. The evaluatormakes its recommendation to the resource manager,which, in turn, responds accordingly.

authorization rule. Part of the security policy thatdefine conditions that are contained in authorizationpolicy. An authorization rule is used to make accessdecisions based on attributes such as user, application,and environment context. See also ACL policy andprotected object policy.

authorization server. The Tivoli Access Managercomponent that runs the authorization service. See alsoauthorization service.

authorization service. A dynamic or shared librarythat can be loaded by the authorization API runtimeclient at initialization time to perform operations thatextend a service interface in the Authorization API.

BBA. See basic authentication.

basic authentication. An authentication method thatverifies identity using a user name and password.

bind. To relate an identifier to another object in aprogram; for example, to relate an identifier to a value,to an address, or to another identifier or to associateformal parameters to actual parameters.

blade. A component that provides application-specificservices and components.

Boolean. A binary numbering system that is namedafter mathematician George Boole in which zero and

one are the only two values that can be returned; avalue of zero represents false while a value of onerepresents true.

business entitlement. The supplemental attribute of auser credential that describes the fine-grainedconditions that can be used in the authorizationprocess.

CCA. See certificate authority.

CDAS. Obsolete. See external authentication C API.

CDMF. See cross domain mapping framework.

certificate. In computer security, a digital documentthat binds a public key to the identity of the certificateowner, thereby enabling the certificate owner to beauthenticated. A certificate is issued by a certificateauthority.

certificate authority (CA). An organization that issuescertificates. A CA creates digital signatures andpublic-private key pairs. The CA guarantees theidentity of the individual who is granted the uniquecertificate and guarantees the services that the owner isauthorized to use, to issue new certificates, and torevoke certificates that belong to users andorganizations who are no longer authorized to use theservices. The role of the CA s to authenticate theentities (users and organizations) involved in electronictransactions. Because the CA guarantees that the twoparties that are exchanging information are really whothey claim to be, the CA is a critical component in datasecurity and electronic commerce.

CGI. See common gateway interface.

cipher. A cryptographic algorithm that is used toencrypt data that is unreadable until it is converted intoplain data (decrypted) with a predefined key.

common gateway interface (CGI). An Internetstandard for defining scripts that pass information froma Web server to an application program, through anHTTP request, and vice versa. A CGI script is a CGIprogram that is written in a scripting language, such asPerl.

configuration. The manner in which the hardwareand software of a system, subsystem, or network areorganized and interconnected.

connection. (1) In data communication, an associationestablished between functional units for conveyinginformation. (2) In TCP/IP, the path between twoprotocol applications that provides reliable data streamdelivery service. In the Internet, a connection extendsfrom a TCP application on one system to a TCPapplication on another system. (3) In system


communication, a line over which data can be passedbetween two systems or between a system and adevice.

console log agent. A log agent that writes events tostandard error or standard output. See also file logagent, pipe log agent, and remote log agent.

container object. A structural designation thatorganizes the object space into distinct functionalregions.

cookie. Information that a server stores on a clientmachine and accesses during subsequent sessions.Cookies allow servers to remember specific informationabout clients.

credentials. Detailed information, acquired duringauthentication, that describes the user, any groupassociations, and other security-related identityattributes. Credentials can be used to perform amultitude of services, such as authorization, auditing,and delegation.

credentials modification service. An authorizationAPI runtime plug-in which can be used to modify aTivoli Access Manager credential. Credentialsmodification services developed externally bycustomers are limited to performing operation to addand remove from the credentials attribute list and onlyto those attributes that are considered modifiable.

cross domain authentication service (CDAS).Obsolete. See external authentication C API.

cross domain mapping framework (CDMF). Aprogramming interface that allows a developer tocustomize the mapping of user identities and thehandling of user attributes when WebSEALe-Community SSO function are used.

Ddaemon. A system process that runs unattended toperform continuous or periodic system-wide functions,such as network control. See also service.

data store. A storage area for data, such as a databasesystem, directory, or file.

delegate. A user who is authorized to work foranother user. The authorization can be made by a useror by an administrator.

demilitarized zone (DMZ). In network security, acomputer or network that uses a firewall to be isolatedfrom, and to serve as a neutral zone between, a trustednetwork (for example, a private intranet) and anuntrusted network (for example, the Internet). One ormore secure gateways usually control access to theDMZ from the trusted or the untrusted network.

digital signature. Information that is encrypted with aprivate key and is appended to a message to assure therecipient of the authenticity and integrity of themessage. The digital signature proves that the messagewas signed by the entity that owns, or has access to,the private key or shared secret symmetric key.

directory schema. The valid attribute types and objectclasses that can appear in a directory. The attributetypes and object classes define the syntax of theattribute values, which attributes are required, andwhich attributes are optional.

distinguished name (DN). (1) The name that uniquelyidentifies an entry in a directory. A distinguished nameis made up of an attribute-value pairs, separated bycommas. (2) A set of name-value pairs (such ascn=common name and c=country) that uniquelyidentifies an entry in a digital certificate.

DMZ. See demilitarized zone.

DN. See distinguished name.

domain. (1) A logical grouping of resources in anetwork that share common administration andmanagement. (2) A part of a network that isadministered with a common protocol. See also domainname.

domain administrator. The administrator for adomain who can assign any of the roles in that domainto subdomains. After assigning roles to subdomains,administrators in that subdomain can assignsubdomain users these roles.

domain name. In the Internet suite of protocols, thename of a host system. A domain name consists of asequence of subnames that are separated by a delimitercharacter. For example, if austin.ibm.com is the fullyqualified domain name (FQDN) of a host system, bothaustin.ibm.com and ibm.com® are domain names.

dynamic group. A group that is defined using asearch expression. When an attribute is added to adirectory entry that causes it to match the searchexpression, the entry automatically becomes a memberof the group.

EEAS. See external authorization service.

encryption. In computer security, the process oftransforming data into a cipher.

entitlement. A data structure that containsexternalized security policy information. Entitlementscontain policy data or capabilities that are formatted ina way that is understandable to a specific application.

entitlement service. An authorization API runtimeplug-in which can be used to return entitlements from

Glossary 55

an external source for a principal or set of conditions.Entitlements are normally application specific data thatwill be consumed by the resource manager applicationin some way or added to the principal's credentials foruse further on in the authorization process. Customersmay develop these services using the authorizationADK.

entity. In object-oriented design, an item that can betreated as a unit and, often, as a member of a particularcategory or type. An entity can be concrete or abstract.

event. Any significant change in the state of a systemresource, network resource, or network application. Anevent can be generated for a problem, for the resolutionto a problem, or for the successful completion of a task.

event pool. A set of events recognized by an activity.Each activity has its own event pool. The event pool isinitialized when the activity is created and is deletedwhen the activity is deleted.

extended attribute. Additional information that thesystem or a program associates with an object. Anextended attribute can be any format, such as text, abitmap, or binary data.

external authentication C API. A C API that enablesyou to write custom authentication modules thatreplace or extend the functionality of the built–inauthentication process. The identity information isreturned through the authentication module interface.Contrast with external authentication HTTP interface.

external authentication HTTP interface. An interfacethat enables you to extend the functionality of thebuilt-in authentication process to allow a remote serviceto handle the authentication process. The identityinformation in the HTTP response headers is used togenerate user credentials. Contrast with externalauthentication C API.

external authorization service (EAS). Anauthorization API runtime plug-in that can be used tomake application- or environment-specific authorizationdecisions as part of the authorization decision chain.Customers can develop these services using theauthorization ADK.

Extensible Markup Language (XML). A standardmeta-language for defining markup languages that isbased on Standard Generalized Markup Language(SGML).

Extensible Stylesheet Language (XSL). A language forspecifying style sheets for XML documents. XSLTransformation (XSLT) is used with XSL to describehow an XML document is transformed into anotherdocument. See also Extensible Stylesheet LanguageTransformation.

Extensible Stylesheet Language Transformation(XSLT). An XML processing language that is used toconvert an XML document into another document inXML, PDF, HTML, or other format. See also ExtensibleStylesheet Language.

Ffile log agent. A log agent that writes events to a file.See also console log agent, pipe log agent, and remotelog agent.

file transfer protocol (FTP). In the Internet suite ofprotocols, a protocol that can use Transmission ControlProtocol (TCP) and Telnet services to transfer filesbetween machines.

FTP. See file transfer protocol

Gglobal sign-on (GSO). A flexible single sign-onsolution that enables the user to provide alternativeuser names and passwords to the back-end Webapplication server. Through a single login, globalsign-on grants users access to the computing resourcesthey are authorized to use. Designed for largeenterprises consisting of multiple systems andapplications within heterogeneous, distributedcomputing environments, GSO eliminates the need forusers to manage multiple user names and passwords.See also single sign-on.

group. A named list of users by which access levels tocorporate directories, databases, and servers areassigned. Two or more individual users who arecategorized for assigning database security settings; forexample, administrators must assign individuals togroups before assigning roles.

GSO. See global sign-on.

Hhost. A computer that is connected to a network andprovides an access point to that network. The host canbe a client, a server, or both a client and a serversimultaneously.

HTTP. See hypertext transfer protocol.

hypertext transfer protocol (HTTP). In the Internetsuite of protocols, the protocol that is used to transferand display documents.

Iinheritance. An object-oriented programmingtechnique that allows the use of existing classes as abasis for creating other classes.


Internet protocol (IP). In the Internet suite ofprotocols, a connectionless protocol that routes datathrough a network or interconnected networks. IP actsas an intermediary between the higher protocol layersand the physical network.

Internet suite of protocols. A set of protocolsdeveloped for use on the Internet and publishedthrough the Internet Engineering Task Force (IETF).

interprocess communication (IPC). (1) The process bywhich programs communicate data to each other andsynchronize their activities. Semaphores, signals, andinternal message queues are common methods ofinterprocess communication. (2) A mechanism of anoperating system that allows processes to communicatewith each other within the same computer or over anetwork.

IP. See Internet protocol.

IPC. See interprocess communication.

Jjunction. A logical connection that is created toestablish a path from one server to another.

KKDC. See key distribution center.

Kerberos. An authentication system that enables twoparties to exchange private information over anotherwise open network. It works by assigning aunique key, called a ticket, to each user that logs on tothe network. The ticket is then embedded in messagesthat are sent over the network. The receiver of amessage uses the ticket to authenticate the sender.

Kerberos ticket. A transparent application mechanismthat transmits the identity of an initiating principal toits target. A simple ticket contains the identity, a sessionkey, a timestamp, and other information that is sealedusing a secret key.

key. In computer security, a sequence of symbols thatis used with a cryptographic algorithm for encryptingor decrypting data. See private key and public key.

key database file (KDC). See key file.

key distribution center. In the Kerberos protocol, thecentral server, which includes the authentication serverand the ticket-granting server. The KDC is sometimesreferred to as the Kerberos server.

key file. In computer security, a file that containspublic keys, private keys, trusted roots, and certificates.

key pair. In computer security, a public key and aprivate key. When the key pair is used for encryption,

the sender uses the public key to encrypt the message,and the recipient uses the private key to decrypt themessage. When the key pair is used for signing, thesigner uses the private key to encrypt a representationof the message, and the recipient uses the public key todecrypt the representation of the message for signatureverification. Because the private key holds more of theencryption pattern than the public key, the key pair iscalled asymmetric.

key ring. See key file.

keystore file. A key file that contains both public keysstored as signer certificates and private keys stored inpersonal certificates.

keytab file. See key table.

key table. In the Kerberos protocol, a file that containsservice principal names and secret keys. The secret keysshould be known only to the services that use the keytable file and the key distribution center (KDC).

key-value pair. Information that is expressed as apaired set.

LLDAP. See lightweight directory access protocol.

leaf node. A node that has no children before it in thedirectory tree.

lightweight directory access protocol (LDAP). Anopen protocol that uses TCP/IP to provide access todirectories that support an X.500 model and that doesnot incur the resource requirements of the morecomplex X.500 Directory Access Protocol (DAP). Forexample, LDAP can be used to locate people,organizations, and other resources in an Internet orintranet directory.

lightweight third party authentication (LTPA). Anauthentication protocol that users cryptography tosupport security across a set of Web servers in adistributed environment.

LTPA. See lightweight third party authentication.

Mmanagement domain. The default domain in whichTivoli Access Manager enforces security policies forauthentication, authorization, and access control. Thisdomain is created when the policy server is configured.See also domain.

management interface. The interface that a domainadministrator can use to manage security policy. InTivoli Access Manager, an administrator can use WebPortal Manager or the pdadmin commands to applysecurity policy to resources.

Glossary 57

management server. Obsolete. See policy server.

master server. In a network environment, the serverthat has permissions to run commands on all othermachines in the environment. The master server isdesigned to manage the network, clients, and resourceobjects in the network database. Contrast with replicaserver

metadata. Data that describes the characteristics ofstored data.

migration. The installation of a new version or releaseof a program to replace an earlier version or release.

MPA. See multiplexing proxy agent.

multi-factor authentication. A protected object policy(POP) that forces a user to authenticate using two ormore levels of authentication. For example, the accesscontrol on a protected resource can require that theusers authenticate with both user name/password anduser name/token passcode.

multiple tenancy server. A server that permits thehosting of multiple customers on a single server insteadof multiple client machines. See also protected objectpolicy.

multiplexing proxy agent (MPA). A gateway thataccommodates multiple client access. These gatewaysare sometimes known as Wireless Access Protocol(WAP) gateways when clients access a secure domainusing a WAP. Gateways establish a single authenticatedchannel to the originating server and tunnel all clientrequests and responses through this channel.

Nnamespace. (1) In XML, a uniform resource identifier(URI) that provides a unique name to associate with allthe elements and type definitions in a schema. (2)Space reserved by a file system to contain the names ofits objects.

network-based authentication. A protected objectpolicy (POP) that controls access to objects based on theInternet protocol (IP) address of the user. See alsoprotected object policy.

notification thread. The synchronization mechanismthat the policy server uses to inform all databasereplicas of a change to the master policy database.

Oobject. (1) In object-oriented design or programming,a concrete realization (instance) of a class that consistsof data and the operations associated with that data.An object contains the instance data that is defined bythe class, but the class owns the operations that areassociated with the data. (2) Any digital content that a

user can manipulate as a single unit and perform atask. An object can appear as text, an icon, or both. (3)A named storage space that consists of a set ofcharacteristics that describe the space and, in somecases, data. An object is anything that occupies space instorage, can be located in a library or directory, can besecured, and on which defined operations can beperformed. Some examples of objects are programs,files, libraries, and stream files.

object space. A virtual representation of the resourcesto be protected. See also namespace.

object type. A categorization or group of objectinstances that share similar behavior and characteristics.

PPAC. See privilege attribute certificate.

PDCA. See Policy Director Certificate Authority

permission. The ability to access a protected object,such as a file or directory. The number and meaning ofpermissions for an object are defined by the accesscontrol list (ACL). See also access control list.

pipe log agent. A log agent that writes events asstandard input to another program. See also console logagent, file log agent, and remote log agent.

policy. A set of rules that are applied to managedresources.

policy database. The database that contains thesecurity policy information for all resources in thedomain. Each domain has its own policy database.

Policy Director Certificate Authority (PDCA). Atrusted certificate that is created during theconfiguration of the policy server and that is used tosign all other Tivoli Access Manager certificates. APDCA certificate is stored in the master policydatabase.

policy enforcer. A component of a resource managerthat directs requests to the authorization service forprocessing after authorization is granted. Traditionalapplications bundle the policy enforcer and theresource manager as one process.

policy server. The Tivoli Access Manager componentthat maintains the master policy database, replicatesthis policy information throughout the secure domain,and updates database replicas whenever a change ismade to the master policy database. The policy serveralso maintains location information about other TivoliAccess Manager and non-Tivoli Access Managerresource managers that are operating in the securedomain.


polling. The process by which databases areinterrogated at regular intervals to determine if dataneeds to be transmitted.

POP. See protected object policy.

portal. A single point of access to diverse informationand applications. Users can customize and personalizea portal.

principal. (1) An entity that can communicate securelywith another entity. (2) An authenticated user. Aprincipal is identified by its associated security context,which defines its access rights.

private key. In computer security, a key that is knownonly to its owner. Contrast with public key.

privilege attribute certificate (PAC). A digitaldocument that contains a principal's authentication andauthorization attributes and a principal's capabilities.

privilege attribute certificate service. Anauthorization API runtime client plug-in whichtranslates a PAC of a predetermined format in to aTivoli Access Manager credential, and vice-versa. Theseservices could also be used to package or marshall aTivoli Access Manager credential for transmission toother members of the secure domain. Customers maydevelop these services using the authorization ADK.See also privilege attribute certificate.

protected object. The logical representation of anactual system resource that is used for applying ACLsand POPs and for authorizing user access. See alsoprotected object policy and protected object space.

protected object policy (POP). A type of securitypolicy that imposes additional conditions on theoperation permitted by the ACL policy to access aprotected object. It is the responsibility of the resourcemanager to enforce the POP conditions. See also ACLpolicy, authorization rule, protected object, andprotected object space.

protected object space. The virtual objectrepresentation of actual system resources that is usedfor applying ACLs and POPs and for authorizing useraccess. See also protected object and protected objectpolicy.

proxy server. A server that receives requests intendedfor another server and that acts on behalf of a client toobtain the requested service. A proxy server is oftenused when the client and the server are incompatiblefor direct connection. For example, a client cannot meetthe security authentication requirements of the serverbut should be permitted some services.

public key. In computer security, a key that is madeavailable to everyone. Contrast with private key.

Qquality of protection. The level of data security,determined by a combination of authentication,integrity, and privacy conditions.

Rrecord. (1) The storage representation of a single rowof a table or other data in a database. (2) A group ofrelated data, words, or fields treated as a unit.

registry. The datastore that contains access andconfiguration information for users, systems, andsoftware.

remote cache mode. An operational mode in which aresource manager uses the functions that are providedby the authorization API to communicate to the remoteauthorization server.

remote log agent. A log agent that sends events to aremote server for recording. See also console log agent,file log agent, and pipe log agent.

replica server. A server that contains a copy of thedirectory or directories of another server. Replicas backup master servers or other replica servers to enhanceperformance or response times and to ensure dataintegrity. Contrast with master server.

resource. A hardware, software, or data entity that ismanaged.

resource group. A group of resources that can includebusiness objects such as contracts or a set of relatedcommands. In access control policies, resource groupsspecify the resource to which the policy authorizesaccess.

resource manager. (1) An application, program, ortransaction that manages and controls access to sharedresources, such as memory buffers and data sets. (2)Any server or application that uses the authorizationAPI to process client requests for access to resources.

resource object. The representation of an actualnetwork resource, such as a service, file, and program.

response file. An ASCII file that can be customizedwith the setup and configuration data that automatesan installation. The setup and configuration data has tobe entered during an interactive installation, but withthe response file, the installation can proceed withoutuser interaction. See also silent installation.

role. A definition of the access permissions that a useror process has and the specific resources that the useror process can modify at those levels. Users andprocesses are limited in how they can access resourceswhen that user or process does not have theappropriate role.

Glossary 59

role activation. The process of applying accesspermissions to a role.

role assignment. The process of assigning a role to auser, such that the user has the appropriate accesspermissions for the object defined for that role.

root container object. The top-level container object inthe hierarchy or resource objects.

root domain. Name servers that have authoritativecontrol of all the top-level domains.

routing file. An ASCII file that contains commandsthat control the configuration of messages.

routing table. A collection of path informationthrough which hosts or networks can communicatewith each other.

RSA. A public-key encryption technology that wasdeveloped by RSA Data Security, Inc., and used byGSKit. The acronym stands for Rivest, Shamir, andAdleman, the inventors of this encryption technique.

RSA encryption. A system for public-keycryptography used for encryption and authentication.The security of the system depends on the difficulty offactoring the product of two large prime numbers.

rule. A set of logical statements that enable a server torecognize relationships among events and to performautomated responses accordingly.

rules evaluator. The component responsible forevaluating an authorization rule.

run time. The time period during which a computerprogram is running.

runtime environment. A subset of an applicationdevelopment kit (ADK) that contains the executablefiles and other supporting files that comprise theoperational environment of the platform.

Sscalability. The ability of hardware, software, or adistributed system to maintain performance levels as itincreases in size and increases in the number of userswho access resources.

schema. The set of statements, expressed in a datadefinition language, that completely describes thestructure of data that is stored in a database, directory,or file.

Secure Sockets Layer (SSL). A security protocol thatprovides communication privacy. SSL enablesclient/server applications to communicate in a way thatis designed to prevent eavesdropping, tampering, andmessage forgery.

security context. The digitally signed token thatidentifies a principal, lists the roles and access rightsfor the principal, and contains information about whenthe token expires.

security management. The software discipline thataddresses how an organization can control access tomission critical applications and data.

security policy. (1) A written document that definesthe security controls that you institute for yourcomputer systems. A security policy describes the risksthat you intend to minimize and the actions thatshould be taken if someone breaches your securitycontrols. (2) In Tivoli Access Manager, the combinationof ACL policies, authorization rules, and protectedobject policies attached to objects to make themprotected objects. See also ACL policy, authorizationrule, and protected object policy.

self-registration. The process by which a user canenter required data and become a registered userwithout the involvement of an administrator.

service. Work performed by a server. A service can bea simple request for data to be sent or stored (as withfile servers, HTTP servers, or e-mail servers), or it canbe for more complex requests (as with print servers orprocess servers). See also daemon.

session. A series of requests to a server or applicationthat originate from the same user at the same browser.

silent installation. An installation that does not sendmessages to the console but instead stores messagesand errors in log files. Also, a silent installation can useresponse files for data input. See also response file.

single sign-on (SSO). The mechanism that allows auser to logon once and access multiple applicationsthrough a single authorization challenge. Using SSO, auser does not need to log on to each applicationseparately. See also global sign-on.

SSL. See Secure Socket Layer.

SSO. See single sign-on.

stanza. A group of lines in an ASCII file that togetherhave a common function or define a part of a system.Stanzas are usually separated by blank lines or colons,and each stanza has a name.

stash file. The local copy of the master key file thatresides in an encrypted format on the local disk.

step-up authentication. A protected object policy(POP) that relies on a preconfigured hierarchy ofauthentication levels and enforces a specific level ofauthentication according to the policy set on a resource.The step-up authentication POP does not force the userto authenticate using multiple levels of authenticationto access any given resource, but it requires the user to


authenticate at a level at least as high as that requiredby the policy protecting a resource. See also protectedobject policy.

suffix. A distinguished name that identifies the topentry in a locally held directory hierarchy. Because ofthe relative naming scheme used in LightweightDirectory Access Protocol (LDAP), this suffix applies toevery other entry within that directory hierarchy. Adirectory server can have multiple suffixes, eachidentifying a locally held directory hierarchy.

Tticket. See Kerberos ticket.

token. A sequence of bits (symbol of authority) that ispassed successively along a transmission medium fromone device to another to indicate the device that istemporarily in control of the transmission medium.Each device can acquire and use the token to controlthe medium.

trusted root. In the Secure Sockets Layer (SSL), thepublic key and associated distinguished name of acertificate authority (CA). See also Secure Socket Layer.

Uuniform resource identifier (URI). The characterstring used to identify an abstract or physical resourceon the Internet. A URI typically describes how to accessthe resource, the computer that contains the resource,and the name of the resource. The most common formof URI is the Web page address, which is a particularsubset or URI called uniform resource locator (URL).See also uniform resource locator.

uniform resource locator (URL). A character stringthat represent resources on a computer or in a network,such as the Internet. The URL includes the abbreviatedname of the protocol used to access the informationresource and the information used by the protocol tolocate the resource.

URI. See uniform resource identifier.

URL. See uniform resource locator.

user. Any person, organization, process, device,program, protocol, or system that uses a serviceprovided by others.

user registry. See registry.

Vvirtual hosting. The capability of a Web server thatallows it to appear as more than one host to theInternet.

WWeb Portal Manager (WPM). A Web-based graphicalapplication used to manage Tivoli Access Managersecurity policy in a secure domain. An alternative tothe pdadmin command line interface, this GUI enablesremote administrator access and enables administratorsto create delegated user domains and assign delegateadministrators to these domains.

Web resource. Any one of the resources that arecreated during the development of a Web application;for example, Web projects, HTML pages, JSP files,servlets, custom tag libraries, and archive files.

WebSEAL. A high performance, multi-threaded Webserver that applies a security policy to a protectedobject space. WebSEAL can provide single sign-onsolutions and incorporate back-end Web applicationserver resources into its security policy.

Web session. See session.

WPM. See Web Portal Manager.

XXML. See Extensible Markup Language.

XML transform. A standard that uses XSL stylesheetsto transform XML documents into other XMLdocuments or fragments or to transform XMLdocuments into HTML documents.

XSL. See Extensible Stylesheet Language.

XSL stylesheet. Code that describes how an XMLdocument should be rendered (displayed or printed).

XSLT. See Extensible Stylesheet LanguageTransformation.

Glossary 61


Index

Aaccessibility ixadding development systems 4application server

configuring 23applications

deploying 4, 6authorization

non-Java 2 29authorization API

installing 2authorization server 2azn_entitlements_get_entitlements() function 30

Bbooks

see publications v, viiibuilding applications 4

Cclasses

PDAttrs 11PDAttrValue 12PDAttrValueList 12PDAttrValues 13PDAuthorizationContext 8PDLoginModule 8PDPermission 9PDPrincipal 9PDStatics 13SvrSslCfg 33

com.tivoli.pd.jcfg.SvrSslCfg 33common problems

reportingdescribing problem 46determining business impact 45gathering information 46

submitting problems 46configuring

application server 23configuring into secure domain 22conventions

typeface xcredentials 17

retrieve without authenticating 18customer support

contacting 45obtaining fixes 43receiving updates from 44registering with 44searching information centers 43searching knowledge bases 43searching the Internet 43submitting problems 46

Ddefining 18deploying an application 6deprecated classes and methods 2, 41

com.tivoli.mts.SvrSslCfg 33development systems, adding 4directory names, notation xi

Eeducation

see Tivoli technical training ixentitlements 30entitlements service plug-in 30environment variables, notation xi

Ffile 18files, installation directories 2fixes, obtaining 43

Iinformation centers, searching 43installation 2installation directories 2installation requirements 4Internet, searching 43

JJAAS 17

configuration 27JAAS login file

configuring 27specify file location 27

JAAS model 17JAAS policy 18jaas.policy 18Java 2 permission model 17Java 2 security 16Java application 22Java classes 2java.security 18

Kknowledge bases

information centers 43searching 43the Internet 43

Llocal mode

configuring 24LoginModule 17


LoginModule (JAAS) 17

Mmanuals

see publications v, viii

NNameCallback 17notation

environment variables xipath names xitypeface xi

Oobtaining 17online publications

accessing viiiordering publications ix

PPasswordCallback 17path names, notation xiPDAttrs class 11PDAttrValue class 12PDAttrValueList class 12PDAttrValues class 13PDAuthorizationContext class 8PDLoginModule 19PDLoginModule class 8PDPermission 18PDPermission class 9PDPrincipal class 9PDPrincipal.getEntitlements 30PDStatics class 13protected objects entitlements service 30publications v

accessing online viiiordering ix

Rregistry, user 4remote mode

configuring 23requirements, for installation 4resource manager

sample code 28

Ssecure domain 4service plug-ins 30signed JAR files 5software requirements 4software updates, receiving 44SSL 2support

See customer supportSvrSslCfg 22

addsvr 37

SvrSslCfg (continued)chgsvr 37config 36configuring application server 23replcert 38rmsvr 37setcertref 39setdbdir 38setdblisten 38setdbref 38setport 38syntax 33unconfig 37

SvrSslCfg class 33adding a policy or authorization server 24changing a policy or authorization server 25configuring a server in local mode 24configuring a server in remote mode 23removing a policy or authorization server 24replacing a certificate 25setting the application listening mode 25setting the database directory 25setting the database refresh interval 25setting the port 25unconfiguring an application server 24

TTivoli Access Manager Runtime for Java component

configuring 5Tivoli Information Center viiiTivoli technical training ixTivoli user groups ixtraining, Tivoli technical ixtroubleshooting 6typeface conventions x

Uuser authentication 17user groups, Tivoli ixuser registry 4

Vvariables, notation for xi


��

Printed in USA

SC23-6516-01

Documents

Authorization Java Classes Developer Reference - IBM€¦ · Chapter 1. Introduction to ... the users and objects associated with the Tivoli Access Manager for e ... Authorization