ts-doc: ts-636 - help, my nt server's too slow - sas

IBM Tivoli Access Manager

Authorization Java ClassesDeveloper’s ReferenceVersion 3.9

GC23-4688-00

Note:Before using this information and the product it supports, read the information in Appendix B, “Notices” on page 25.

First Edition (April 2002)

This edition applies to version 3.9 of IBM Tivoli Access Manager (product number 5724-C08) and to all subsequentreleases and modifications until otherwise indicated in new editions.

© Copyright International Business Machines Corporation 2002. All rights reserved.US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contractwith IBM Corp.

Contents

Figures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . v

Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . vii

Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ixWho should read this reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ixWhat this reference contains . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ixPublications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . x

IBM Tivoli Access Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xRelated publications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiiAccessing publications online . . . . . . . . . . . . . . . . . . . . . . . . . . . . xivOrdering publications. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xivProviding feedback about publications . . . . . . . . . . . . . . . . . . . . . . . . . xv

Accessibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvContacting customer support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvConventions used in this reference . . . . . . . . . . . . . . . . . . . . . . . . . . . xv

Typeface conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xv

Chapter 1. Introducing the authorization API . . . . . . . . . . . . . . . . . . . . 1Authorization API components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1Building Java applications with the authorization API . . . . . . . . . . . . . . . . . . . . . 2

IBM Tivoli Access Manager software requirements. . . . . . . . . . . . . . . . . . . . . . 2JRE requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3Configuring the Java runtime component to a particular Java runtime environment . . . . . . . . . . 3Security requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

Deploying a Java authorization API application. . . . . . . . . . . . . . . . . . . . . . . . 4Gathering problem determination information . . . . . . . . . . . . . . . . . . . . . . . . 4

Enabling tracing on the policy server . . . . . . . . . . . . . . . . . . . . . . . . . . 4Enabling tracing on the authorization server . . . . . . . . . . . . . . . . . . . . . . . . 4Enabling tracing in the Java runtime component . . . . . . . . . . . . . . . . . . . . . . 4Gathering trace and message logs . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

Chapter 2. Understanding security in IBM Tivoli Access Manager . . . . . . . . . . . 7Using Java 2 security with IBM Tivoli Access Manager . . . . . . . . . . . . . . . . . . . . . 7Java Authentication and Authorization Service (JAAS) model . . . . . . . . . . . . . . . . . . . 8

Authenticating users and obtaining credentials . . . . . . . . . . . . . . . . . . . . . . . 8Authorizing access requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

Configuring a Java application into the secure domain . . . . . . . . . . . . . . . . . . . . . 10Information needed for establishing SSL communications . . . . . . . . . . . . . . . . . . . 10SvrSslCfg usage syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11Using the SvrSslCfg class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

Chapter 3. Configuring the authorization API . . . . . . . . . . . . . . . . . . . 13Configuring the Java Authentication and Authorization Service . . . . . . . . . . . . . . . . . . 13

Creating a login configuration file . . . . . . . . . . . . . . . . . . . . . . . . . . . 13Specify the login file location . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

Developing a resource manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14Making authorization decisions outside of Java 2 . . . . . . . . . . . . . . . . . . . . . . . 14Obtaining entitlements for a specified user . . . . . . . . . . . . . . . . . . . . . . . . . 15

Chapter 4. Java classes overview . . . . . . . . . . . . . . . . . . . . . . . . 17com.tivoli.mts.PDLoginModule . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17com.tivoli.mts.PDPrincipal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17com.tivoli.mts.PDPermission. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

© Copyright IBM Corp. 2002 iii

com.tivoli.mts.PDAttrs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18com.tivoli.mts.PDAttrValue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19com.tivoli.mts.PDAttrValues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19com.tivoli.mts.PDStatics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19com.tivoli.mts.SvrSslCfg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

Chapter 5. Upgrade considerations . . . . . . . . . . . . . . . . . . . . . . . 21

Appendix A. Deprecated Java classes and methods . . . . . . . . . . . . . . . . 23

Appendix B. Notices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25Trademarks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

iv IBM Tivoli Access Manager: Authorization Java Classes Developer’s Reference

Figures

1. JAAS login configuration file. . . . . . . . . . . . . . . . . . . . . . . . . . . . 132. Resource manager task example. . . . . . . . . . . . . . . . . . . . . . . . . . . 143. Example showing authorization outside of Java 2 . . . . . . . . . . . . . . . . . . . . . 154. Using the PDPrincipal.getEntitlements method. . . . . . . . . . . . . . . . . . . . . . 165. Processing protected objects returned . . . . . . . . . . . . . . . . . . . . . . . . . 16

© Copyright IBM Corp. 2002 v

vi IBM Tivoli Access Manager: Authorization Java Classes Developer’s Reference

Tables

1. Files associated with the Access Manager Java runtime and ADK components . . . . . . . . . . . 22. Sample information used for SvrSslCfg examples . . . . . . . . . . . . . . . . . . . . . 113. Arguments for main() method of SvrSslCfg class . . . . . . . . . . . . . . . . . . . . . 20

© Copyright IBM Corp. 2002 vii

viii IBM Tivoli Access Manager: Authorization Java Classes Developer’s Reference

Preface

IBM® Tivoli® Access Manager (Access Manager) is the base software that isrequired to run applications in the IBM Tivoli Access Manager product suite. Itenables the integration of IBM Tivoli Access Manager applications that provide awide range of authorization and management solutions. Sold as an integratedsolution, these products provide an access control management solution thatcentralizes network and application security policy for e-business applications.

Note: IBM Tivoli Access Manager is the new name of the previously releasedsoftware entitled Tivoli SecureWay® Policy Director. Also, for users familiarwith the Tivoli SecureWay Policy Director software and documentation, themanagement server is now referred to as the policy server.

This reference contains information about how to use Access Managerauthorization Java™ classes and methods. This document describes the Javaimplementation of the Access Manager authorization API. See the IBM Tivoli AccessManager Authorization C API Developer’s Reference for information regarding the Cimplementation of these APIs.

Who should read this referenceThis reference is for application programmers implementing programs in the Javaprogramming language that require the use of the authorization functionsprovided with the IBM Tivoli Access Manager product.

Readers should be familiar with the following:v PC 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 Access Manager is configured to usev Lightweight Directory Access Protocol (LDAP) and directory services, if used by

your user registryv Authentication and authorizationv Secure Sockets Layer (SSL) communications

What this reference containsThis reference contains the following chapters and appendixes:v Chapter 1, “Introducing the authorization API” on page 1

This chapter provides an overview of the authorization API and its components.v Chapter 2, “Understanding security in IBM Tivoli Access Manager” on page 7

This chapter provides an overview of the Java classes and methods.v Chapter 3, “Configuring the authorization API” on page 13

This chapter provides information on configuring the authorization API.v Chapter 4, “Java classes overview” on page 17

© Copyright IBM Corp. 2002 ix

This chapter provides an overview of the Java classes and methods provided asart of the authorization API.

v Chapter 5, “Upgrade considerations” on page 21This chapter outlines considerations for upgrading Java applications from aprevious version of Tivoli SecureWay® Policy Director.

v Appendix A, “Deprecated Java classes and methods” on page 23This appendix provides a list of the Java classes and methods that have beendeprecated in this version of Access Manager.

v Appendix B, “Notices” on page 25This appendix provides copyright, legal, and trademark information.

PublicationsThis section lists publications in the Access Manager library and any other relateddocuments. It also describes how to access Tivoli publications online, how to orderTivoli publications, and how to make comments on Tivoli publications.

IBM Tivoli Access ManagerThe Access Manager library is organized into the following categories:v “Release information”v “Base information”v “WebSEAL information” on page xiv “Web security information” on page xiv “Developer references” on page xiiv “Technical supplements” on page xii

Publications in the product library are included in Portable Document Format(PDF) on the product CD. To access these publications using a Web browser, openthe infocenter.html file located in the /doc directory on the product CD.

For additional sources of information about Access Manager and related topics, seethe following Web sites:

http://www.ibm.com/redbookshttps://www.tivoli.com/secure/support/documents/fieldguides

Release informationv IBM Tivoli Access Manager for e-business Read Me First

GI11-0918 (am39_readme.pdf)Provides information for installing and getting started using Access Manager.

v IBM Tivoli Access Manager for e-business Release NotesGI11-0919 (am39_relnotes.pdf)Provides late-breaking information, such as software limitations, workarounds,and documentation updates.

Base informationv IBM Tivoli Access Manager Base Installation Guide

GC32-0844<(am39_install.pdf)Explains how to install, configure, and upgrade Access Manager software,including the Web portal manager interface.

x IBM Tivoli Access Manager: Authorization Java Classes Developer’s Reference

http://www.ibm.com/redbooks

https://www.tivoli.com/secure/support/documents/fieldguides/

v IBM Tivoli Access Manager Base Administrator’s GuideGC23-4684 (am39_admin.pdf)Describes the concepts and procedures for using Access Manager services.Provides instructions for performing tasks from the Web portal managerinterface and by using the pdadmin command.

v IBM Tivoli Access Manager Base for Linux on zSeries Installation GuideGC23-4796 (am39_zinstall.pdf)Explains how to install and configure Access Manager Base for Linux on thezSeries™ platform.

WebSEAL informationv IBM Tivoli Access Manager WebSEAL Installation Guide

GC32-0848<(amweb39_install.pdf)Provides installation, configuration, and removal instructions for the WebSEALserver and the WebSEAL application development kit.

v IBM Tivoli Access Manager WebSEAL Administrator’s GuideGC23-4682 (amweb39_admin.pdf)Provides background material, administrative procedures, and technicalreference information for using WebSEAL to manage the resources of yoursecure Web domain.

v IBM Tivoli Access Manager WebSEAL Developer’s ReferenceGC23-4683 (amweb39_devref.pdf)Provides administration and programming information for the Cross-domainAuthentication Service (CDAS), the Cross-domain Mapping Framework (CDMF),and the Password Strength Module.

v IBM Tivoli Access Manager WebSEAL for Linux on zSeries Installation GuideGC23-4797 (amweb39_zinstall.pdf)Provides installation, configuration, and removal instructions for WebSEALserver and the WebSEAL application development kit for Linux on the zSeriesplatform

Web security informationv IBM Tivoli Access Manager for WebSphere Application Server User’s Guide

GC32-0850 (amwas39_user.pdf)Provides installation, removal, and administration instructions for AccessManager for IBM WebSphere® Application Server.

v IBM Tivoli Access Manager for WebLogic Server User’s GuideGC32-0851 (amwls39_user.pdf)Provides installation, removal, and administration instructions for AccessManager for BEA WebLogic Server.

v IBM Tivoli Access Manager Plug-in for Edge Server User’s GuideGC23-4685 (amedge39_user.pdf)Describes how to install, configure, and administer the plug-in for IBMWebSphere Edge Server application.

v IBM Tivoli Access Manager Plug-in for Web Servers User’s GuideGC23-4686 (amws39_user.pdf)Provides installation instructions, administration procedures, and technicalreference information for securing your Web domain using the plug-in for Webservers.

Preface xi

Developer referencesv IBM Tivoli Access Manager Authorization C API Developer’s Reference

GC32-0849 (am39_authC_devref.pdf)Provides reference material that describes how to use the Access Managerauthorization C API and the Access Manager service plug-in interface to addAccess Manager security to applications.

v IBM Tivoli Access Manager Authorization Java Classes Developer’s ReferenceGC23-4688 (am39_authJ_devref.pdf)Provides reference information for using the Java™ language implementation ofthe authorization API to enable an application to use Access Manager security.

v IBM Tivoli Access Manager Administration C API Developer’s ReferenceGC32-0843 (am39_adminC_devref.pdf)Provides reference information about using the administration API to enable anapplication to perform Access Manager administration tasks. This documentdescribes the C implementation of the administration API.

v IBM Tivoli Access Manager Administration Java Classes Developer’s ReferenceSC32-0842 (am39_adminJ_devref.pdf)Provides reference information for using the Java language implementation ofthe administration API to enable an application to perform Access Manageradministration tasks.

v IBM Tivoli Access Manager WebSEAL Developer’s ReferenceGC23-4683 (amweb39_devref.pdf)Provides administration and programming information for the Cross-domainAuthentication Service (CDAS), the Cross-domain Mapping Framework (CDMF),and the Password Strength Module.

Technical supplementsv IBM Tivoli Access Manager Performance Tuning Guide

GC43-0846 (am39_perftune.pdf)Provides performance tuning information for an environment consisting ofAccess Manager with IBM SecureWay Directory defined as the user registry.

v IBM Tivoli Access Manager Capacity Planning GuideGC32-0847 (am39_capplan.pdf)Assists planners in determining the number of WebSEAL, user registry, andbackend Web servers needed to achieve a required workload.

v IBM Tivoli Access Manager Error Message ReferenceSC32-0845 (am39_error_ref.pdf)Provides explanations and recommended actions for the messages produced byAccess Manager.

The Tivoli Glossary includes definitions for many of the technical terms related toTivoli software. The Tivoli Glossary is available, in English only, at the followingWeb site:

http://www.tivoli.com/support/documents/glossary/termsm03.htm

Related publicationsThis section lists publications related to the Access Manager library.

xii IBM Tivoli Access Manager: Authorization Java Classes Developer’s Reference

http://www.tivoli.com/support/documents/glossary/termsm03.htm

IBM DB2® Universal Database™

IBM DB2 Universal Database is required when installing IBM SecureWay Directory,z/OS™, and OS/390® SecureWay LDAP servers. DB2 information is available atthe following Web site:

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

IBM Global Security ToolkitAccess Manager provides data encryption through the use of the IBM GlobalSecurity Toolkit (GSKit). GSKit is shipped on the IBM Tivoli Access Manager BaseCD for your particular platform.

The GSKit package installs the iKeyman key management utility, gsk5ikm, whichenables you to create key databases, public-private key paris, and certificaterequests. The following document is available in the /doc/GSkit directory on theIBM Tivoli Access Manager Base CD for your particular platform:v Secure Sockets Layer Introduction and iKeyman User’s Guide

(gskikm5c.pdf)Provides information for network or system security administrators who plan toenable SSL communication in their Access Manager secure domain.

IBM SecureWay DirectoryIBM SecureWay Directory, Version 3.2.2, is shipped on the IBM Tivoli AccessManager Base CD for your particular platform. If you plan to install the IBMSecureWay Directory server as your user registry, the following documents areavailable in the /doc/Directory path on the IBM Tivoli Access Manager Base CDfor your particular platform:v IBM SecureWay Directory Installation and Configuration Guide, SC32-0845

(aparent.pdf, lparent.pdf, sparent.pdf, wparent.pdf)Provides installation, configuration, and migration information for IBMSecureWay Directory components on AIX®, Linux, Solaris OperatingEnvironment, and Microsoft® Windows® operating systems.

v IBM SecureWay Directory Release Notes(relnote.pdf)Supplements IBM SecureWay Directory, Version 3.2.2, product documentationand describes features and functions made available to you in this release.

v IBM SecureWay Directory Readme Addendum(addendum322.pdf)Provides information about changes and fixes that occurred after the IBMSecureWay Directory documentation had been translated. This book is providedin English only.

v IBM SecureWay Directory Server Readme(server.pdf)Provides a description of the IBM SecureWay Directory Server, Version 3.2.2.

v IBM SecureWay Directory Client Readme(client.pdf)Provides a description of the IBM SecureWay Directory Client SDK, Version3.2.2. This software development kit (SDK) provides LDAP applicationdevelopment support.

v IBM SecureWay Directory Configuration Schema(scparent.pdf)

Preface xiii

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

Describes the directory information tree (DIT) and the attributes that are used toconfigure the slapd32.conf file. In IBM SecureWay Directory Version 3.2, thedirectory settings are stored using the LDAP Directory Interchange Format(LDIF) format in the slapd32.conf file.

v IBM SecureWay Directory Tuning Guide(tuning.pdf)Provides performance tuning information for IBM SecureWay Directory. Tuningconsiderations for directory sizes ranging from a few thousand entries tomillions of entries are given where applicable.

For more information about IBM SecureWay Directory, see the following Web site:

http://www.ibm.com/software/network/directory/library/

IBM WebSphere Application ServerIBM WebSphere Application Server, Advanced Single Server Edition 4.0.2, isinstalled with the Web portal manager interface. For information about IBMWebSphere Application Server, see the following Web site:

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

Accessing publications onlinePublications in the product libraries are included in Portable Document Format(PDF) on the product CD. To access these publications using a Web browser, openthe infocenter.html file, which is located in the /doc directory on the product CD.

When IBM publishes an updated version of one or more online or hardcopypublications, they are posted to the Tivoli Information Center. The TivoliInformation Center contains the most recent version of the publications in theproduct library in PDF or HTML format, or both. Translated documents are alsoavailable for some products.

You can access the Tivoli Information Center and other sources of technicalinformation from the following Web site:

http://www.tivoli.com/support/documents/

Information is organized by product, including release notes, installation guides,user’s guides, administrator’s guides, and developer’s references.

Note: If you print PDF documents on other than letter-sized paper, select the Fit topage check box in the Adobe Acrobat Print dialog (which is available whenyou click File → Print) to ensure that the full dimensions of a letter-sizedpage are printed on the paper that you are using.

Ordering publicationsYou can order many Tivoli publications online at the following Web site:

http://www.elink.ibmlink.ibm.com/public/applications/publications/cgibin/pbi.cgi

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

xiv IBM Tivoli Access Manager: Authorization Java Classes Developer’s Reference

http://www.ibm.com/software/network/directory/library/

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

http://www.tivoli.com/support/documents/



v In other countries, for a list of telephone numbers, see the following Web site:http://www.tivoli.com/inside/store/lit_order.html

Providing feedback about publicationsWe are very interested in hearing about your experience with Tivoli products anddocumentation, and we welcome your suggestions for improvements. If you havecomments or suggestions about our products and documentation, contact us in oneof the following ways:v Send an e-mail to [email protected] Complete our customer feedback survey at the following Web site:

http://www.tivoli.com/support/survey/

AccessibilityAccessibility features help a user who has 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 also canuse the keyboard instead of the mouse to operate all features of the graphical userinterface.

Contacting customer supportIf you have a problem with any Tivoli product, you can contact Tivoli CustomerSupport. See the Tivoli Customer Support Handbook at the following Web site:

http://www.tivoli.com/support/handbook/

The handbook provides information about how to contact Tivoli CustomerSupport, depending on the severity of your problem, and the followinginformation:v Registration and eligibilityv Telephone numbers and e-mail addresses, depending on the country in which

you are locatedv What information to gather before contacting support

Conventions used in this referenceThis reference uses several conventions for special terms and actions and operatingsystem-dependent commands and paths.

Typeface conventionsThe following typeface conventions are used in this reference:

Bold Command names and options, keywords, names of Java classesand objects, and other information that you must use literallyappear in bold.

Italic Variables, command options, and values you must provide appearin italics. Titles of publications and special words or phrases thatare emphasized also appear in italics.

Monospace Code examples, command lines, screen output, file and directorynames, and system messages appear in monospace font.

Preface xv

http://www.tivoli.com/inside/store/lit_order.html

http://www.tivoli.com/support/survey/

http://www.tivoli.com/support/handbook/

Brackets ([ ]) Information enclosed in brackets ([ ]) is optional. Anything notenclosed in brackets must be specified.

Braces ({ }) Braces ({ }) identify a set of mutually exclusive options, withexactly one option required.

Vertical Bar (|)Mutually exclusive options are separated by a vertical bar (|).

... Additional parameters of the same type can be specified here.

xvi IBM Tivoli Access Manager: Authorization Java Classes Developer’s Reference

Chapter 1. Introducing the authorization API

The IBM Tivoli Access Manager (Access Manager) Java runtime componentincludes the Java language version of a subset of the Access Manager authorizationAPI. The authorization API consists of a set of classes and methods that provideJava applications with the ability to interact with Access Manager to makeauthentication and authorization decisions.

Application developers can use the Javadoc information provided with the AccessManager application developer kit (ADK) along with this book and other Javareference materials, to add Access Manager authorization and security services tonew or existing Java applications.

Note: If you are familiar with the authorization API Java classes provided inprevious versions of Tivoli SecureWay Policy Director, see Chapter 5,“Upgrade considerations” on page 21 for important information.

This chapter contains the following topics:v “Authorization API components”v “Building Java applications with the authorization API” on page 2v “Deploying a Java authorization API application” on page 4v “Gathering problem determination information” on page 4

Authorization API componentsThe authorization API Java classes are installed as part of the Access Manager Javaruntime component. These classes communicate directly with the Access Managerauthorization server by establishing an authenticated, Secure Sockets Layer (SSL)session with the authorization server process. The authorization server servicesthese requests in the same manner that it services requests from the authorizationC API.

Table 1 on page 2 lists the files related to the authorization API that are installed aspart of the Access Manager Java runtime component. The Javadoc information,even though it is installed as part of the Access Manager ADK component, is listedin the table for completeness.

© Copyright IBM Corp. 2002 1

Table 1. Files associated with the Access Manager Java runtime and ADK components

Directory File File Description

JAVA_HOME/lib/ext PD.jar The Java Archive (JAR) file containingthe classes and methods associatedwith both the authorization API andthe administration API.

ibmjsse.jar The JAR file encapsulating the JavaSecure Socket Extension (JSSE) supportwhich provides a Java implementationof SSL.

ibmjcefw.jaribmjceprovider.jarlocal_policy.jarUS_export_policy.jar

The JAR files comprising part of theJava Cryptography Extension (JCE).

ibmpkcs.jar The JAR file containing the Public KeyCryptography Standard (PKCS)support.

jaas.jar The JAR file encapsulating the JavaAuthentication and AuthorizationService (JAAS).

AM_BASE/nls/javadocs/pdjrte

index.html

(and many others)

Javadoc HTML documentation for theJava classes and methods providedwith the Access Manager Java runtimecomponent.

Note: The PD.jar file replaces the PDPerm.jar file that was provided in previousversions of Tivoli SecureWay Policy Director.

To make the JAR files listed in Table 1 available to a particular JRE, see“Configuring the Java runtime component to a particular Java runtimeenvironment” on page 3.

Building Java applications with the authorization APITo develop Java applications that use the Access Manager authorization API, youmust install and configure the required software.

IBM Tivoli Access Manager software requirementsYou must install and configure an Access Manager secure domain. If you do nothave an Access Manager secure domain installed, install one before beginningapplication development. The minimum installation consists of a single systemwith the following Access Manager components installed:v Access Manager runtime environment (see Note 1 on page 3)v Access Manager Java runtime componentv Access Manager policy serverv Access Manager authorization serverv Access Manager ADK

If you already have an Access Manager secure domain installed and want to add adevelopment system to the domain, the minimum Access Manager installationconsists of the following components:v Access Manager runtime environment (see Note 1 on page 3)

2 IBM Tivoli Access Manager: Authorization Java Classes Developer’s Reference

v Access Manager Java runtime componentv Access Manager ADK

For Access Manager installation instructions, refer to the section of the IBM TivoliAccess Manager Base Installation Guide for your operating system platform.

Notes:

1. The Access Manager runtime environment component is not needed fordeveloping or deploying an Access Manager Java application. The prerequisitechecking for the Access Manager ADK component is in error and erroneouslyrequires that the Access Manager runtime component be installed, even if youare developing only Java applications and simply need the Javadoc informationand the example files from the ADK component.To save disk space, you can copy the Javadoc HTML information, consisting ofthe entire AM_BASE/nls/javadocs directory tree, to another location on yourdevelopment system and then uninstall the Access Manager ADK and runtimecomponents. Only the Access Manager Java runtime component is necessary forrunning Java applications.

2. If you intend to use the Access Manager runtime environment for anadministration C API application, you also must install the IBM® SecureWay®

Directory client if an LDAP or Lotus Domino server is being used as the userregistry in the secure domain.

JRE requirementsOn those operating system platforms that support the Access Managerauthorization API Java classes and methods, the base installation CD contains anoptionally installable JRE. You also can choose to use any of the supported JREslisted in the IBM Tivoli Access Manager Base Installation Guide for developing anddeploying your Access Manager Java applications. After you have installed asuitable JRE, configure it for use with Access Manager as outlined in the nextsection, “Configuring the Java runtime component to a particular Java runtimeenvironment”.

Configuring the Java runtime component to a particular Javaruntime environment

Configure the Access Manager Java runtime component to use the proper JRE onthe system by using the pdjrtecfg command. The pdjrtecfg command copies theAccess Manager JAR files to the JAVA_HOME/lib/ext directory of the JRE,automatically making the Access Manager classes and methods available. TheCLASSPATH in your environment does not need to be modified. The AccessManager Java runtime component can be configured to several different JREs onthe same system, if desired. See the IBM Tivoli Access Manager Base InstallationGuide for details.

Security requirementsThe PD.jar file is signed, but verification of the signing of JAR files is notsupported in this version of Access Manager.

The SvrSslCfg Java class (com.tivoli.mts.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 10 for details on using the SvrSslCfgutility.

Chapter 1. Introducing the authorization API 3

Note: The svrsslcfg command 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.

Deploying a Java authorization API applicationOnce you have developed and tested your Java application that uses the AccessManager authorization API, you can deploy the application to systems that areconfigured as part of an Access Manager secure domain. The Access Manager Javaruntime component is the only Access Manager component that must be installedon a system to run an Access Manager Java application. The Access Managerruntime component is not needed for running Java applications.

Note: Information on installing the Access Manager Java runtime component canbe found in the IBM Tivoli Access Manager Base Installation Guide.

Gathering problem determination informationWhen developing a Java application, you might encounter a problem with AccessManager. To assist Tivoli support personnel in diagnosing your problem, gatherproblem determination information relating to your error.

Access Manager components can be configured to log information to one or moretrace files. You can enable tracing for the policy server, the authorization server, theJava runtime component, or any system using the Access Manager runtimeenvironment.

Enabling tracing on the policy serverTo enable tracing on the policy server, edit the /etc/routing file, located in theinstallation directory for the Access Manager policy server, and uncomment the lastline.

Shut down and restart the policy server daemon, pdmgrd.

Enabling tracing on the authorization serverTo enable tracing on the authorization server, edit the /etc/routing file, located inthe installation directory for the Access Manager authorization server, anduncomment the last line.

Shut down and restart the authorization server daemon, pdacld.

Enabling tracing in the Java runtime componentTracing for the Access Manager Java runtime component is controlled by settingsin the JAVA_HOME/PolicyDirector/PDJLog.properties file. To enable tracing, editthe properties file and update the following line to set isLogging to true:baseGroup.PDJTraceLogger.isLogging=true

Gathering trace and message logsTrace and message log files for the policy server, authorization server, and AccessManager runtime environment are written to the /log directory in the AccessManager installation directory. To determine the names of the trace log files, youneed to determine the process identifier, or PID, of the Access Manager process.


Determine the PID for the policy or authorization server by checking theappropriate file:

Policy servercat ivmgrd.pid

Authorization servercat ivacld.pid

After determining the PID, look in the AM_BASE/log directory for trace files withnames of the form: PID.trace.log.*. Also collect the following message files in thesame directory::notice*.logfatal*.logwarning*.logerror*.log

Trace and message log files associated with the Access Manager Java runtimecomponent are written to files in the /log directory with the following names:PDJTrace.log.*PDJFatal.log.*PDJWarning.log.*PDJError.log.*

Chapter 1. Introducing the authorization API 5

Chapter 2. Understanding security in IBM Tivoli AccessManager

The IBM Tivoli Access Manager (Access Manager) authorization Java classesprovide an implementation of Java security code that is fully compliant with theJava 2 security model and the Java Authentication and Authorization Service(JAAS).

The Access Manager authorization Java classes are described in the followingsections:v “Using Java 2 security with IBM Tivoli Access Manager” on page 7v “Java Authentication and Authorization Service (JAAS) model” on page 8

Using Java 2 security with IBM 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 Access Manager authorization server provides an SSL-based access mode forhandling remote authorization calls. The Access Manager Java authorization APIuses this socket-based capability to provide functionality equivalent to thatprovided in the authorization C API by the azn_decision_access_allowed() andazn_decision_access_allowed_ext() functions.

The azn_decision_access_allowed() function requires the following information: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.

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


Note: The Access Manager authorization API Java classes only support use of theremote cache mode for accessing the Access Manager authorizationdatabase. Local cache mode is not supported.

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 to add 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’s 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 Access Manager authorization Java Classesuse the JAAS model:v “Authenticating users and obtaining credentials” on page 8v “Authorizing access requests” on page 9

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

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

Access Manager provides one JAAS LoginModule. You can use the module in twodifferent ways. You can use it to authenticate a user and obtain the user’scredentials. Alternatively, you can use it just to obtain the user’s credentials.

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

The LoginModule authenticates the principal and returns the Access Managercredential. The LoginModule expects the calling application to provide thefollowing information:v The username, through a javax.security.auth.callback.NameCallback

v The password, through a javax.security.auth.callback.PasswordCallback.


http://java.sun.com/products/jaas

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

Retrieving credentials without authenticatingTo retrieve credentials without authenticating, the calling application can call theJAAS Login Module with only a principal name as a short name or a X500Name(DN).

The LoginModule will expect the calling application to provide the usernamethrough a javax.security.auth.callback.NameCallback.

Using the login configuration fileYou can use an entry in the login configuration file to specify which of two loginmodes your application uses. You can configure the module to either require botha user name and a password, or just a user name.

This configuration takes the form of an optional keyword, nameOnly=true.

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

Authorizing access requestsThe Access Manager authorization Java Classes are built around JAAS and the Java2 security model. The Access Manager API closely follows the Java 2 permissionmodel.

Note: For more information on the Java 2 security model, see:http://java.sun.com/j2se/1.3/docs/guide/security/index.html

The Access Manager authorization API Java classes provide a new permission classnamed PDPermission. This class extends the abstract class com.ibm.IBMPermission,which extends the abstract class java.security.Permission. PDPermission has astatic initializer that establishes the SSL-protected socket communications protocolwhich is used to talk to Access Manager.

An entry needs to be made in the Java 2 policy file to insure that the Java 2security code calls the implies() method in the PDPermission class describedbelow. This entry could be made specific to particular codebases, as desired.grant signedBy “xxx” codeBase “file:/E:/Program Files/aaa/bbb/ccc”principal com.tivoli.mts.PDPrincipal “*” {permission com.ibm.mts.PdPermission “ignoreme”;};

The contents of the action string ignoreme above are unimportant because thePDPermission class ignores them. This is because Access Manager acts as therepository for security policy. The intent of this entry is to get the Java securitycode to call the implies() method when some resource manager checks to see if apermission is held.

The PDPermission class implements two constructors plus the following methods:

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

equals()Determines if two PDPermission objects are equal.

Chapter 2. Understanding security in IBM Tivoli Access Manager 9

http://java.sun.com/j2se/1.3/docs/guide/security/index.html

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.mts.PDPrincipal, then theappropriate credentials are secured for the call to Access Manager.

The example below illustrates one way a resource manager, such as a Web serveror Enterprise Java Beans container, would place the Subject on the current threadof 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 Access Manager.

Following is an example of a typical authorization check that invokes the AccessManager through the PDPermission class implementation. The checkPermission()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);

Configuring a Java application into the secure domainAccess Manager uses a self-generated and self-signed certificate to authenticate itsSecure Sockets Layer (SSL) communications. The Access Manager authorizationAPI Java classes must be able to determine the certificate that Access Manager isusing in order to establish its SSL communication. You also must establish anidentity for the Java application. These are accomplished by creating aconfiguration file, a keystore file, and an Access Manager application name usingthe SvrSslCfg (com.tivoli.mts.SvrSslCfg) class.

Information needed for establishing SSL communicationsTo create the files necessary for establishing SSL communications in the securedomain, the SvrSslCfg class needs information about the secure domain as well asinformation related to the application.

The following information about the Access Manager secure domain is needed:

Security master passwordThe password associated with the Access Manager sec_master user.

Policy server nameThe name of the system running the Access Manager policy server,ivmgrd.


Authorization server nameThe name of the system running the Access Manager authorization server,ivacld. This might be the same system as the policy server.

Policy server SSL port numberThe number of the port being used for SSL communications with thepolicy server. The default is 7135.

Authorization server SSL port numberThe number of the port being used for SSL communications with theauthorization server. The default is 7136.

To uniquely associate this SSL connection to the Java application being run, thefollowing information is needed also:

Configuration file URLThe URL to the configuration file to be manipulated by the SvrSslCfgclass. If not specified, the JAVA_HOME/PdPerm.properties file is used.

Keystore file URLThe URL to the keystore file to be manipulated by the SvrSslCfg class. Ifnot specified, the JAVA_HOME/lib/security/pdperm.ks file is used.

Access Manager application nameThe name of the Access Manager application name to be created andassociated with the SSL connection between this system and the AccessManager servers.

The configuration and keystore files are sensitive files that should be protected.The contents of the configuration file is not externalized and is subject to changewithout notice in future releases of Access Manager. Do not use the information inthe configuration file directly.

Note: If either of these files becomes damaged, the configuration steps must berepeated. Creating backups of these two files is recommended.

SvrSslCfg usage syntaxThe use of the SvrSslCfg class can be summarized as follows:java com.tivoli.mts.SvrSslCfg name sec_master_pwd ivmgrd_name ivacld_name \

ivmgrd_port ivacld_port config_URL keystore_URL option

Additional information on the SvrSslCfg class can be found in“com.tivoli.mts.SvrSslCfg” on page 20 or in the Javadoc information in the AccessManager ADK component.

The examples in this chapter use the information shown in Table 2.

Table 2. Sample information used for SvrSslCfg examples

Information Value

sec_master password secpw

Policy server amps.myco.com

Authorization server amas.myco.com

Policy server port number 7135 (the default)

Authorization server port number 7136 (the default)

Configuration file c:\am\configfile

Chapter 2. Understanding security in IBM Tivoli Access Manager 11

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

Information Value

Keystore file c:\am\keystore

Access Manager application name PDPermissionjapp

The application name must be unique. Otherinstances of the application running on thisor other systems must each be given aunique name. A distinguished name can beused if an LDAP-based user registry is beingused by Access Manager.

Host name of Java application system jsys.myco.com

Using the SvrSslCfg classAfter obtaining the necessary information, you use the SvrSslCfg class to createthe Access Manager application name, the configuration file, and the keystore file.

Based on the sample information shown in Table 2 on page 11, the command toestablish an SSL connection between japp.myco.com and the Access Manager securedomain might be as follows:java com.tivoli.mts.SvrSslCfg PdPermissionjapp \

secpw amps.myco.com amas.myco.com "" "" \file:///c:/am/configfile file:///c:/am/keystore create

The create option is used to initially create the configuration and keystore files. Ifthe create option is used and the configuration or keystore files already exist, anexception is thrown.

Compatibility Note: In previous versions of Tivoli SecureWay Policy Director, theSvrSslCfg class did not allow the specification of theconfiguration and keystore files and required that the accountfor the application be created on the policy server prior toinvoking the class. The old syntax for using the SvrSslCfgclass is maintained for backward compatibility.

The certificate in the keystore expires based on the certificate lifetime set on thepolicy server. After the certificate expires, the replace option must be used togenerate a new certificate. The replace option also can be used to invalidate anexisting certificate, which is useful should a certificate become compromised.java com.tivoli.mts.SvrSslCfg PdPermissionjapp \

secpw amps.myco.com amas.myco.com "" "" \file:///c:/am/configfile file:///c:/am/keystore replace

The unconfig option deletes the keystore file and deletes information for thisapplication from the configuration file but does not delete the configuration file.java com.tivoli.mts.SvrSslCfg PdPermissionjapp \

secpw amps.myco.com amas.myco.com "" "" \"" "" unconfig


Chapter 3. Configuring the authorization API

After establishing SSL communications within the IBM Tivoli Access Manager(Access Manager) secure domain, you can configure and customize the wayauthentication and authorization decisions are made.

This chapter covers the following topics:v “Configuring the Java Authentication and Authorization Service”v “Developing a resource manager” on page 14v “Making authorization decisions outside of Java 2” on page 14

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

This section does not provide an overview of all of the JAAS configuration options.Tto 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 13v “Specify the login file location” on page 14

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

Note that the last stanza allows applications that use pd-nopass in theirLoginContext constructor to simply supply usernames but not passwords. Formore information, see the Javadoc information for com.tivoli.mts.PDLoginModule.

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

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

};

pd {com.tivoli.mts.PDLoginModule required;

};

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

Figure 1. JAAS login configuration file


http://java.sun.com/products/jaas

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/j131ibm/jre/lib/security/config.pd

v Specify the appropriate -D options on the java command line invocation. Formore information, see the JAAS configuration documentation.

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

Making authorization decisions outside of Java 2The Access Manager authorization API Java classes also support a completelyJava-compliant usage of the Access Manager authorization check that is outside ofthe Java 2 and JAAS framework.

The PDPrincipal class has one constructor that takes a name and password andauthenticates to Access Manager as part of the construction of the object. ThePDPrincipal class also has a constructor that simply takes a name.

// 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.doAs(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());

}

Figure 2. Resource manager task example


A security check is performed on the current environment when one is using theno-password version of the constructor. The permission that must be held is:permission javax.security.auth.AuthPermission “createPDPrincipal”

If authorized, the constructor retrieves the authentication information from AccessManager for that entity. The names that are supported on these constructors caneither be Access Manager short names, or distinguished names.

After you have constructed a PDPrincipal object for the specified entity, constructa PDPermission 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 thespecified access to the specified object is allowed by the specified entity.

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

Obtaining entitlements for a specified userThe authorization API supports a service plug-in model that enables developers toadd modules that extend the capabilities of Access Manager. The entitlementsservice plug-in is the only type of plug-in that is callable from a Java application atthis time.

An entitlements service plug-in enables domain-specific authorization APIapplications to retrieve the entitlements for a user from a domain-specific policyrepository. An entitlements service allows a third-party application running in thesecure domain to call a specific entitlements service based on its service ID. If noservice ID is provided, the default entitlements service plug-in is called. Anentitlements service plug-in, like other authorization service plug-ins, must beinstalled and configured before use.

Access Manager provides a default entitlement service called the Access Managerprotected objects entitlements service that is specific to the Access Managerenvironment. This entitlements service plug-in accepts a single, multi-valued stringattribute that specifies one or more root nodes for searching the Access Managerprotected object space along with an indicator of what access permissions arerequired. The plug-in returns a multi-valued attribute list of protected objectsmeeting 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 4 onpage 16 shows a call to the protected objects entitlements service requesting a list

PDPrincipal whoIsIt = new PDPrincipal(“tom”, “letmein”.toCharArray());PDPermission whatTheyWant = new PDPermission(“/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

Chapter 3. Configuring the authorization API 15

of objects in the /AppData/AccountData and /AppData/EmployeeData object trees towhich the principal has view and modify permission.

The protected objects entitlements service returns a multi-valued attribute listconsisting of byte arrays or Strings representing the protected objects to which theprincipal has the desired access permission. The sample code in Figure 5demonstrates printing the results.

Additional information on the entitlements service plug-in as well as the othertypes of authorization service plug-ins can be found in the IBM Tivoli AccessManager Authorization C API Developer’s Reference.

PDAttrs attrsIn = new PDAttrs();PDAttrs attrsOut = new PDAttrs();

// 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.getEntitlements(PDStatics.AZN_ENT_SVC_PD_POBJ,attrsIn);

// Is user entitled to anything?

PDAttrValues results = attrsOut.get(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

// Process results of getEntitlements

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

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

java.util.Iterator iter = results.iterator();

while (iter.hasNext()) {Object value = ((PDAttrValue)iter.next()).getValue();

System.out.println(value.toString());}

Figure 5. Processing protected objects returned


Chapter 4. Java classes overview

This chapter discusses the IBM Tivoli Access Manager (Access Manager)authorization API Java classes:v “com.tivoli.mts.PDLoginModule” on page 17v “com.tivoli.mts.PDPrincipal” on page 17v “com.tivoli.mts.PDPermission” on page 18v “com.tivoli.mts.PDAttrs” on page 18v “com.tivoli.mts.PDAttrValue” on page 19v “com.tivoli.mts.PDAttrValues” on page 19v “com.tivoli.mts.PDStatics” on page 19v “com.tivoli.mts.SvrSslCfg” on page 20

See the Javadoc information in the Access Manager ADK for detailed informationabout all of these classes and their associated methods.

com.tivoli.mts.PDLoginModuleThis class knows how to authenticate to Access Manager using a user name andpassword. This class expects to be run inside the JAAS framework.public class PDLoginModule implements

javax.security.auth.spi.LoginModule{

public PDLoginModule()public login()public logout()public abort()public commit()public initialize(javax.security.auth.Subject subject,

javax.security.auth.callback.CallbackHandlercallbackHandler,

java.util.Map sharedState,java.util.Map options)

}

com.tivoli.mts.PDPrincipalThis class represents the identity of an Access Manager user.public class PDPrincipal implements java.security.Principal,

com.ibm.security.auth.PrincipalComparator,java.io.Serializable {

public PDPrincipal()public PDPrincipal(String name)public PDPrincipal(String name, char[] password)public PDPrincipal(String name, char[] password, URL configURL)public PDPrincipal(String name, URL configURL)public PDPrincipal(URL configURL)public PDPrincipal addGroupMemberships(String service ID,

String[] groups)public boolean equals(Object o)public PDAttrs getEntitlements(String serviceID, PDAttrs attrsIn)public String getName()public int hashCode()


public String toString()public boolean implies(javax.security.auth.Subject subject)public boolean implies(PDPermission perm)public boolean implies(PDPermission perm,

PDAttrs attrsIn,PDAttrs attrsOut)

}

com.tivoli.mts.PDPermissionThis class knows how to check Access Manager for specified actions. Resourcemanagers and applications can create a subclass or use PDPermission directly toget a Permission class. The Permission class is passed to Access Manager as part ofajava.security.SecurityManager.checkPermission(perm) method invocation.public class PDPermission {

public PDPermission(java.lang.String rname,java.lang.String actions)

public boolean implies(java.security.Permission p)public boolean implies(PDPrincipal princ)public boolean implies(PDPrincipal princ,

PDAttrs inputList,PDAttrs, outputList)

public boolean equals(Object obj)public String getActions()public int hashCode()}

com.tivoli.mts.PDAttrsThis class represents an attribute list. Attribute lists are data types used by theAccess Manager C API. Each attribute consists of entries that have a name and oneor more values. The names are Strings, and the values can be either Strings or bytearrays.public class PDAttrs extends java.lang.Objectimplements java.lang.Cloneable, java.io.Serializable {

public PDAttrs()public PDAttrs(int initialCapacity)public PDAttrs(PDattrs int initialCapacity, float loadFactor)public PDAttrs(PDattrs that)public add(java.lang.String name, PDAttrValues vals)public java.util.Collection add(java.lang.String name,

java.lang.String value)public java.util.Collection add(java.lang.String name,

byte[] value)public void addAll(PDAttrs attrs)public void clear()public boolean delete(java.lang.String key)public java.lang.Object clone()public java.util.Set entrySet()public boolean equals(java.lang.Object obj)public PDAttrValues get(java.lang.String key)public int getQop()public int hashCode()public java.util.Set keySet()public void setQop(int qop)public int size()public java.lang.String toString()

}


com.tivoli.mts.PDAttrValueThis class represents the value of an Access Manager attribute. A value may beeither a String or a byte arraypublic class PDAttrValue extends java.lang.Object

implements java.lang.Cloneable, java.io.Serializable{

public PDAttrValue(byte[] bytes)public PDAttrValue(java.lang.String string)public boolean equals(java.lang.Object obj)public java.lang.Object getValue()public int hashcode()public java.lang.Object clone()public java.lang.String toString()

}

com.tivoli.mts.PDAttrValuesThis class represents a collection of values for a particular PDAttr. Thisimplementation is a Set, so duplicates are not allowed in a particular PDAttrValuesobject.public class PDAttrValues extends java.util.HashSet

implements java.lang.Cloneable, java.io.Serializable{

public PDAttrValues()public PDAttrValues(int initialCapacity)public PDAttrValues(int initialCapacity,

float loadFactor)public PDAttrValues(java.util.Collection c)

public boolean add(PDAttrValue value)public boolean add(java.lang.Object obj)public boolean addAll(java.util.Collection c)public java.lang.Object clone()public boolean equals(java.lang.Object obj)public int hashCode()public java.lang.String toString()

}

com.tivoli.mts.PDStaticsThis is a class for various constants used in the PDPermission class and otherassociated classes.public class PDStatics extends java.lang.Object {

public static final java.lang.String AZN_MOD_SVC_RAD_2ABpublic static final java.lang.String

AZN_MOD_RAD_GROUP_NAMESpublic static final java.lang.String AZN_ENT_SVC_PD_POBJpublic static final java.lang.String

AZN_ENT_SVC_PD_POBJ_PATHpublic static final java.lang.String

AZN_ENT_SVC_PD_POBJ_REQD_OPSpublic static final java.lang.String

AZN_ENT_SVC_PD_POBJ_MATCHESpublic static final int QOP_NONEpublic static final int QOP_INTEGRITYpublic static final int QOP_PRIVACY

Chapter 4. Java classes overview 19

public static final int AZN_VALTYPE_BUFFERpublic static final int AZN_VALTYPE_UTF8STRING

}

com.tivoli.mts.SvrSslCfgThis class configures SSL communication with remote Access Manager servers.public class SvrSslCfg extends java.lang.Object {

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

The values for the nine argv parameters are shown in Table 3. The parameters arepositional. Use a null string to accept the default for a given parameter.

Table 3. Arguments for main() method of SvrSslCfg class

argv Value

Name Name of the Access Manager application tocreate and associate with the SSLcommunication.

sec_master password Password for the sec_master user.

Policy server name Name of the system where the AccessManager policy server, ivmgrd, is running.

Authorization server name Name of the system where the AccessManager authorization server, ivacld, isrunning. This could be the same system asthe policy server.

Policy server port number The number of the port used for SSLcommunications with the policy server.Default is 7135.

Authorization server port number The number of the port used for SSLcommunications with the authorizationserver. Default is 7136.

URL of the configuration file URL to the configuration file. The URL mustuse the file:/// format. Default isJAVA_HOME/PdPerm.properties.

URL of the keystore file URL to the keystore file. The URL must usethe file:/// format. Default isJAVA_HOME/lib/security/pdperm.ks.

Option One of the following:

create Creates the specified PDPrincipalobject and create the configurationand keystore files. Throws anexception if the files already exist.

replace Replaces the configuration andkeystore files with the informationprovided.

unconfigDeletes the keystore file andremoves application-relatedinformation from the configurationfile, but does not delete it.


Chapter 5. Upgrade considerations

Existing Java applications built using the authorization API provided in previousversions of Tivoli SecureWay® Policy Director need to be aware of the followingchanges introduced in this version of IBM Tivoli Access Manager (AccessManager).1. The Tivoli SecureWay Policy Director authorization ADK is now called the

Access Manager ADK and only contains the Javadoc information associatedwith the Java classes and methods. The authorization API Java classes andmethods are provided as part of the Access Manager Java runtime component.Both of these components are installable from the Access Manager base productCD.

2. The PD.jar file replaces the PDPerm.jar file that was provided in previousversions of Tivoli SecureWay Policy Director. The PD.jar file contains thedefinitions for both the authorization Java classes as well as the administrationJava classes.

3. You no longer need to copy the JAR files or make changes to the CLASSPATHenvironment variable to use Access Manager Java classes and methods. Thenew pdjrtecfg command line interface is used to make the Access Manager JARfiles available to one or more JREs on a system. See the IBM Tivoli AccessManager Base Installation Guide for information on the pdjrtecfg command.

4. In previous versions of Tivoli SecureWay Policy Director, two pdadmincommands had to be entered on the policy server before using the SvrSslCfgclass to create configuration files. The SvrSslCfg class has been enhanced inthis version to automatically create the desired PDPrincipal object on the policyserver.


Appendix A. Deprecated Java classes and methods

No Java classes or methods have been deprecated at this time.


Appendix B. 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 reference to an IBMproduct, program, or service is not intended to state or imply that only that IBMproduct, program, or service may be used. Any functionally equivalent product,program, or service that does not infringe any IBM intellectual property right maybe used instead. However, it is the user’s responsibility to evaluate and verify theoperation of 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-1785U.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-0032, 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 orimplied warranties in certain transactions, therefore, this statement may not applyto 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 78758U.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 information 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.

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 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 notbeen 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.

If you are viewing this information softcopy, the photographs and colorillustrations may not appear.

TrademarksThe following terms are trademarks or registered trademarks of InternationalBusiness Machines Corporation in the United States, other countries, or both:


AIXDB2IBMIBM logoOS/390SecureWayTivoliTivoli logoUniversal DatabaseWebSpherez/OSzSeries

Lotus is a registered trademark of Lotus Development Corporation and/or IBMCorporation.

Domino is a trademark of International Business Machines Corporation and LotusDevelopment Corporation in the United States, other countries, or both.

Microsoft and Windows are trademarks of Microsoft Corporation in the UnitedStates, other countries, or both.

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

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.

Appendix B. Notices 27

Index

Aaccessibility xvadding development systems 2application, deploying 4applications, building 2Authorization API

installing 2authorization server 1, 4azn_entitlements_get_entitlements() function 15

Bbooks

feedback xonline xordering x

building applications 2

Cclasses

PDAttrs 18PDAttrValue 19PDAttrValues 19PDLoginModule 17PDPermission 18PDPrincipal 17PDStatics 19SvrSslCfg 20

Customer Support xv

Ddeploying an application 4development systems, adding 2

Ee-mail contact xventitlements 15entitlements service plug-in 15

Ffeedback about publications xvfiles, installation directories 1

IIBM SecureWay Directory client 3installation 2installation directories 1installation requirements 2

JJava classes 1

Mmanuals


Oonline publications xivordering publications xiv

PPD.jar file 2pdacld server 4PDAttrs class 18PDAttrValue class 19PDAttrValues class 19PDLoginModule class 17pdmgrd server 4PDPermission class 18PDPrincipal class 17PDStatics class 19policy server 4prerequisite publications xproblem determination 4protected objects entitlements service 15publications


Rregistry, user 3related publications xiirequirements, for installation 2

Ssecure domain 2service plug-ins 15signed JAR files 3software requirements 2SSL 1SvrSslCfg class 20

using 12

TTivoli Customer Support xvTivoli Information Center xiv

Uuser registry 3


Printed in the United States of Americaon recycled paper containing 10%recovered post-consumer fiber.

GC23-4688-00

ts-doc: ts-636 - help, my nt server's too slow - sas

Documents