Am611 Web Devref

7/28/2019 Am611 Web Devref

http://slidepdf.com/reader/full/am611-web-devref 1/140

Tivoli ® Access Manager for e-business Version 6.1.1

Web Security Developer Reference

SC23-6517-01





Tivoli ® Access Manager for e-business Version 6.1.1

Web Security Developer Reference

SC23-6517-01



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

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

Publications . . . . . . . . . . . . . . vIBM 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. External authentication C APIconcepts . . . . . . . . . . . . . . 1Application development kit (ADK) overview . . . 2Authentication terminology . . . . . . . . . 3Authentication interfaces . . . . . . . . . . 4

Web security resource manager . . . . . . . 4Tivoli Access Manager runtime . . . . . . . 4Tivoli Access Manager authorization API . . . . 5External authentication C API . . . . . . . 5External authentication C API modules . . . . 5

Process flows for authentication operations . . . . 7Authentication process flow . . . . . . . . 7Change password process flow . . . . . . . 8

Password strength process flow . . . . . . . 8Post password change process flow. . . . . . 9Extended attributes process flow. . . . . . . 9

Chapter 2. Application development kitcomponents . . . . . . . . . . . . 11External authentication C API . . . . . . . . 12Cross-domain mapping framework API . . . . . 13Password strength API (deprecated) . . . . . . 14EPAC demonstration application . . . . . . . 15

Chapter 3. Authentication modulecustomization. . . . . . . . . . . . 17

Task summary for custom module implementation 18External authentication C API requirements . . . 19External authentication C API softwarerequirements . . . . . . . . . . . . . 19External authentication C API build instructions 19External authentication C API example library. . 19

Configuring WebSEAL to use a customauthentication module . . . . . . . . . . . 21UTF-8 compatibility . . . . . . . . . . . 24

UTF-8 compatibility for custom authenticationmodules . . . . . . . . . . . . . . 24User credential data format . . . . . . . . 24

Entitlements service data format . . . . . . 24Conversion library for authentication data . . . 25

Configuring the conversion library . . . . . 25External authentication C API functions . . . . . 27External authentication C API and utility APIfunctions . . . . . . . . . . . . . . 27Initializing the external authentication C API . . 28

External authentication C API data structures . . . 29Extended attribute information . . . . . . . 29User identity information . . . . . . . . . 29Authentication data . . . . . . . . . . 30

Chapter 4. Writing customauthentication modules . . . . . . . 31Customizing the authentication process . . . . . 32

1. Obtaining user authentication information . . 32

2. Authenticating the user . . . . . . . . 323. Returning the user identity . . . . . . . 334. Returning the authentication status . . . . 33

Customizing user password change . . . . . . 35Customizing password strength checking . . . . 36Processing post password changes. . . . . . . 37Adding extended attributes to the credential . . . 38Modifying the user name in a credential. . . . . 40

Chapter 5. Single signon customization 43WebSEAL single signon concepts . . . . . . . 44

Default token creation for cross-domain singlesignon . . . . . . . . . . . . . . . 44

Default token creation for e-community singlesignon . . . . . . . . . . . . . . . 44Default token consumption for cross-domainsingle signon . . . . . . . . . . . . . 45Default token consumption for e-communitysingle signon . . . . . . . . . . . . . 45

Customizing token create and consume modules . . 47Built-in token create and consume modules. . . 47Example token create and consume modules . . 47The token create module interface . . . . . . 48The token consume module interface . . . . . 49

Customizing identity mapping and attributehandling . . . . . . . . . . . . . . . 50

Cross-domain mapping framework overview . . 50

Software requirements for the cross-domainmapping framework API . . . . . . . . . 51Build instructions for the cross-domain mappingframework API . . . . . . . . . . . . 51Customizing the example source file . . . . . 51Providing user attributes:cdmf_get_usr_attributes() . . . . . . . . . 52Providing identity mapping: cdmf_map_usr() . . 52Specifying extended attributes . . . . . . . 52

Example: Cross-domain single signon with anon-WebSEAL server . . . . . . . . . . . 54

© Copyright IBM Corp. 2002, 2010 iii



Sending cross-domain single signon requests to anon-WebSEAL server . . . . . . . . . . 54Accepting cross-domain single signon requestsfrom a non-WebSEAL server. . . . . . . . 54

Appendix A. External authentication CAPI reference . . . . . . . . . . . . 57

xattr_get() . . . . . . . . . . . . . . 58xattr_list_item_t . . . . . . . . . . . . . 59xattr_list_t . . . . . . . . . . . . . . 60xattr_set() . . . . . . . . . . . . . . . 61xauthn_utils_append_extcred_tags() . . . . . . 62xauthn_authenticate() . . . . . . . . . . . 63xauthn_change_password() . . . . . . . . . 64xauthn_identity_t . . . . . . . . . . . . 65xauthn_initialize() . . . . . . . . . . . . 66xauthn_shutdown() . . . . . . . . . . . 67xauthn_util_entry_to_creds() . . . . . . . . 68xnvlist_get() . . . . . . . . . . . . . . 69xnvlist_item_t . . . . . . . . . . . . . 70xnvlist_t . . . . . . . . . . . . . . . 71

Appendix B. Cross-domain mappingframework C API reference . . . . . . 73cdmf_add_attr_to_list() . . . . . . . . . . 74cdmf_add_value_to_attr() . . . . . . . . . 75cdmf_create_usr_attr() . . . . . . . . . . 76cdmf_create_usr_attr_list() . . . . . . . . . 77cdmf_get_usr_attributes() . . . . . . . . . 78cdmf_map_usr() . . . . . . . . . . . . 79CDSSO_FREE() . . . . . . . . . . . . . 81CDSSO_MALLOC() . . . . . . . . . . . 82CDSSO_REALLOC() . . . . . . . . . . . 83CDSSO_STRDUP() . . . . . . . . . . . . 84

Appendix C. Authentication identifiersreference. . . . . . . . . . . . . . 85

Identifiers common to all authentication methods . 86User name and password authentication identifiers 88Certificate authentication identifiers . . . . . . 89Token card authentication identifiers . . . . . . 90HTTP authentication identifiers. . . . . . . . 91Failover authentication identifiers . . . . . . . 92EAI identifiers . . . . . . . . . . . . . 93Token create identifiers . . . . . . . . . . 94Token consume identifiers . . . . . . . . . 95Switch user authentication identifiers . . . . . . 96

Appendix D. External authenticationinterface . . . . . . . . . . . . . . 99

Appendix E. Support information . . . 101Searching knowledge bases. . . . . . . . . 101

Searching information centers . . . . . . . 101Searching the Internet . . . . . . . . . 101

Obtaining fixes . . . . . . . . . . . . . 101Registering with IBM Software Support . . . . 102Receiving weekly software updates . . . . . . 102

Contacting IBM Software Support . . . . . . 103Determining the business impact . . . . . . 103Describing problems and gathering information 104Submitting problems . . . . . . . . . . 104

Appendix F. Notices . . . . . . . . 107Trademarks . . . . . . . . . . . . . . 109

Glossary . . . . . . . . . . . . . 111

Index . . . . . . . . . . . . . . . 121

iv Web Security Developer Reference



About this publication

Welcome to the IBM® Tivoli® Access Manager for e-business Web Security DeveloperReference.

This document provides programming information and references for developingauthentication modules using the external authentication C API. It also includesinstructions for developing authentication modules that provide cross-domainsingle signon authentication and e-community single signon. The use of thecross-domain mapping framework to enhance cross-domain single signon ande-community single signon is also described. The document contains the APIreferences for the external authentication C API and the cross-domain mappingframework API.

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

Intended audience

This guide is for system administrators responsible for the installation,deployment, and administration of Tivoli Access Manager.

Readers must be familiar with:

v Microsoft® Windows® and UNIX® operating systems

v Security management

v Internet protocols, including HTTP, HTTPS, and TCP/IP

v Lightweight Directory Access Protocol (LDAP) and directory services

v Authentication and authorizationv Access Manager security model and its capabilities

If you are enabling Secure Sockets Layer (SSL) communication, you must befamiliar with SSL protocol, key exchange (public and private), digital signatures,cryptographic algorithms, and certificate authorities.

Publications

This 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

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-6502

© Copyright IBM Corp. 2002, 2010 v



Explains how to install and configure Tivoli Access Manager for e-business.

v IBM Tivoli Access Manager for e-business: Upgrade Guide, SC23-6503

Upgrade 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-6504

Describes the concepts and procedures for using Tivoli Access Manager. Providesinstructions for performing tasks from the Web Portal Manager interface and by

using the pdadmin utility.v IBM Tivoli Access Manager for e-business: WebSEAL Administration Guide,

SC23-6505

Provides 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-6506

Provides 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 Administration

Guide, 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 Management Administration Guide, SC23-6509

Provides deployment considerations and operational instructions for the sessionmanagement server.

v IBM Global Security Kit: Secure Sockets Layer Introduction and iKeyman User's Guide ,SC23-6510

Provides information for enabling SSL communication in the Tivoli AccessManager environment.

v IBM Tivoli Access Manager for e-business: Auditing Guide, SC23-6511

Provides 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-6512

Provides 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-6513

Provides reference information about using the C language implementation of

the 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-6514

Provides reference information about using the Java™ language implementationof the administration API to enable an application to perform Tivoli AccessManager administration tasks.

v IBM Tivoli Access Manager for e-business: Authorization C API Developer Reference,SC23-6515

vi Web Security Developer Reference



Provides reference information about using the C language implementation of the authorization API to enable an application to use Tivoli Access Managersecurity.

v IBM Tivoli Access Manager for e-business: Authorization Java Classes DeveloperReference, SC23-6516

Provides reference information about using the Java language implementation of

the authorization API to enable an application to use Tivoli Access Managersecurity.

v IBM Tivoli Access Manager for e-business: Web Security Developer Reference,SC23-6517

Provides programming and reference information for developing authenticationmodules.

v IBM Tivoli Access Manager for e-business: Troubleshooting Guide, GC27-2717

Provides problem determination information.

v IBM Tivoli Access Manager for e-business: Error Message Reference, GI11-8157

Provides 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 Access

Manager Base CD for your particular platform, as well as on the IBM Tivoli Access Manager 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 Access

Manager 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:

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

About this publication vii

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



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



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 Access

Manager 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 auditevents.

v Session management server, which manages shared session in a Web securityserver 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 Web Security Developer Reference


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


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

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

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



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




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-2755

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

Accessibility

Accessibility 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 Access Manager for e-business Installation Guide.

Tivoli technical training

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

Tivoli user groups

Tivoli user groups are independent, user-run membership organizations thatprovide Tivoli users with information to assist them in the implementation of

Tivoli 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+ members

v 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/alphaworks/topics/accessibility/


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

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

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

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







Support information

If 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 Access

Manager for e-business Installation Guide.

Conventions used in this publication

This 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, spin buttons, 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 CDs

v 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 wordthat 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 examples

v File names, programming keywords, and other elements that are difficultto distinguish from surrounding text

v Message text and prompts addressed to the user

x Web Security Developer Reference

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










v Text that the user must type

v 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 Web Security Developer Reference



Chapter 1. External authentication C API concepts

Topic Index:

v “Application development kit (ADK) overview” on page 2

v “Authentication terminology” on page 3

v “Authentication interfaces” on page 4

v “Process flows for authentication operations” on page 7

© Copyright IBM Corp. 2002, 2010 1



Application development kit (ADK) overview

The Tivoli Access Manager Web security application development kit (ADK)contains programming resources that allow you to customize and extend thefunctionality of the authentication modules built into WebSEAL. The ADKprovides programming interfaces that enable you to:

v Add functionality to the built-in authentication modules

v Write replacement authentication modules

The ADK also provides an example program that demonstrates how to use theTivoli Access Manager authorization API to extract user credential attributes. Thisprogram is included because it is helpful in testing the results of authenticationoperations.

The Tivoli Access Manager Web security application development kit can be usedwith either Tivoli Access Manager WebSEAL or Tivoli Access Manager plug in forWeb Servers. Both of these components provide the server processing that handlesauthentication requests. You can use the interfaces provided by the Tivoli AccessManager Web security application development kit to write customized

authentication modules for use by either of the Tivoli Access Manager Websecurity components.

This developer reference uses the term Web security resource manager. The termresource manager is used by Tivoli Access Manager to describe an application orprocess that handles requests from clients and then engages with the Tivoli AccessManager authorization service to determine if a client must be allowed to performthe requested action on the requested protected resource. Tivoli Access ManagerWebSEAL and the Tivoli Access Manager plug in for Web servers are bothexamples of a Web security resource manager.

The plug-in for Web servers runs in the same process as an external Web server,such as Microsoft IIS. In this developer reference, the term Web security resource

manager can refer not only to the WebSEAL server, but also can refer to a serverprocess that includes the external Web server plus the security functions provided

by the Tivoli Access Manager plug in for Web servers.

For more information about the Tivoli Access Manager Web security components,see:

v IBM Tivoli Access Manager for e-business: WebSEAL Administration Guide

v IBM Tivoli Access Manager for e-business: Plug-in for Web Servers AdministrationGuide

The external authentication interface is an alternate method for customizing theauthentication process. Complete information about using the external

authentication interface is located in the IBM Tivoli Access Manager for e-business:WebSEAL Administration Guide.

2 Web Security Developer Reference



Authentication terminology

This document uses the following terminology for discussing authentication:

v method

An authentication method describes the overall process and strategy of anauthentication type. Examples of authentication methods include, but are not

limited to:– Username/password

– Token

– Certificate

Typically, but not always, authentication methods have a one-to-one relationshipwith a particular type of data used to prove a user identity.

v mechanism

An authentication mechanism describes how an authentication method isenabled and specifically refers to the appropriate configuration stanza entry(such as passwd-ldap) used in the WebSEAL configuration file.

v module

An authentication module describes where an authentication method isperformed and specifically refers to the shared library file (such aslibsslauthn.so) that performs the authentication and returns the client identity toWebSEAL, if successful.

There is a one-to-one mapping between an authentication method and anauthentication module. For example, if a user provides authentication data usingthe password authentication method, the same module is used to bothauthenticate that user and to change the user password, if the user prefers to doso).

The authentication modules are dynamic and are written as plug-ins. They can be replaced with new versions, and when the Web security resource manager isrestarted, it uses the new authentication module to handle the operations

associated with a particular authentication method. Both standard built-in andcustom authentication modules load directly into the Web security resourcemanager memory and run as part of the server process.

v operations

An authentication operation describes any action that supports theauthentication method. For example:

– Performing an LDAP lookup during user name and password authentication.

– Changing a user password.

– Verifying that a new password meets certain criteria.

– Adding attributes to an authenticated identity.

A given authentication method can have more than one authentication operation

associated with it. For example, the token authentication method includes theoperations of authenticating, creating a new PIN number, and prompting a userto enter a new PIN. Some methods might not perform an actual authenticationat all. An example is the credential attribute entitlement service, whose solefunction is to add new attributes to an authenticated identity before a credentialis constructed.

Chapter 1. External authentication C API concepts 3



Authentication interfaces

Tivoli Access Manager uses a flexible framework that allows the functions thathandle authentication operations to be easily modified or replaced. This diagramshows the main components used in processing authentication operations.

The following sections describe the purpose of each components.

Web security resource managerThe Web security resource manager can be either the WebSEAL component or theplug-in for Web Servers component.

The resource manager:

v Extracts authentication data from user requests and provides it to the Tivoli

Access Manager runtime.

v Receives the results of authentication operations from the runtime. The resultscan be statuses or, in the case of actual authentication, user credentials thatrepresent authenticated accounts.

Tivoli Access Manager runtimeThe Tivoli Access Manager runtime is the set of libraries provided in the TivoliAccess Manager runtime installation package. These Tivoli Access Managerlibraries are separate from the authentication modules. They provide core TivoliAccess Manager security management functions for use by various resourcemanagers, including some that are unrelated to Web security. The Web securityresource managers require these libraries as a prerequisite. The libraries are not

customizable.

The Tivoli Access Manager runtime libraries perform the following tasks:

v Pass authentication data to the external authentication (xauthn) C API.

v Receive statuses or, when authentication occurs, identity structures back fromthe external authentication C API.

Note: An identity structure is a collection of data that represents anauthenticated user.

Figure 1. Tivoli Access Manager Web security authentication interfaces




v Pass authentication data or identity structures back to the external authenticationC API. (This step is not performed in all cases)

v Determine if an identity was received from the external authentication C API. If yes, the runtime passes the identity to the Tivoli Access Manager authorizationAPI to build a credential.

v Receive statuses, or credentials, or both back from the authorization API and

pass them to the Web security resource manager.

Tivoli Access Manager authorization APIThe authorization API is a Tivoli Access Manager component. It performsauthorization tasks, including the following:

v Receives an identity structure from the runtime.

v Extracts the user name contained in the identity structure.

v Attempts to find the user name in the Tivoli Access Manager user registry.

v When successful, constructs a user credential.

v Returns the credential to the runtime.

External authentication C APINote: In previous releases, custom authentication modules were built using the

Tivoli Access Manager cross-domain authentication services or CDAS. This termis no longer used because the scope of the term CDAS is no longer wideenough to cover all the functions performed by Web security resourcemanager authentication modules. The replacement term is externalauthentication C API . The new term reflects only a change in terminology.

The external authentication C API interface performs the following tasks:

v Receives authentication data from the runtime.

v Organizes the data into a standard format.

vPasses the data to the authentication modules.

v Receives statuses, identity structures, or both back from the authenticationmodules.

v Passes the statuses, identity structures, or both back to the runtime.

External authentication C API modulesThe use of the external authentication C API to author custom authenticationmodules is described in this developer reference.

Every authentication module implements one or more of four functions defined bythe external authentication module interface. This is true both for the built-inauthentication modules as well as custom modules that you can develop using the

external authentication C API.

The complete programming reference for the external authentication C API isdescribed in detail in Appendix A, “External authentication C API reference,” onpage 57.

In summary, the four functions of the external authentication C API include:

v xauthn_initialize()

Initializes a specified authentication module shared library.

v xauthn_authenticate()




Performs the authentication module authentication tasks.

v xauthn_change_password()

Performs a password change.

v xauthn_shutdown()

Shuts down a specified authentication module shared library.




Process flows for authentication operations

This section describes how authentication methods, and the authenticationoperations they contain, are implemented in the Web security resource managerauthentication framework. The following authentication methods are supported:

v Basic authentication

v

Forms authenticationv Token authentication

v Certificate authentication

v HTTP header authentication

v IP address authentication

v Failover cookie authentication

v Switch-user authentication

v SPNEGO (Kerberos) authentication

v Cross-domain single signon (token)

v e-community single signon

v External authentication interface (EAI)

The process flow for authentication operations are described in the followingsections:

v “Authentication process flow” on page 7

v “Change password process flow” on page 8

v “Password strength process flow” on page 8

v “Post password change process flow” on page 9

v “Extended attributes process flow” on page 9

Authentication process flowThe sequence of events can vary depending on the authentication module. Thegeneral sequence of events is as follows:

1. The Web security resource manager receives a request containing authenticationinformation. For example, the request includes a user name and password.

2. The Web security resource manager extracts the authentication informationfrom the request.

3. The Web security resource manager passes the authentication information tothe runtime.

4. The runtime passes the authentication information to the externalauthentication C API.

5. The external authentication C API formats the information, and then passes itto an authentication module that implements the external

xauthn_authenticate() function.6. The authentication module performs the actual authentication and returns an

identity structure back to the external authentication C API.

7. The external authentication C API passes the identity structure back to theruntime.

8. The runtime passes the identity structure to the authorization API, which thenconstructs a credential and returns it to the runtime.

9. The runtime then passes the credential back to the Web security resourcemanager, for use in authorizing and managing sessions with the user.




Change password process flowThe general sequence of events is as follows:

1. The Web security resource manager receives a request containing authenticationinformation. In this example, an old password and a new password.




5. The external authentication C API formats the information, and then passes itto an authentication module that implements the xauthn_change_password()function.

6. The authentication module performs the password change operation andreturns a status to the external authentication C API.

7. The external authentication C API returns the status to the runtime.

8. The runtime returns the status to the Web security resource manager.

9. The Web security resource manager then communicates either success or failureto the user.

Password strength process flowThe password strength authentication module was implemented in previousversions of Tivoli Access Manager with the password strength API. This API has

been deprecated. The password strength module now uses the externalauthentication C API.

Note: The password strength API is still available to support older modules builtusing the API.

The general sequence of events is as follows:1. The Web security resource manager receives a request containing

authentication information. In this example, the request includes an oldpassword and a new password.




5. The external authentication C API formats the information, and then passes itto an authentication module that implements the xauthn_change_password()

function.

6. The xauthn_change_password() recognizes that a password strength modulehas been configured. The password strength module is called, and decideswhether the new password satisfies the password strength policy.

7. When the password strength policy is satisfied, the password is changed.When the password strength policy is not satisfied, the password change isdenied. The status is returned to the external authentication C API.


9. The runtime returns the status to the Web security resource manager.




10. The Web security resource manager then communicates either success orfailure to the user.

Post password change process flowThis authentication module is chained. Rather than calling directly through theinterface from the Web security resource manager, it is always called (when

configured) after the completion of a change password operation performed byanother authentication module using the xauthn_change_password() function.

The general sequence of events is as follows.

1. The Web security resource manager receives a request containingauthentication information. In this example, the request includes an oldpassword and a new password.



4. The runtime passes the authentication information to the external

authentication C API.5. The external authentication C API formats the information, and then passes it

to an authentication module that implements thexauthn_change_password()function.

6. The authentication module performs the password change operation andreturns a status to the external authentication C API.


8. The runtime recognizes that a post password change module has beenconfigured.

9. The runtime then passes the authentication information to the post passwordchange module.

10.

The module performs some operation, such as synchronizing the passwordwith an external registry, and then returns a status to the externalauthentication C API.

11. The external authentication C API returns the status to the Web securityresource manager.

Extended attributes process flowThis authentication module is chained. Rather than calling directly through theinterface from the Web security resource manager, it is always called (if configured)after the completion of an authentication operation performed by anotherauthentication module using the xauthn_authenticate() function.

The general sequence of events is as follows.1. The Web security resource manager receives a request containing

authentication information. In this example, the request includes a usernameand password.







5. The external authentication C API formats the information, and then passes itto an authentication module that implements thexauthn_authenticate()function.

6. The authentication module performs the actual authentication and returns anidentity structure back to the external authentication C API.

7. The external authentication C API then passes the identity to the runtime.

8. The runtime recognizes that an extended attribute module has beenconfigured and passes the identity structure back through the externalauthentication C API to the extended attributes authentication module.

9. The extended attributes authentication module adds extended attributes to theidentity structure and returns it back to the external authentication C API.

10. The external authentication C API passes the identity structure back to theruntime.

11. The runtime passes the identity structure to the authorization API. Theauthorization API constructs a credential and returns it to the runtime.

12. The runtime then passes the credential back to the Web security resourcemanager, for use in authorizing and managing sessions with the user.




Chapter 2. Application development kit components

The Web Security application development kit provides two authentication APIs, apassword strength module (deprecated), and a demonstration application.

Topic Index:

v “External authentication C API” on page 12

v “Cross-domain mapping framework API ” on page 13

v “Password strength API (deprecated)” on page 14

v “EPAC demonstration application” on page 15




External authentication C API

The Web security external authentication C API is a programming interface youcan use to build a custom authentication module.

The external authentication C API can be found in the Web Security ADK package(PDWebADK) and includes the following components:

v External authentication C API header files

v External authentication C API library

v Source file

v Example pre-built authentication module (for demonstration only)

v Makefiles for building custom libraries

The external authentication C API components are located in a directory namedpdxauthn_adk.

The API components are contained in the following subdirectories:

Table 1. External authentication C API components

Directory Contents

include Contains C header files:

v pdxauthn.h

Definition of function prototypes, client identity, and error codes usedfor authentication API functions

v xnvlist.h

User authentication data structure utility functions

v xattr.h

User extended attributes data structure utility functions

lib Contains the authentication module authentication static library files:

v UNIX or Linux systems: libpdxauthn.a

v Windows systems: pdxauthn.lib

example Contains:

v Source file (xauthn.c) for customization

v Makefile

v A pre-built platform-specific example library to demonstrate afunctional authentication module.




Cross-domain mapping framework API

Cross-domain mapping framework is a programming interface you can use to build a custom library that provides mapping services for a user identity andhandles any extended user attributes.

The cross-domain mapping framework is used with Tivoli Access Manager

cross-domain single signon solutions.

The cross-domain mapping framework API can be found in the Web Security ADKpackage (PDWebADK) and includes the following components:

v Cross-domain mapping framework API library

v Cross-domain mapping framework API header file

v Demonstration cross-domain mapping framework file

v Makefiles

The cross-domain mapping framework components are located in a directorynamed cdmf_adk. The following table lists the files included in this directory:

Table 2. Cross-domain mapping framework API components

Files Description

cdmf.c.skeleton The source file that can be customized by thedeveloper to implement the cross-domain mappingframework logic. This file needs to be renamed tocdmf.c and then compiled and linked into thecross-domain mapping framework library.

cdmf.c.example Example cdmf.c file

This example performs a simple user mapping andperforms some manipulation of the cross-domainsingle signon attribute lists.

cdmf.h The header file for cdmf.c.

cdmf_utils.h The header file providing utility functions formanipulating extended user attribute lists.

cdssotypes.h The header file that provides definitions of types andmacros used in cdmf.c.

Windows only:

cdmf_utils.lib The library for the utility functions in cdmf_utils.h.

Makefile.win32 The makefile used to build the custom cross-domainmapping framework library.

UNIX or Linux only:

libcdmfutils. (so, a, sl) The library for the utility functions defined incdmf_utils.h.- .so for Solaris and Linux- .a for AIX- .sl for HP-UX

Makefile.cdmf.in The template makefile used to build the cross-domainmapping framework library. Change this file to suityour platform.

Chapter 2. Application development kit components 13



Password strength API (deprecated)

The interface used for the password strength module has changed for version 5.1and later of Tivoli Access Manager.

The password strength API is deprecated, and is available only to support oldermodules.

The external authentication C API is now used for this module and is described in“Customizing password strength checking” on page 36.




EPAC demonstration application

The Web Security application development kit contains a CGI program that readsinformation that is stored in the form of an extended privilege attribute certificate(EPAC) and converts it to a Tivoli Access Manager user credential. The EPAC isobtained from the HTTP_IV_CREDS variable. In addition, the program displaysthe name and value for each credential attribute contained in the EPAC.

The application development kit contains the following files for the EPACdemonstration application:

Table 3. EPAC demonstration application files

File Description

epac The demonstration program.

epac.c Source for the demonstration program.

Makefile.in Makefile (for use when building the program).

README A text file containing instructions for how to build and configure theprogram.

The EPAC uses the Tivoli Access Manager authorization API. To use theauthorization API, you must install the Tivoli Access Manager authorization ADKpackage (PDAuthADK).

You can use the EPAC demonstration binary as distributed, or you can modify thesource to customize it for your deployment. The source uses a number of authorization API function calls. You can find more information about thesefunctions in the IBM Tivoli Access Manager for e-business: Authorization C API Developer Reference.

The EPAC source contains a utility function for writing debug output to a log file,

and a utility function for formatting the output of the credential attribute list intoan HTML table. You can use these functions as written, or edit them to modify theoutput format.

The following table describes the credential attributes that are displayed by theEPAC program:

Table 4. EPAC demonstration application credential attributes

Attribute name Description

AUTHENTICATION_LEVEL Authentication mechanism level, in terms of authentication strength policy. For example:

1

AZN_CRED_AUTH_METHOD The authentication method used. For example:

password

AZN_CRED_AUTHNMECH_INFO Information about the authentication mechanism.For example:

LDAP Registry

AZN_CRED_AUTHZN_ID User identity. For example, for an LDAP userregistry:

cn=joeuser,o=ibm,c=us

AZN_CRED_BROWSER_INFO Information identifying the type and version of browser

Chapter 2. Application development kit components 15



Table 4. EPAC demonstration application credential attributes (continued)

Attribute name Description

AZN_CRED_GROUPS Group identifiers, in UUID format

AZN_CRED_GROUPS_NAMES Group names, in user registry format. Forexample:

cn=sales,o=ibm,c=us

AZN_CRED_IP_ADDRESS IP address (hex number)

AZN_CRED_LDAP_DN LDAP DN for the user (principal)

AZN_CRED_MECH_ID User registry mechanism ID. For example:

IV_LDAP_V3.0

AZN_CRED_PRINCIPAL_NAME User name

AZN_CRED_PRINCIPAL_UUID User identity, expressed as a Universal UniqueIdentifier

AZN_CRED_QOP_INFO Quality of protection setting

AZN_CRED_VERSION Credential version (indicates release of TivoliAccess Manager).

To use the EPAC demonstration, complete the following steps:

1. Build the EPAC CGI executable.

2. Configure the EPAC as an authorization API application.

3. Deploy and run the EPAC executable.

For more information about each of the above steps, see the README file thataccompanies the EPAC source file.




Chapter 3. Authentication module customization

Topic Index:

v “Task summary for custom module implementation” on page 18

v “External authentication C API requirements” on page 19

v “Configuring WebSEAL to use a custom authentication module” on page 21

v “UTF-8 compatibility” on page 24

v “External authentication C API functions” on page 27

v “External authentication C API data structures” on page 29




Task summary for custom module implementation

The basic process for implementing a custom authentication module includes thefollowing tasks:

1. Identify the type of authentication method and data that you want to process.

You can write a custom authentication module for any of the authentication

mechanisms supported by WebSEAL or the Plug-in for Web Servers.Instructions for developing authentication modules for each type of authentication operation are described in Chapter 3, “Authentication modulecustomization,” on page 17.

The cross-domain single signon and e-community single signon authenticationmodules require additional instructions, including the optional use of thecross-domain mapping framework API. This is described in Chapter 5, “Singlesignon customization,” on page 43.

2. Build a custom library using the external authentication C API.

For detailed instructions on writing a custom authentication library, seeChapter 4, “Writing custom authentication modules,” on page 31.

For an overview of the external authentication C API and the cross-domain

mapping framework, see Chapter 2, “Application development kitcomponents,” on page 11.

Reference pages for each of the external authentication C API functions areprovided in Appendix A, “External authentication C API reference,” on page57.

Reference pages for the cross-domain mapping framework are provided inAppendix B, “Cross-domain mapping framework C API reference,” on page 73.

3. Configure the Web security resource manager to use the custom library forthe specified data.

You configure custom authentication modules into the secure Web server bymodifying entries in the secure Web server configuration file. This developerreference provides configuration instructions in Chapter 3, “Authentication

module customization,” on page 17 and Chapter 5, “Single signoncustomization,” on page 43.

When you are ready to configure a new authentication module for WebSEAL,you should also review the detailed authentication configuration information inthe IBM Tivoli Access Manager for e-business: WebSEAL Administration Guide.

To review detailed configuration information for authentication modules used by the plug-in for Web servers, see also the IBM Tivoli Access Manager fore-business: Plug-in for Web Servers Administration Guide.




External authentication C API requirements

This section contains the following topics:

v “External authentication C API software requirements ” on page 19

v “External authentication C API build instructions ” on page 19

v “External authentication C API example library ” on page 19

External authentication C API software requirementsThe Web Security application development kit provides all the necessary resourcesfor authentication module application development.

To develop and test an authentication module on a single machine, the followingTivoli Access Manager components must be installed:

v Tivoli Access Manager runtime (PDRTE)

v Tivoli Access Manager policy server (PDMgr)

v Tivoli Access Manager authorization ADK (PDAuthADK)

v Tivoli Access Manager WebSEAL (PDWeb) or the Tivoli Access Manager plug in

for Web Serversv Tivoli Access Manager Web Security ADK (PDWebADK)

For instructions regarding installation and configuration of Tivoli Access Managercomponents, refer to the IBM Tivoli Access Manager for e-business: Installation Guide.

External authentication C API build instructionsYou build an authentication module by using make to compile your source file.The WebSEAL application development kit provides a sample MakefileMakefile.in under the example directory.

In many cases, you can use the Makefile with minimum changes. The Makefile

template is written to compile the example source file xauthn.c. See theMakefile.in template for more information.

When compiling the library, add the include directory of the Web Securityapplication development kit to the compiler command line.

When linking the library, include the appropriate pdxauthn library. See “Externalauthentication C API” on page 12.

External authentication C API example libraryThe Tivoli Access Manager Web security ADK includes an example(demonstration) library that implements a generic user name and passwordauthentication module. The sample library is an interactive program that displaysall the available client authentication data and prompts for a user identity.

In addition, the example library can be used as an extended attributesauthentication module. In this case, the prompts ask for tag/value data instead of client authentication data.

The example library is located in the example directory of the applicationdevelopment kit (PDWebADK) package. To use the sample library with WebSEAL,configure WebSEAL as described in “Configuring WebSEAL to use a customauthentication module” on page 21.

Chapter 3. Authentication module customization 19



Then, using the sample library, run the Tivoli Access Manager Web securityresource manager (WebSEAL or the plug-in for Web Servers) in the foreground. Forexample, on a Solaris system:

WebSEAL# /opt/pdweb/bin/webseald -foreground

Plug-in for Web Servers

# /opt/pdwebpi/bin/pdwebpi -foreground

The program user interface for client authentication data for the WebSEAL versionof the application appears as follows:

===============================User Authentication Information:===============================xauthn_username: laura (4)xauthn_password: 123456 (9)xauthn_ipaddr_ipv6: :: (3)xauthn_ipaddr: 9.0.0.119 (13)xauthn_qop: SSK: TLSV1: 35 (15)xauthn_browser_info: Mozilla/5.0 (X11; U; Linux i686; en-US; rv:1.7.6)Gecko/20050223 Firefox/1.0.1 (79)xauthn_existing_cred: 0

Please enter the registry ID number: 1Enter the user identity: laura===============================

The user identity testuser as in the preceding example is returned to WebSEAL.

The program user interface for adding external attribute data appears as follows:

===============================User Authentication Information:===============================xauthn_username: laura (4)xauthn_password: 123456 (9)xauthn_ipaddr_ipv6: :: (3)xauthn_ipaddr: 9.0.0.119 (13)

xauthn_qop: SSK: TLSV1: 35 (15)xauthn_browser_info: Mozilla/5.0 (X11; U; Linux i686; en-US; rv:1.7.6)Gecko/20050223 Firefox/1.0.1 (79)xauthn_existing_cred: 0Enter the test tag: emailEnter the test tag data: [email protected]===============================




Configuring WebSEAL to use a custom authentication module

Tivoli Access Manager supports many configuration options for authenticationmodules. The following set of instructions covers common cases as applicable to atypical authentication module deployment.

The IBM Tivoli Access Manager for e-business: WebSEAL Administration Guide and the

IBM Tivoli Access Manager for e-business: Plug-in for Web Servers Administration Guidecontain detailed discussions of authentication methods, modules, and configurationoptions. Before deploying your authentication module, you should review theappropriate configuration material that applies to the authentication methodimplemented by your authentication module.

The general sequence for configuring an authentication module can be summarizedas follows:

1. Stop the Web security resource manager, such as WebSEAL.

2. Open the configuration file for editing.

3. Enter the appropriate authentication identifier parameter, with the full pathname of the library, in the [authentication-mechanisms] stanza.

authentication_method_identifier = library_name

The following stanza entries specify authentication modules:

Table 5. Stanza entries for authentication mechanisms

Stanza Entries Description

passwd-cdas Specifies an external authentication C API library that implementseither basic authentication or forms authentication.

passwd-ldap Specifies a library that implements basic authentication or formsauthentication with an LDAP user registry.

passwd-uraf Specifies a library that implements basic authentication or formsauthentication using the Tivoli Access Manager URAF interface tounderlying user registry types.

token-cdas Specifies the library that implements token authentication.

cert-ldap Specifies the library that implements certificate authentication forinternal Tivoli Access Manager server communication.

cert-ssl Specifies the library that implements certificate authentication. Usethis stanza entry (not cert-ldap) to implement a custom certificateauthentication module.

http-request Specifies the library that implements HTTP header or IP addressauthentication.

sso-create Specifies the library that implements WebSEAL single signon tokencreation.

sso-consume Specifies the library that implements WebSEAL single signon token

consumption.

kerberosv5 Specifies the library that implements WebSEAL support forSPNEGO authentication. This library is used to provide Windowsdesktop single signon support for WebSEAL .

passwd-strength Specifies the library that enforces custom password strengthauthentication policies.

cred-ext-attrs Specifies the library used to supply extended attribute data to theuser credential.




Table 5. Stanza entries for authentication mechanisms (continued)

Stanza Entries Description

su-password Specifies the library that implements switch user authentication for basic authentication or forms authentication.

su-token-card Specifies the library that implements switch user authentication fortoken authentication.

su-certificate Specifies the library that implements switch user authentication forX.509 certificate authentication.

su-http-request Specifies the library that implements switch user authentication forHTTP header or IP address authentication.

su-cdsso Specifies the library that implements switch user authentication forcross-domain single signon authentication.

su-kerberosv5 Specifies the library that implements switch user authentication forSPNEGO (Kerberos) authentication.

failover-password Specifies the library that implements failover cookie authenticationfor basic authentication or forms authentication.

failover-token-card Specifies the library that implements failover cookie authentication

for token card authentication.failover-certificate Specifies the library that implements failover cookie authentication

for certificate authentication.

failover-http-request Specifies the library that implements failover cookie authenticationfor HTTP header authentication or IP address authentication.

failover-cdsso Specifies the library that implements failover cookie authenticationfor cross-domain single signon authentication.

failover-kerberosv5 Specifies the library that implements failover cookie authenticationfor SPNEGO authentication.

failover-ext-auth-interface

Specifies the library that implements failover cookie authenticationfor custom authentication using the external authenticationinterface.

post-pwdchg-process Specifies the library that implements post password changeprocessing. This is called by WebSEAL when the user changes apassword using the pkmspasswd password change page.

ext-auth-interface Specifies the library that implements custom authentication usingthe external authentication interface.

For example, if you want to externalize LDAP user name and passwordauthentication using a custom module named libxauthn.so (for a Solarissystem), enter the following line:

[authentication-mechanisms]passwd-ldap = /opt/pdweb/lib/libxauthn.so

4. If the custom module accepts any arguments during initialization and

shutdown, they can be specified in the following format (using thelibxauthn.so library as an example):

passwd-ldap = /opt/pdweb/lib/libxauthn.so&arg1 arg2 .... argN

Note: When using a custom module developed to work with a version of WebSEAL or the plug-in for Web Servers prior to Version 5.1, you mightneed to also call a conversion library. See the instructions in “UTF-8compatibility” on page 24.

5. Ensure that each custom module has both read and execute operating systemfile permissions for the ivmgr user.




6. Restart the Web Security resource manager process.




UTF-8 compatibility

Custom authentication modules must be compatible with UTF-8 encoded localcode pages.


v “UTF-8 compatibility for custom authentication modules”

v “User credential data format”

v “Entitlements service data format”

v “Conversion library for authentication data” on page 25

v “Configuring the conversion library” on page 25

Note: This section describes UTF-8 compatibility in WebSEAL. The samecompatibility applies to the plug-in for Web Servers.

UTF-8 compatibility for custom authentication modulesAs of version 5.1 and later, WebSEAL and plug-in for Web Servers have beenconverted to use UTF-8 encoded strings when handling data internally. The use of

UTF-8 encoding enables WebSEAL to support multiple languages at a time, knownas multi-locale support.

The use of UTF-8 encoded strings raises several issues that can affect both theimplementation and use of custom external authentication modules, such asauthentication modules, that were written to work with prior versions of WebSEALand Tivoli Access Manager. Developers who have deployed custom authenticationmodules for use with prior versions of WebSEAL must review the issues in thissection.

Pre-version 5.1 custom authentication modules have typically operated in singlelanguage environment because each WebSEAL process ran in a single-localeenvironment. These environments use a local code page that is not UTF-8 enabled.Because Tivoli Access Manager and WebSEAL processes now run in a multi-localeUTF-8 enabled environment, the format of data read into and written out of theseprocesses has changed. For some custom authentication modules, this change indata format might require code changes to the library. For all customauthentication modules, a configuration (deployment) change is required.

User credential data formatMany custom authentication modules access and modify user credentialinformation. This information is obtained from Tivoli Access Manager by using theTivoli Access Manager authorization C API. For version 5.1 and later, theauthorization C API is now initialized to use UTF-8 strings. This means thatauthorization modules need to be initialized to use UTF-8 as the code page of

choice. Calls to authorization API functionality need to use UTF-8 arguments, andall code that is invoked by authorization modules must expect UTF-8 arguments.

This means that customized authentication modules that use authorization APIfunctions to process user credentials must be modified to expect UTF-8 data. Thismodification can affect switch user authentication modules.

Entitlements service data formatSome customized authentication modules also obtain data from customizedentitlements services. The entitlements services must be called with UTF-8






Table 6. Conversion shared library file names (continued)

Operating system Shared library name

Windows amwauthconv.dll

Custom authentication modules are invoked by entering a command-line argument

into the configuration file. For example (WebSEAL):cert-ssl = /usr/lib/libcustomauth.so& argument1 argument2

The conversion library is also implemented with the external authentication C API.The conversion library takes one or more arguments. The first argument is thename of the custom authentication module library that the application uses.

For example, to use the sample library specified in the previous paragraph withthe conversion library, the entry in the WebSEAL configuration file is as follows:

cert-ssl = /opt/pdwebrte/lib/libamwauthconv.so&/usr/lib/libcustomauth.so argument1 argument2

The preceding command is entered as a single continuous line.

Note: If multiple conversion modules are required, multiple copies must be used because dynamic loaders load shared modules only once.




External authentication C API functions


v “External authentication C API and utility API functions” on page 27

v “Initializing the external authentication C API ” on page 28

External authentication C API and utility API functionsThe following table lists the external authentication C API and utility APIfunctions. The first column contains links to the reference page for each function.The second column contains links to sections in this developer reference thatdescribe the tasks for which this function is called.

Table 7. External authentication C API functions

Function Task

“xauthn_initialize() ” on page 66 “Initializing the external authentication CAPI ” on page 28

“xauthn_authenticate() ” on page 63v “1. Obtaining user authentication

information” on page 32

v “2. Authenticating the user” on page 32

v “3. Returning the user identity” on page33

“xauthn_change_password() ” on page 64v “Customizing user password change” on

page 35

v “Customizing password strengthchecking” on page 36

v “Processing post password changes” onpage 37

“xauthn_shutdown() ” on page 67 “Initializing the external authentication CAPI ” on page 28

Table 8. External authentication utility API functions

Function Task

“xauthn_util_entry_to_creds() ” on page 68 “Converting the credential to string format”on page 32

“xattr_get() ” on page 58 “Adding extended attributes to thecredential” on page 38

“xattr_set() ” on page 61

“xnvlist_get() ” on page 69 “1. Obtaining user authenticationinformation” on page 32

Thepdxauthn

static library file contains the utility functions. To use these utilities,you must link your custom shared library to this file:

Table 9. File names for pdxauthn libraries

Operating system Filename

UNIX libpdxauthn.a

Windows pdxauthn.lib




Initializing the external authentication C APIWebSEAL loads the authentication module library and initializes it by callingxauthn_initialize().

This function contains the argc and argv parameters. These parameters contain thevalues specified in the library definition located in the Web security resource

manager (WebSEAL or Plug-in for Web Servers) configuration file. The librarydefinition uses the following syntax:

authentication_mechanism = library_name[&arg1]...[ argN]

The library definition defines all entries after the ampersand character (&) to beinitialization parameters. Unlike the C language argv, the argv[0] array entry is thefirst parameter.

For more information, see the reference page for xauthn_initialize().

It is not necessary to shut down the external authentication C API. The APIprovides a shutdown function, xauthn_shutdown(). However, the shutdowninterface is not functional in past and current versions of Tivoli Access Manager.

You can successfully complete and use an authentication module implementationwithout it.




External authentication C API data structures


v “Extended attribute information” on page 29

v “User identity information” on page 29

v “Authentication data” on page 30

Extended attribute informationExtended attributes contain information about a user. This information consists of name/value pairs. A series of name/value pairs can be organized into a list. Thislist is used by xauthn_authenticate() to pass extended information about a user tothe custom authentication module library.

The data structure that holds a single extended attribute is xattr_list_item_t.

typedef struct {char *name;char *value;

} xattr_list_item_t;

Table 10. Members of the extended attribute item data structure Member Description

name A string representing the name of the extended attribute.

value A string representing the value of the extended attribute.

The data type xattr_list_t is a list of extended attributes to be added to thecredential.

typedef struct {long length;xattr_list_item_t *items;

} xattr_list_t;

Table 11. Members of the extended attribute list data structure

Member Description

length The number of elements in the list.

items An array of xttr_list_item_t structures.

User identity informationThe xauthn_identity_t data structure used to hold information about the identityof a Tivoli Access Manager user.

typedef struct {struct {

unsigned32 prin_type;union {/* case(s): 0 */char *name;/* case(s): 1 */char *dn;/* case(s): 2 */char *uraf_name;

} data;} prin;




char *user_info;char *authnmech_info;xattr_list_t xattrs;

} xauthn_identity_t;

Table 12. Members of the user identity data structure

Member Description

prin_type Theprin_type indicates the user registry used to generate acredential from the identity. The only valid value isXAUTHN_PRIN_TYPE_DN (LDAP user registry), where the prin.data.dncontains the distinguished name (DN) of the user.

name Not valid.

dn LDAP Distinguished Name (DN) of the user or the LDAP username.

uraf_name Not valid

user_info Information added to the credential as an extended attribute calledazn_cred_user_info.

authnmech_info Authentication method information. Added to the credential as anextended attribute calledazn_cred_mech_id.

xattrs The xattr_list_t data structure can be used to return any extendeduser attributes.

Authentication dataThe xnvlist_item_t data structure holds a single item of authentication data.

typedef struct {char *name;char *value;int vlen;

} xnvlist_item_t;

Table 13. Members of the data structure for authentication data

Member Description

name A string representing the name of the item. Valid names are described in“1. Obtaining user authentication information” on page 32

value An array of bytes representing the value of the item.

The authentication data can be a character string or can be binary data.

vlen An integer value representing the length of the "value" array.

The xnvlist_t data structure holds a list of xnvlist_item_t authentication datastructures.

typedef struct {

long length;xnvlist_item_t *items;

} xnvlist_t;

Table 14. Members of the data structure for a list of authentication data items

Member Description

length The number of elements in the items array.

items An array of xnvlist_item_t.




Chapter 4. Writing custom authentication modules

Topic Index:

v “Customizing the authentication process” on page 32

v “Customizing user password change” on page 35

v “Customizing password strength checking” on page 36

v “Processing post password changes” on page 37

v “Adding extended attributes to the credential” on page 38

v “Modifying the user name in a credential” on page 40




Customizing the authentication process

The xauthn_authenticate() function performs the application-specificauthentication process based on the authentication information found in the datalist, and returns the resulting client identity (xauthn_identity_t ) to WebSEAL orthe plug-in for Web Servers.

The xauthn_authenticate() function is called, for example, after you haveobtained a user name from the user (if one has not been passed in already) andobtained the user registry type. For another example, the library could accept adigital certificate, modify the Distinguished Name (DN) data, and return themodified DN as the Tivoli Access Manager identity.

This section describes how to complete the following steps:

v “1. Obtaining user authentication information” on page 32

v “2. Authenticating the user” on page 32

v “3. Returning the user identity” on page 33

v “4. Returning the authentication status” on page 33

1. Obtaining user authentication informationAs soon as the authentication module library is configured, the Tivoli AccessManager Web security resource manager can pass the client request to the librarythrough the xauthn_authenticate() interface.

The Web security resource manager can pass various client authenticationinformation to the library. The information is passed using a name/value listformat, where the name is an identifier that specifies the value type.

The information is stored in the xnvlist_t data type. Values can be accessed byusing the utility function xnvlist_get() .

For a complete listing of identifiers used for authentication, see Appendix C,“Authentication identifiers reference,” on page 85.

2. Authenticating the userAuthenticate the user against the registry.

Converting the credential to string formatThis optional step is necessary only when the user has previously authenticated,and is now authenticating again in order to be granted additional access privileges.

In this case, the user credential was obtained during the previous authentication.The credential is passed into xauthn_authenticate() user information as

xauthn_existing_cred.

If the xnvlist_t item contains the xauthn_existing_cred item, usexauthn_util_entry_to_creds() to convert the entry to a credential, as anazn_creds_h_t.




3. Returning the user identityThe authentication module library returns the resulting client identity back toWebSEAL or the plug-in for Web Servers. The client identity is defined by thexauthn_identity_t data structure. This structure is returned byxauthn_authenticate().

The client identity is not required if the authentication fails. In that case, a NULLidentity can be returned.

4. Returning the authentication statusThe authentication module library is required to return the authentication status

back to WebSEAL or the plug-in for Web Servers. The authentication status isdefined by the error_status_t data type. This structure is returned byxauthn_authenticate().

The status must be one defined in pdxauthn.h. This status is logged in themsg__webseald.log file. The status and message served to the browser are mappedfrom the status returned by the authentication module. The following tablecontains the appropriate mappings. All mapped statuses and their associatedmessages are described in the IBM Tivoli Access Manager for e-business: Error MessageReference.

Table 15. Authentication status mapping

Status returned from module Status returned to browser

XAUTHN_S_COMPLETE error_status_ok

XAUTHN_S_FAILURE ivauthn_authentication_failure

XAUTHN_S_OUT_OF_MEMORY ivauthn_out_of_memory

XAUTHN_S_BAD_AUTHENTICATION_INFO ivauthn_bad_authentication_info

XAUTHN_S_INVALID_USERNAME ivauthn_invalid_username

XAUTHN_S_RETRY_LIMIT_REACHED ivauthn_retry_limit_reached

XAUTHN_S_PASSWORD_EXPIRED ivauthn_password_expired

XAUTHN_S_ACCOUNT_EXPIRED ivauthn_account_expired

XAUTHN_S_LOGIN_POLICY_VIOLATION ivauthn_login_policy_violation

XAUTHN_S_NEW_PIN ivauthn_new_pin

XAUTHN_S_ACCOUNT_DISABLED ivauthn_account_disabled

XAUTHN_S_NEXT_TOKEN ivauthn_next_token

XAUTHN_S_MAPPING_FAILED ivauthn_mapping_failed

XAUTHN_S_CERTIFICATE_AUTH_FAILURE ivauthn_certificate_auth_failure

XAUTHN_S_HTTP_HEADER_AUTH_FAILURE ivauthn_http_header_auth_failure

XAUTHN_S_IP_ADDR_AUTH_FAILED ivauthn_ip_addr_auth_failed

XAUTHN_S_SU_INVALID_USERNAME ivauthn_su_invalid_username

XAUTHN_S_SU_NO_PERMS ivauthn_su_no_perms

XAUTHN_S_PASSWD_POLICY_VIOLATION ivauthn_passwd_policy_violation

XAUTHN_S_PASSWD_TOO_SHORT ivauthn_passwd_too_short

XAUTHN_S_PASSWD_HAS_SPACES ivauthn_passwd_has_spaces

XAUTHN_S_PASSWD_TOO_MANY_REPEATED ivauthn_passwd_too_many_repeated

XAUTHN_S_PASSWD_TOO_FEW_ALPHAS ivauthn_passwd_too_few_alphas

Chapter 4. Writing custom authentication modules 33



Table 15. Authentication status mapping (continued)

Status returned from module Status returned to browser

XAUTHN_S_PASSWD_TOO_FEW_NONALPHAS ivauthn_passwd_too_few_nonalphas

XAUTHN_S_PASSWD_ACCT_LOCKEDOUT ivauthn_passwd_acct_lockedout

XAUTHN_S_POST_PWDCHG_FAILED ivauthn_post_pwdchg_failed

All other statuses are mapped to ivauthn_unknown_error.




Customizing user password change

This step is optional.

The xauthn_change_password() function allows the user to change the accountpassword that is stored in the third-party user registry. The user name andpassword, and token authentication methods support this function. If the custom

authentication module that you are going to implement does not support passwordchanges, this function must return:

XAUTHN_S_UNSUPPORTED_AUTHN_METHOD

User authentication information is passed to this interface in a name/value datalist (xnvlist_t ). The data list contains the user name, old password or passcode,the new password or PIN, and the authentication method.

The authentication information identifiers for user name and password, and tokenauthentication are described in “1. Obtaining user authentication information” onpage 32. This section describes the identifiers used by xauthn_change_password() .

See also the reference page:“xauthn_change_password() ” on page 64




Customizing password strength checking

The xauthn_change_password() function can be used to change a user password.

Alternatively, the xauthn_change_password() function can be used to implement apassword strength module without using the function to change a password.

The password strength module is specified by the passwd-strength stanza entry inthe [authentication-mechanisms] stanza of the WebSEAL configuration file. Forexample:

[authentication-mechanisms]passwd-strength = /opt/pdweb/example/libxauthn.so

When writing an authentication module for this task, the xauthn_initialize() andxauthn_shutdown() functions serve their normal purpose for the password strengthmodule. The xauthn_authenticate() function call can be stubbed out. Theauthentication method is passed to this interface among the user authenticationinformation. This enables the password strength module to pass policy based onthe type of method with which the user authenticated.

User authentication information is passed to this interface in a name/value datalist (xnvlist_t). The data list contains the user name, old password or passcode,the new password or PIN, and the authentication method.

When writing an authentication module to perform password strength checking,use the information returned in the xnvlist_t as input to your specific passwordchecking code. This could be a check to ensure that a token authentication is used.

The authentication information identifiers for each authentication method,including those specific to xauthn_change_password() are described in “1.Obtaining user authentication information” on page 32.

For more information, see the reference page for “xauthn_change_password() ” onpage 64.




Processing post password changes

Post password change processing is supported by both WebSEAL and the plug-infor Web Servers. This section refers to both of these components as the TivoliAccess Manager Web security resource manager.

The Web security resource manager provides support for customized post

password change processing. An authentication module can be written to be calledafter a password is successfully changed through the Web security resourcemanager by using the pkms password change page. This feature enablespasswords in external user registries, which might be unknown to Tivoli AccessManager, to be updated with passwords that the user changed while attemptingauthentication when challenged by the Web security resource manager.

When the password of a user is successfully changed, the Web security resourcemanager checks the authentication mechanism that is in use to see if passwordchange processing is enabled. When it is enabled, the Web security resourcemanager calls the module.

The post password change module is specified by the post-pwdchg-process stanzaentry in the [authentication-mechanisms] stanza of the WebSEAL configurationfile. For example:

[authentication-mechanisms]post-pwdchg-process = /opt/pdweb/lib/libcustom.so

The post password change module uses the external authentication C API. Theauthentication module for post password change processing must include:

v xauthn_initialize()

v xauthn_change_password()

The xauthn_change_password() function is called with an xnvlist_t structure as aninput parameter. The xnvlist_t contains the following data:

v Name of the user who needs the password to be changed

v Current password of the user

v New password of the user

The post password change processing module does not usexauthn_authenticate(). User authentication is done through the default TivoliAccess Manager authentication mechanism. The password change occurs afterauthentication is complete, and the post password change processing occurs afterthe user has supplied a new password.

The post password change processing module returns status to the Web securityresource manager. The Web security resource manager audits the return status but

does not act based on it. Any errors from the module are not returned to the client.The implementer of the authentication module must handle any error conditionsthat arise.




Adding extended attributes to the credential

The xauthn_authenticate() function allows you to add extended attribute data(business entitlements) to a user credential. These business entitlements can beused in any situation where this type of data is required. For example, entitlementdata can be extracted from the credential directly by an application using theAuthorization API or inserted in the HTTP headers of requests directed across a

junction to a back-end application server.

The Tivoli Access Manager authorization API provides a built-in entitlementsservice that you can use to place extended attributes into a user credential. Formost deployments, this service can provide all the functions necessary to modifyuser credentials to satisfy the security policy of the deployment. In these cases, youdo not need to write a customized authentication module. For more informationabout calling the built-in entitlements services, see the IBM Tivoli Access Manager

for e-business: Authorization C API Developer Reference. An example usage of thecredentials attribute entitlements service is provided in the Credential processing"chapter of the IBM Tivoli Access Manager for e-business: WebSEAL AdministrationGuide.

The structure of the returned client identity (xauthn_identity_t ) allows you tospecify extended attribute information. This additional information becomes part of the resulting Tivoli Access Manager credential. You define extended attributeinformation with the xattr_list_t data structure.

Extended attributes can be added in a custom authentication module (that replacesa built-in module), or added by a second authentication module that is chained to a

built-in or custom authentication module. The initial authentication module createsthe Tivoli Access Manager identity and can optionally (in the case of a customauthentication module) include extended attribute data. The second authenticationmodule in the chain is used only to add extended attribute data.

The secondary custom authentication module is specified by the cred-ext-attrsstanza entry in the [authentication-mechanisms] stanza of the WebSEALconfiguration file. For example (Solaris):

[authentication-mechanisms]cred-ext-attrs = /opt/pdweb/lib/libcustom.so

Add extended attributes to the credential at the time of authentication. Theextended attribute list can only be used to pass string values. Binary data cannot

be used.

Each name/value pair must be added to the identity using a call to thexattr_set() function and can be retrieved using the xattr_get() function.

In order for WebSEAL to recognize the extended attribute as tag/value data, thetag name is prefixed with the macro XAUTHN_TAG_VALUE_PREFIX, which isdefined as "tagvalue_".

The following section of the xauthn.c demonstration program illustrates thisaction:

char *tag = (char *) malloc(1024+XAUTHN_TAG_VALUE_KEY_PREFIX_LEN+1);char *tag_data = (char *) malloc(1024);

if (!XAUTHN_TAG_VALUE_KEY_PREFIX || !tag || !tag_data) (/* Error condition */

return;




)

/* Request the tag name */sprintf(tag, "%s", XAUTHN_TAG_VALUE_KEY_PREFIX);printf("Enter the test tag: ");fflush(stdout);scanf("%1024s", tag + strlen(XAUTHN_TAG_VALUE_KEY_PREFIX));

/* Request the tag data */

printf("Enter the test tag data: ");fflush(stdout);scanf("%1024s", tag_data);

/* Add the tag/value pair to the credential*/xattr_set(&ident->xattrs, tag, tag_data);

The following example illustrates a method of calling xattr_set to supplytag/value data (business entitlements) in a custom authentication module:

char *name = strdup("tagvalue_ldap_employee_number");char *value = strdup("12345678");

if (name && value) {xattr_set (&ident->xattrs,

name,

value);}else {

/* handle strdup failures here */}

name = strdup("tagvalue_ldap_employee_phone");value = strdup("888-888-8888");if (name && value) {

xattr_set (&ident->xattrs,name,value);

}else {

/* handle strdup failures here */

}




Modifying the user name in a credential

The Tivoli Access Manager external authentication interface allows you to modifythe user name provided by another authentication module. For example, if aprevious authentication module authenticates the user against a different userregistry than the Tivoli Access Manager user registry, a custom module can beused to change the user ID to the Tivoli Access Manager user ID.

When modifying the user identity returned by a previous authentication, theauthor of the custom module must observe the following conditions:

v The old user identity must be deallocated by the custom module.

v The new user identity must be allocated by the custom module using standardC library allocation functions.

v The format of the old user identity depends on the previous authenticationmodule in the chain. Some authentication modules return distinguished names;other modules return user identities in their short forms.

The following example code demonstrates appending "@domain.com" to theidentity returned by the previous authentication module. This code assumes that

the Tivoli Access Manager registry is an LDAP server and that the previousauthentication module returned a user identity and not a distinguished name(DN).

Note: The code for Active Directory or Domino user registries usesident->prin.data.uraf_name instead of ident->prin.data.dn.

xauthn_status_txauthn_authenticate(

xnvlist_t *authnInfo,xauthn_identity_t *ident)

{char *oldprin = NULL;char *newprin = NULL;

/* Validate the provided identity */if (authnInfo == NULL || ident == NULL) {

printf("Invalid previous authentication\n");return XAUTHN_S_AUTHENTICATION_FAILURE;

}oldprin = ident->prin.data.dn;if (oldprin == NULL) {

printf("Invalid previous authentication\n");return XAUTHN_S_AUTHENTICATION_FAILURE;

}

/* Create the new identity */newprin = (char*)malloc(strlen(oldprin)+strlen("@domain.com")+1);if (newprin == NULL) {

printf("Allocation failure\n");return XAUTHN_S_OUT_OF_MEMORY;

}sprintf(newprin, "%[email protected]", oldprin);

/* Release the old identity and return the new one */free(oldprin);ident->prin.data.dn = newprin;return XAUTHN_S_COMPLETE;

}




A custom authentication module, used to modify the user identity returned by aprevious authentication, is specified by the cred-ext-attrs stanza entry in the[authentication-mechanisms] stanza of the WebSEAL configuration file. Forexample (Solaris):

[authentication-mechanisms]cred-ext-attrs = /opt/pdweb/lib/libcustom.so







Chapter 5. Single signon customization

This chapter describes how to customize cross-domain single signon authenticationand e-community single signon authentication.

Topic Index:

v “WebSEAL single signon concepts” on page 44

v “Customizing token create and consume modules” on page 47

v “Customizing identity mapping and attribute handling” on page 50

v “Example: Cross-domain single signon with a non-WebSEAL server” on page 54




WebSEAL single signon concepts

Tivoli Access Manager Web security resource managers support cross-domainsingle signon and e-community single signon solutions. Both single signonsolutions employ authentication tokens that describe or "vouch for" the useridentity to the destination server. The construction of these tokens by the initialserver is called "token creation." The decoding and use of the token by the

destination server is called "token consumption."

To integrate non-WebSEAL servers into cross-domain single signon ande-community single signon environments, you can write custom modules that cancreate and consume tokens. You can also customize the cross domain mappingframework to enhance cross-domain single signon and e-community single signonenvironments using all WebSEAL servers.

The following sections explain how token creation and consumption occurs for thedefault cross-domain single signon and e-community single signon functionality

between two WebSEAL servers. The same concepts apply to the plug-in for WebServers.

Default token creation for cross-domain single signonCross-domain single signon token creation occurs when an authenticated user onwebsealA requests a resource from websealB. The request is made through aspecial management page called pkmscdsso that triggers the token create module(ssocreate). The request also contains the destination URL where the resource islocated.

The following example illustrates the construction of this special link to the remoteresource:

http://websealA.ibm.com/pkmscdsso?http://websealB/resource.html

The built-in token create module encodes the existing credential information of theauthenticated user and includes the information as a query string argument in theredirect response for the resource on websealB, using the destination URL suppliedin the original request.

The cdsso-argument stanza entry in the [cdsso] stanza of the WebSEALconfiguration file tells the default token create module what name to use as a labelfor the encoded token information in the query string argument (default label isPD-ID). It is this unique label that triggers the token consume module onwebsealB.

The following example illustrates the format of a redirect response:

http://websealB/resource.html?PD-ID=encoded_authentication_token

You can create your own custom token create module that formats and encodes thearguments included in the redirect response. The custom module can alter theformat and content of the redirect response to accommodate the consumptionrequirements of another WebSEAL server or a non-WebSEAL server.

Default token creation for e-community single signonThe "vouch for" request in e-community single signon is triggered when a userrequests a resource from a target server configured for e-community that containsno credential information for that user. The server sends a redirect to the "vouch




for" server for the pkmsvouchfor management page. The "vouch for" server iseither the master authentication server or a delegated "vouch for" server identifiedin an e-community cookie.

The pkmsvouchfor management page triggers the token create module(ssocreate). The request also contains the destination URL where the resource islocated.

Example request sent to the "vouch for" server:

http://MAS.ibm.com/pkmsvouchfor?e-community-name&http://websealB/resource.html

The master authentication server authenticates the user (if necessary). The built-intoken create module encodes the credential information of the authenticated userand includes the information as a query string argument in the redirect responsefor the resource on websealB , using the destination URL supplied in the originalrequest.

The vf-argument stanza entry in the [e-community-sso] stanza of the WebSEALconfiguration file tells the default token create module what name to use as a labelfor the encoded token information in the query string argument (default label isPD-VF). It is this unique label that triggers the token consume module on websealB .

The following example illustrates the format of a redirect response:

http://websealB/resource.html?PD-VF=encoded_authentication_token

You can create your own custom token create module that formats and encodes thearguments included in the redirect response. The custom module can alter theformat and content of the redirect response to accommodate the consumptionrequirements of another WebSEAL server or a non-WebSEAL server.

Default token consumption for cross-domain single signonCross-domain single signon token consumption occurs when the websealB serverreceives a request containing a query string argument specified by thecdsso-argument stanza entry in the [cdsso] stanza of the WebSEAL configurationfile. The triggering string ("PD-ID" in this example) is also defined for websealB bythe cdsso-argument stanza entry.

The built-in token consume module (ssoconsume) decodes the query stringcontaining the token and reveals the identity information of the user. The websealBserver can use this information to authenticate the user and serve the request.

You can create your own token consume module that handles the incoming querystring information. The custom module can be written to correctly decode a tokencreated from the custom requirements of a non-WebSEAL server.

Default token consumption for e-community single signonE-community single signon token consumption occurs when the websealB serverreceives a request containing a query string argument with a name specified by thevf-argument stanza entry in the [e-community-sso] stanza of the WebSEALconfiguration file. The triggering string ("PD-VF" in this example) is also definedfor websealB by the vf-argument stanza entry.

The built-in token consume module (ssoconsume) decodes the query stringcontaining the token and reveals the identity information of the user. The websealBserver can use this information to authenticate the user and serve the request.

Chapter 5. Single signon customization 45



You can create your own token consume module that handles the incoming querystring information. The custom module can be written to correctly decode a tokencreated from the custom requirements of another WebSEAL server or anon-WebSEAL server.




Customizing token create and consume modules

You can create custom token create/consume modules by modifying the examplexauthn.c source file included with the external authentication C API. The xauthn.csource file is located in the example subdirectory of the main ADK directory(pdxauthn_adk).

This section contains the following topics:v “Built-in token create and consume modules” on page 47

v “Example token create and consume modules” on page 47

v “The token create module interface” on page 48

v “The token consume module interface” on page 49

Built-in token create and consume modulesToken create and token consume functionality can be contained in one module, orseparated into two individual modules. WebSEAL and the Plug-in for Web Serversuses two distinct built-in modules to handle the token creation and tokenconsumption tasks:

Table 16. Built-in token creation and consumption modules

Operating system Module

Solaris, Linux libssocreate.solibssoconsume.so

AIX libssocreate.alibssoconsume.a

Windows ssocreate.dllssoconsume.dll

HP-UX libssocreate.sllibssoconsume.sl

Example token create and consume modulesThe Web Security ADK provides a pre-built platform-specific sample module thatdemonstrates single signon functionality like the functionality provided by the

built-in default modules. The sample module performs both token creation andtoken consumption tasks and was built from the xauthn.c source file. You use thexauthn.c source file as the starting point for building your own custom module.

In addition, the example module provides output data during the token creationand consumption processing when you use the module in a test environment. Thisoutput is sent by default to the Web server log file. For WebSEAL, the log file ismsg_webseald.log. The output can be useful for analyzing the proper functionalityof the module.

The example module is located in the example sub-directory of the main WebSecurity ADK directory (pdxauthn_adk) and has the following platform-specific filename:

Table 17. Example single signon module


Solaris, Linux libxauthn.so

AIX libxauthn.a




Table 17. Example single signon module (continued)


Windows xauthn.dll

HP-UX libxauthn.sl

Since both the create and consume functionality are contained within the samemodule file, you must specify the full path name to this module for both thesso-create and sso-consume stanza entries in the [authentication-mechanisms]stanza of the Web server configuration file. For example, on Solaris:

[authentication-mechanisms]sso-create = /opt/pdwebrte/pdxauthn_adk/example/libxauthn.sosso-consume = /opt/pdwebrte/pdxauthn_adk/example/libxauthn.so

The token create module interfaceThe Web security resource manager passes client authentication information to thetoken create module. The information is passed using a name/value list format,where the name is an identifier that specifies the value type.

The information is stored in the xnvlist_t data type. Values can be accessed byusing the utility function xnvlist_get() . For more information about retrievingvalues from xnvlist_t , see the reference page for xnvlist_get() .

The token create module typically generates a redirect response containing thedestination URL of the resource and the encoded credential of the user. A customtoken create module can generate a customized version of this redirect. Specificuser authentication data from the Web security resource manager, provided as anxnvlist_t data structure, is passed to the token creation interface. For details onthese identifiers, see “Token create identifiers” on page 94.

The XAUTHN_SSO_TYPE identifier is set to SSO_CREATE_TYPE. The

XAUTHN_INPUT_URL identifier is set to the destination URL where the resourceis located.

For example, if websealA was sent the following request:

http://websealA.ibm.com/pkmscdsso?http://websealB.ibm.com/resource.html

The value of the XAUTHN_INPUT_URL identifier would be

http://websealB.ibm.com/resource.html

For descriptions of the other authentication data types, see “1. Obtaining userauthentication information” on page 32.

A custom module using the xauthn interface for token create or consumefunctionality returns a client identity back to the Web security resource managerusing the xauthn_identity_t identity structure. However, the actual requirement of a token create module is to return a redirect response string (URL).

This string can be passed back to WebSEAL by storing the redirect URL string inthe xattr_list_t data structure of the identity structure. The information providedto xattr_list_t can be set using the xattr_set() utility.




You must set an attribute using the name cdsso-redirect-url with the redirect stringas its value. The identity structure is then passed to WebSEAL and the redirectresponse is sent using the URL string provided as the value to thecdsso-redirect-url attribute.

The value for the cdsso-redirect-url attribute appears like the following example:

http://websealB.ibm.com/resource.html?TOKEN=encoded_authentication_data

The above redirect URL string is constructed using the destination URL from thepkmscdsso request, plus the user credential information passed in from thexauthn_existing_cred authentication identifier created for the authenticated user

by the original Web security resource manager.

The token consume module interfaceThe label identifying the encoded token argument string (configured in thecdsso-argument or vf-argument stanza entries) allows the receiving server torecognize the incoming request as a request with an authentication token and toinvoke the token consume module. The token consume module is passed specificuser authentication data, provided as an xnvlist_t data structure. For details on

these identifiers, see “Token consume identifiers” on page 95.

The XAUTHN_SSO_TYPE identifier is set to SSO_CONSUME_TYPE. TheXAUTHN_QUERY_STRING identifier is set to the query string of the redirectedrequest containing encoded authentication data.

For example, if websealA was sent the following request:

http://websealB.ibm.com/resource.html?TOKEN=encoded-data

then the value of the XAUTHN_QUERY_STRING identifier would be

?TOKEN=encoded_data

The token consume module returns a client identity using the xauthn_identity_tstructure. The Web security resource manager can use this identity information toauthenticate the user and continue processing the request.




Customizing identity mapping and attribute handling


v “Cross-domain mapping framework overview” on page 50

v “Software requirements for the cross-domain mapping framework API” on page51

v“Build instructions for the cross-domain mapping framework API” on page 51

v “Customizing the example source file” on page 51

v “Providing user attributes: cdmf_get_usr_attributes()” on page 52

v “Providing identity mapping: cdmf_map_usr()” on page 52

Cross-domain mapping framework overviewThe cross-domain mapping framework API is a programming interface you canuse to build custom modules that enhance the built-in token create and consumemodules. Enhancements to the built-in modules include providing user identitymapping services and transferring extended user attributes.

For example, in many cross-domain single signon scenarios, the default one-to-onemapping between users from different domains might not suit all deploymentrequirements. The cross-domain mapping framework allows the mapping of aremote user to a local user identity.

In an e-community environment, individual domains manage their own useridentities and associated privileges. You can use the cross-domain mappingframework to map a user from a remote domain to a valid user in the localdomain. If the e-community domains share global identities, this mapping functionis not necessary.

The specific operation of a customized cross-domain mapping framework moduleis determined by the developer. Use the cross-domain mapping framework API

functions and utilities to implement the necessary cross domain identity mappingand extended user attribute handling.

Two cross-domain mapping framework modules always work as partners. Onemodule—associated with the initial Web Security resource manager—suppliesextended attributes in the authentication token during the token creationprocessing.

The second module, written as a partner to the first and located on the destinationserver, performs the following operations:

v Expects possible extended attributes.

v Maps the remote user identity to a local user identity.

The custom cross-domain mapping framework module must contain twoapplication programming interfaces. The first interface, called by the token creationmodule, provides extended user attribute information for inclusion in the token.

The second interface is called by the token consumption module and provides useridentity mapping services.




Software requirements for the cross-domain mappingframework API

There are no software dependencies when building the cross-domain mappingframework module.

To use a cross-domain mapping framework module, you must have at least two

Tivoli Access Manager secure domains installed, each containing a Web securityresource manager. The cross-domain mapping framework modules are called bythe built-in token create and token consume modules.

Custom token create and consume modules can be written to provide user identitymapping and attribute handling, and therefore would not require calling a separatecross-domain mapping framework module.

Build instructions for the cross-domain mapping framework API

Windows-specific macros

The following two macros are required when building the module on a Windowsplatform. The macros should not be redefined or changed.

v CDMF_DECLSPEC()

v CDMF_CALLTYPE()

Customizing the example source file1. Edit the cdmf.c.skeleton source file and modify the cdmf_map_usr() and

cdmf_get_usr_attributes() functions to enable the required user mapping anduser attribute handling.

2. Rename the modified cdmf.c.skeleton file to cdmf.c.

3. For UNIX and Linux platforms, edit Makefile.cdmf.in and modify as required

to build the module for the appropriate development platform. Instructions areincluded in the comments at the top of the file.

For Windows platforms, Makefile.win32 requires no modification.

4. Build the custom cross-domain mapping framework module. Provide thefollowing platform-specific name for the module:

Table 18. Cross-domain mapping framework module name

Operating system Module name

Solaris, Linux libcdmf.so

AIX libcdmf.a

HP-UX libcdmf.sl

Windows cdmf.dll

Note: If you build the cross-domain mapping framework module on a Solarissystem using C++ and Sun Workshop 5 or greater, the module must be

built with the "–compat=4" flag.

5. Stop the server process (webseald or pdwebpi).

6. Replace the original cross-domain mapping framework module that wasincluded with the Tivoli Access Manager product with the customized version.

7. Start webseald or pdwebpi server process.




Providing user attributes: cdmf_get_usr_attributes()The cdmf_get_usr_attributes() function allows extended user attributes to beincluded in the cfross-domain single signon authentication token or thee-community "vouch for" token. The cdmf_get_usr_attributes() function is called

by the token creation module (ssocreate).

The input parameter to this function is the short name of the user on the local Websecurity resource manager.

The output parameter is the attribute list constructed by the cross-domain mappingframework utility functions. The token create module incorporates these attributesin the token it creates.

The cross-domain mapping framework module at the remote WebSEAL or Plug-infor Web Servers server can use the information contained in this attribute list whenproducing a user identity.

Providing identity mapping: cdmf_map_usr()The cdmf_map_usr() function is called by WebSEAL or the Plug-in for Web Serversto perform the mapping from the remote user to a local user identity. Thecdmf_map_usr() function can be used when the local and remote servers usedifferent user registries. For example:

v When a cross-domain single signon request originating in domain A is received by the domain B Web security resource manager, the identity of the local usermust be determined. The cdmf_map_usr() function is called to map the remoteuser (who initiated the single signon request) to a local user identity.

v When a request with a "vouch for" token is received by a WebSEAL or Plug-infor Web Servers server (which is the target of the request) from a masterauthentication server, that WebSEAL or Plug-in for Web Servers server might berequired to map the identity of the requesting user to a local user identity.

The input parameter to this function is the cdsso_usr_info_t data type, whichcontains the user name, domain, and an attribute list. This input information isused by the custom cross-domain mapping framework module to determine a localuser identity. Any information contained in the attribute list was added by thecdmf_get_usr_attributes function call to the first cross-domain mappingframework module.

The output information is also contained in a cdsso_usr_info_t data type. Theonly required field is the user name, which is the short name of the local (orrequesting) user. The local user attribute list is an optional field that can be filledout if the user credential requires extended attributes.

Because the extended attribute list of the credential supports only one value, only

the first value for each attribute becomes a part of the user credential. The domainfield is ignored.

Specifying extended attributesBoth cross-domain mapping framework application programming interfacessupport additional user information in the form of a cross-domain single signonattribute list.




Although this type is called a cross-domain single signon attribute list, this list can be used by the cross-domain mapping framework functions to communicate userinformation in both cross-domain single signon and e-community scenarios.

The cross-domain single signon attribute list cdsso_attrlist_t is a name andmultiple value data list that is defined in cdssotypes.h.

The utility functions that are required to construct this list are defined in the filecdmf_utils.h.

These utility functions perform the following operations:

v Create a cross-domain single signon user attribute list

v Create a cross-domain single signon user attribute

v Add a value to a cross-domain single signon user attribute

v Add a cross-domain single signon user attribute to the user attribute list

For detailed information, consult the following reference pages:

v cdmf_create_usr_attr_list()

v

cdmf_create_usr_attr()v cdmf_add_value_to_attr()

v cdmf_add_attr_to_list()




Example: Cross-domain single signon with a non-WebSEAL server

Sending cross-domain single signon requests to anon-WebSEAL server

Cross-domain single signon is a functionality that provides a single signon solution

between two Tivoli Access Manager Web security resource managers. This sectiondescribes how to set up a Tivoli Access Manager Web security resource manager tosend a single signon request to a non-Tivoli Access Manager destination server.

1. Create a custom token create module based on the xauthn.c example sourcefile.

This code must be written to generate redirect requests in a format acceptable by the destination server.

2. In the server configuration file, set the sso-create authentication mechanismparameter to the full path name of the token create module. For example, onSolaris:

[authentication-mechanisms]sso-create = /opt/pdwebrte/lib/libxauthn.so

Specify a full path name to this module.3. Enable the Web security resource manager to generate single signon requests by

communication type:

WebSEAL:

[cdsso]cdsso-create = {http | https | both}

Plug-in for Web Servers:

[common-modules]pre-authzn = cdsso

4. Create a special link on the appropriate page of this server that requests thesingle signon to the server and activates the token create module. For example,for WebSEAL:

http://webseal.ibm.com/pkmscdsso?https://non-webseal.example.com/resource.html

If the customized module fails for some reason, an xnvlist attribute should beallocated with the specified return value name (see the sample code), but with anull value. For example, WebSEAL can then serve a WebSEAL "Not Found" errorpage to the browser.

When the cross-domain single signon link is activated by an authenticated user, thetoken create module constructs a redirect request made up of the destination URLand encoded identity information describing the user. The format and contents of the redirected request URL, constructed by the custom module, must becompatible with how the destination server is configured to accept and read thisrequest.

Accepting cross-domain single signon requests from anon-WebSEAL server

This section describes how to set up a Tivoli Access Manager Web securityresource manager to accept a single signon request from a Web Security resourcemanager on a non-Tivoli Access Manager server.

1. Create a custom token consume module based on the xauthn.c example sourcefile.




This code must be written to successfully parse and decode requests in aformat created by the server that is not protected by a Tivoli Access Managerresource manager.

2. In the Tivoli Access Manager Web server configuration file, set the sso-consumeauthentication mechanism parameter to the full path name of the token createmodule file. For example, on Solaris:

[authentication-mechanisms]sso-consume = /opt/pdwebrte/lib/libxauthn.so

You must specify a full path name to this module.

3. Enable the Web security resource manager to process single signon requests bycommunication type:

WebSEAL:

[cdsso]cdsso-auth = {http | https | both}

Plug-in for Web Servers:

[common-modules]authentication = cdsso

4. Set the cdsso-argument label to the appropriate value that matches what the

server that is not protected by Tivoli Access Manager sends in its request andthat uniquely identifies the request as a single signon request to be handled bythe Tivoli Access Manager Web security resource manager cross-domain singlesignon functionality:

[cdsso]cdsso-argument = token_argument_ID

The Web security resource manager receives the redirect request URL from theserver that is not protected by a Tivoli Access Manager resource manager. Thetoken_argument_ID label informs the Web security resource manager is across-domain single signon request.

The token consume module is called. The module parses and decodes the query

string of the request. The resulting user identity is passed to the Web securityresource manager which uses it to authenticate the user and continue processingthe request.

The custom module must be written to understand the format and contents of thequery string constructed by the server that is external to the Tivoli Access ManagerWeb security resource manager.

If authentication is not successful, the Tivoli Access Manager Web security resourcemanager presents the user with a login prompt.







Appendix A. External authentication C API referenceNotes:

1. The following index is organized by function and data structure categories. The

reference pages are organized alphabetically.2. The External Authentication C API contains certain internal functions that are

not intended for use by customers. These functions are not supported and may be deprecated. Such functions are wrapped in #if defined C preprocessordirectives to prevent their accidental use.

v Functions in the xnvlist.h file wrapped with

#if defined (XNVLIST_PRIVATE)

are not supported.

v Functions in the xattr.h file wrapped with

#if defined (XATTR_DEPRECATED)

are not supported and might be removed in the future releases.

Data structures:

v “xattr_list_item_t ” on page 59

v “xattr_list_t ” on page 60

v “xauthn_identity_t ” on page 65

v “xnvlist_item_t ” on page 70

v “xnvlist_t ” on page 71

External authentication C API functions:

v “xauthn_authenticate() ” on page 63

v “xauthn_change_password() ” on page 64v “xauthn_initialize() ” on page 66

v “xauthn_shutdown() ” on page 67

v “xauthn_utils_append_extcred_tags()” on page 62

Utility API functions:

v “xattr_get() ” on page 58

v “xattr_set() ” on page 61

v “xauthn_util_entry_to_creds() ” on page 68

v “xnvlist_get() ” on page 69




xattr_get()

Retrieves the value of a given name in the extended attribute list.

Syntaxintxattr_get(

xattr_list_t *list,char *name,char **value

);

DescriptionRetrieves the value of a given name in the extended attribute list.

ParametersInput

list

A pointer to the name and value list.name

A pointer to a name of the attribute to retrieve.

Output

valueA pointer to a pointer that stores the value of a given name. The caller of thisfunction must not free the value returned.

Return ValuesThis function returns 0 upon success. Otherwise, it returns 1.




xattr_list_item_t

Holds a single extended attribute.

Definitiontypedef struct {

char *name;char *value;} xattr_list_item_t;

Values

nameA string representing the name of the extended attribute.

valueA string representing the value of the extended attribute.

Appendix A. External authentication C API reference 59



xattr_list_t

Lists extended attributes to be added to the credential.


long length;xattr_list_item_t *items;} xattr_list_t;

Values

lengthThe number of elements in the list.

itemsAn array of xttr_list_item_t structures.




xattr_set()

Stores a name and a value into the extended attribute list.

Syntaxintxattr_set(

xattr_list_t *list,char *name,char *value

);

DescriptionStores a name and a value into the extended attribute list.

The caller does not need to free name or value. These are released when theattribute list is freed.

Parameters

Input

listA pointer to the name and value list.

nameA pointer to a name. The name must be dynamically allocated using malloc().

valueA pointer to a value of the given name. The value must be dynamicallyallocated using malloc().

Return ValuesThis function returns 0 upon success. Otherwise, it returns 1.




xauthn_utils_append_extcred_tags()

Appends the extended credential attributes specified in the ldap-ext-cred-tags-41stanza within the pd.conf file.

Syntax

xauthn_utils_append_extcred_tags(const char *user,xattr_list_t *xattrs,xauthn_status_t *st);

ParametersInput

userA pointer to the user name or the Distinguished Name (DN) of the LDAPobject that contains the client information.

Output

xattrsThe extended attributes list to be added to.

st

XAUTHN error status.

Return ValuesUpon success, this routine returns with *st set to XAUTHN_S_COMPLETE. Uponfailure, *st is set to an XAUTHN error status indicating the nature of the failure




xauthn_authenticate()

Performs the authentication module authentication tasks.

Syntaxxauthn_status_txauthn_authenticate(

xnvlist_t *authnInfo,xauthn_identity_t *ident

);

DescriptionThe authentication dispatcher calls this interface to perform the customer-specificexternal authentication. Client authentication information is passed by thedispatcher through the input argument authnInfo.

Refer to “1. Obtaining user authentication information” on page 32 for the list of authentication data that authnInfo can contain.

Based on the authentication information, this function implements the specificauthentication mechanism and stores the resulting client information in ident. Thisinformation is then returned to WebSEAL.

It is important to note that the client identity ident can contain additional userinformation.

WebSEAL frees ident. The implementer of this function must not free ident.

ParametersInput

authnInfo

The authnInfo parameter is a name and value data list containing clientauthentication information.

Input/Output

identThe ident parameter contains the authenticated user information.

Return ValuesIf successful, the function returns XAUTHN_S_COMPLETE. Other possible error codescan be found in the pdxauthn.h header file.




xauthn_change_password()

Performs one of two tasks. Either performs the password change, or deliverspassword information as a password strength module.

Syntax

xauthn_status_txauthn_change_password(xnvlist_t *authnInfo

);

DescriptionThe authentication dispatcher calls this interface to implement a custom passwordchange mechanism. This interface is supported only for username/password andtoken authentication mechanisms. Client password change information is passed

by the dispatcher through the input argument authnInfo.

Alternatively, a module implementing this interface can provide a passwordstrength operation. Instead of actually updating a client password,

xauthn_change_password() verifies whether the new password of the client satisfiesthe custom conditions of the module. The same password change information isincluded in authnInfo for both uses of the interface.

Refer to “1. Obtaining user authentication information” on page 32 for the list of authentication data that authnInfo can contain.

ParametersInput

authnInfoThe authnInfo parameter is a name and value data list containing clientauthentication information.

Return ValuesIf successful, the function returns XAUTHN_S_COMPLETE.

XAUTHN_S_UNSUPPORTED_AUTHN_METHOD is returned if the external authenticationprocess does not support password changes. Other possible error codes can befound in the pdxauthn.h header file.

When xauthn_change_password() is used as a password-strength mechanism, itreturns XAUTHN_S_COMPLETE when the new password satisfies the custom policies.Any other return code means the strength check failed. Strength policy-specificerror codes are available in the pdxauthn.h header file to provide the client with

useful messages.




xauthn_identity_t

Holds information about a user Tivoli Access Manager identity.


struct {unsigned32 prin_type;union {

/* case(s): 0 */char *name;/* case(s): 1 */char *dn;/* case(s): 2 */char *uraf_name;

} data;} prin;char *user_info;char *authnmech_info;

xattr_list_t xattrs;} xauthn_identity_t;

Values

prin_typeThe prin_type indicates the user registry used to generate a credential from theidentity. The only valid value is XAUTHN_PRIN_TYPE_DN (LDAP user registry),where the prin.data.dn contains the distinguished name (DN) of the user.

nameNot valid.

dn The LDAP Distinguished Name (DN) of the user or the LDAP user name.

uraf_nameNot valid.

user_infoInformation added to the credential as an extended attribute calledazn_cred_user_info.

authnmech_infoAuthentication method information. Added to the credential as an extendedattribute called azn_cred_mech_id.

xattrsThe xattr_list_t data structure can be used to return any extended userattributes.




xauthn_initialize()

Initializes the specified authentication module.

Syntaxxauthn_status_txauthn_initialize(

int argc,const char **argv

);

DescriptionUse this initialization function to initialize an authentication module. The inputparameters argc and argv are built from parameters specified in the[authentication-mechanisms] stanza of the secure Web server configuration file.The following example definition uses the sample module:

passwd-ldap = libxauthn.so& -dbms sys.db

In the preceding example, xauthn_initialize() is called with an argc value of 2.

The argv array contains the following values:argv[0] = "-dbms"argv[1] = "sys.db"

Input parameters should not be modified.

WebSEAL frees the contents of argc and argv. Therefore, the implementer of thisfunction should not free either of these parameters.

ParametersInput

argc

The number of arguments contained in the argv array.

argvThe string arguments passed in the service definition for this service instance.





xauthn_shutdown()

Shuts down the specified authentication module.

Note: The shutdown interface is not functional. You can successfully implementand use the external authentication interface without this function.

Syntaxxauthn_status_txauthn_shutdown(

int argc,const char **argv

);

DescriptionDuring the normal shutdown, the WebSEAL authentication dispatcher calls thisinterface to perform any shut down processes that might be required by thecustom environment. The input parameters argc and argv are built from theparameters specified in the [authentication-mechanisms] stanza of the secure Web

server configuration file. The following example definition uses the samplemodule:

passwd-ldap = libxauthn.so& -dbms sys.db

In the preceding example, xauthn_shutdown() is called with an argc value of 2. Theargv array contains the following values:

argv[0] = "-dbms"argv[1] = "sys.db"

Input parameters should not be modified.

Parameters

Inputargc

The number of arguments contained in the argv array.

argvThe string arguments passed in the service definition for this service instance.





xauthn_util_entry_to_creds()

Converts a value from an xnvlist_t into a credential.

Syntaxazn_creds_h_txauthn_util_entry_to_creds(

const char *value,int vlen

);

DescriptionSome entries in the xnvlist_t authentication data structure passed intoxauthn_authenticate() and xauthn_change_password() are actually encodedcredentials. This function converts the encoded credential into an azn_creds_h_tthat can then be manipulated using the functions defined by the Tivoli AccessManager authorization API.

The caller does not need to free the returned azn_creds_h_t.

ParametersInput

valueThe value retrieved by the call to xnvlist_get() for the entry that contains thecredential.

vlenThe length returned by the call to xnvlist_get() for the entry that contains thecredential.

Return Values

The function returns a valid credential if it is successful, or AZN_C_INVALID_HANDLEif an error occurs.






xnvlist_item_t

Holds a single item of authentication data.


char *name;char *value;int vlen;

} xnvlist_item_t;

Values

nameA string representing the name of the item. Valid names are described in “1.Obtaining user authentication information” on page 32.

valueAn array of bytes representing the value of the item. The authentication datacan be a character string or can be binary data.

vlenAn integer value representing the length of the value array.

DescriptionThe authentication data can be a character string or can be binary data.




xnvlist_t

Holds a list of xnvlist_item_t authentication data structures.


long length;xnvlist_item_t *items;} xnvlist_t;

Values

lengthThe number of elements in the "items" array.

itemsAn array of xnvlist_item_t.







Appendix B. Cross-domain mapping framework C APIreference

Note: The following index is organized by function and data structure categories.

The reference pages are organized alphabetically.

Utility API functions:

v “cdmf_add_attr_to_list() ” on page 74

v “cdmf_add_value_to_attr() ” on page 75

v “cdmf_create_usr_attr() ” on page 76

v “cdmf_create_usr_attr_list() ” on page 77

Cross-domain mapping framework API functions:

v “cdmf_get_usr_attributes() ” on page 78

v “cdmf_map_usr() ” on page 79

Memory management macros:

v “CDSSO_FREE() ” on page 81

v “CDSSO_MALLOC() ” on page 82

v “CDSSO_REALLOC() ” on page 83

v “CDSSO_STRDUP() ” on page 84




cdmf_add_attr_to_list()

Adds the specified user attribute to the specified user attribute list.

Syntaxintcdmf_add_attr_to_list(

cdsso_usr_attr_t *new_attr,cdsso_attrlist_t *list

);

DescriptionAdds the specified user attribute to the specified user attribute list.

The new attribute is added to an existing list. The caller is responsible for freeingmemory used by the attribute list. The new attribute is part of the attribute list,and therefore the memory for it is freed when the attribute list is freed.

ParametersInput

new_attr

New attribute to be added to the list.

Output

listUpdated list.

Return ValuesIf successful, the function returns TRUE.

Otherwise, the function returns FALSE.




cdmf_add_value_to_attr()

Adds a new value to a user attribute.

Syntaxintcdmf_add_value_to_attr(

char *new_value,cdsso_usr_attr_t *attr

);

DescriptionAdds a new value to a user attribute. A copy of the value is made. This functioncan be called many times to add multiple values to a user attribute.

The caller is responsible for freeing the memory used by the new value.

ParametersInput

new_value

New value to be added to the attribute.

Output

attrUpdated user attribute object.

Return ValuesIf successful, the function returns TRUE.

Otherwise, the function returns FALSE.

Appendix B. Cross-domain mapping framework C API reference 75



cdmf_create_usr_attr()

Creates a new user attribute.

Syntaxcdsso_usr_attr_t *cdmf_create_usr_attr(

char *attr_name);

DescriptionCreate a new user attribute. A copy is made of the name.

The caller is responsible for freeing the memory used by the new attribute.

ParametersInput

attr_name

Name of the new attribute.

Return ValuesIf successful, the function returns a pointer to the newly allocated attribute.

Otherwise, the function returns NULL.




cdmf_create_usr_attr_list()

Creates an empty attribute list.

Syntaxcdsso_attrlist_t *cdmf_create_usr_attr_list(

void);

DescriptionCreates an empty attribute list.

The caller is responsible for freeing the memory used by the list.

ParametersNone.

Return ValuesIf successful, the function returns a pointer to the newly allocated list.

Otherwise, the function returns NULL.




cdmf_get_usr_attributes()

Retrieves the extended attributes for the specified user.

Syntaxintcdmf_get_usr_attributes(

char *usr,cdsso_attrlist_t **attr_list

);

DescriptionWebSEAL and plug-in for Web Servers call this interface:

v When a cross-domain single signon request is initiated by a user accessing the/pkmscdsso page on the local WebSEAL or plug-in for Web Servers server.

v When an e-community "vouch for" server generates a "vouch for" reply token foranother WebSEAL or plug-in for Web Servers server in the e-community.

In a cross-domain single signon operation, the extended attribute list returned by

this function is sent to the remote WebSEAL or plug-in for Web Servers server (thetarget of the request) inside the authentication token.

In an e-community "vouch for" operation, the attribute list returned by thisfunction is sent to the remote WebSEAL or plug-in for Web Servers server (thetarget of the request) inside the "vouch for" reply token.

The remote WebSEAL or plug-in for Web Servers server can use these extendedattributes to help in the user mapping.

The attribute list must be constructed using the functions defined in cdmf_utils.h.

If no attributes are being set, this function sets attr_list to NULL.

Note: WebSEAL or plug-in for Web Servers frees the memory allocated by thisfunction. The implementer of the function should not free the pointer**attr_list.

ParametersInput

usrUser name.

Output

attr_listExtended attributes for input user.

Return ValuesIf successful, the function returns CDMF_SUCCESS.

Upon failure, the function returns CDMF_FAILURE.




cdmf_map_usr()

Maps a remote user into a local user.

Syntaxintcdmf_map_usr(

cdsso_user_info_t *remote_usr,cdsso_user_info_t *local_usr

);

DescriptionThe WebSEAL or plug-in for Web Servers cross-domain single signon tokenauthentication (consumption) mechanism calls this interface to determine theidentity of the local user during a cross-domain single signon authentication or ane-community "vouch for" operation.

The remote user information is received in a cdsso_usr_info_t structure. Thisinformation includes the remote user name, the remote domain name, and possibly

an extended attribute list. This information should be used to determine theidentity of the local user.

If the identity of the local user is successfully determined, then CDMF_SUCCESSshould be returned. The local user information is returned in a cdsso_usr_info_tstructure. The local user information that can be returned in this structure consistsof the local user name and possibly an extended attribute list.

If an attribute list is to be returned, then the functions defined in cdmf_utils.h isused to construct the list. Information from this attribute list is included in theTivoli Access Manager credential for that client.

When cdmf_map_user() successfully returns the identity of the user, the function

returns CDMF_SUCCESS. In this case, the implementer of cdmf_map_user() shouldnot free the memory for the cdsso_user_into_t structure local_usr. This structure isfreed by WebSEAL.

If cdmf_map_user() fails, CDMF_FAILURE is returned. If the function completes, butis not able to determine the identity of the local user, CDMF_NOMAP is returned.

When either CDMF_FAILURE or CDMF_NOMAP is returned, WebSEAL does not clean upthe memory used by the cdsso_user_info_t structure local_usr. In these cases, theimplementer of cdmf_map_user() must clean up this memory.

Parameters

Inputremote_usr

Out of domain user.

Input/Output

local_usrUser mapped to in this domain.




Return ValuesIf successful, the function returns CDMF_SUCCESS.

If no user mapping is available, the function returns CDMF_NOMAP.

Upon failure, the function returns CDMF_FAILURE.




CDSSO_FREE()

Deallocate the specified memory.

SyntaxvoidCDSSO_FREE(

void *ptr,);

DescriptionDeallocate the specified memory.

Parameters

ptr A pointer to the memory to be deallocated.

Return ValuesSuccess: none.

Error: none




CDSSO_MALLOC()

Allocates a portion of memory of the specified size.

Syntaxvoid *CDSSO_MALLOC(

size_t size,);

DescriptionAllocates a portion of memory of the specified size.

The caller is responsible for freeing the allocated memory.

Parameters

sizeSize in bytes of memory to allocate.

Return ValuesReturns a pointer to newly allocated memory.

Returns NULL if the call fails.




CDSSO_REALLOC()

Reallocates a memory block.

Syntaxvoid *CDSSO_REALLOC(

void *curr_ptr,size_t new_size

);

DescriptionReallocates a memory block.

The caller is responsible for freeing the allocated memory.

Parameters

curr_ptrPointer to the existing memory to be deallocated.

new_sizeSize in bytes of the new portion of memory.

Return ValuesReturns a pointer to the reallocated (and possibly moved) memory block.

Returns NULL is any memory errors are encountered.




CDSSO_STRDUP()

Duplicates the specified string.

Syntaxvoid*CDSSO_STRDUP(

char *dest,char *src

);

DescriptionDuplicates the specified string.

The caller is responsible for freeing the string when it is no longer needed.

Parameters

dest

Destination string.src Source string.

Return ValuesWhen successful, returns a pointer to the new memory.

Returns NULL if the call fails.




Appendix C. Authentication identifiers reference

The following sections list the identifiers that contain authentication information:

v “Identifiers common to all authentication methods” on page 86

v “User name and password authentication identifiers” on page 88

v “Certificate authentication identifiers” on page 89

v “Token card authentication identifiers” on page 90

v “HTTP authentication identifiers” on page 91

v “Failover authentication identifiers” on page 92

v “EAI identifiers” on page 93

v “Token create identifiers” on page 94

v “Token consume identifiers” on page 95

v “Switch user authentication identifiers” on page 96




Identifiers common to all authentication methods

All Tivoli Access Manager authentication methods use a common set of identifiers.Combine the identifiers in the following set with the identifiers that are specific tothe authentication method for your authentication module. The identifiers used forspecific authentication methods are described in separate sections that follow thisone.

Table 19. Identifiers common to all authentication methods

Name Description

XAUTHN_BROWSER_INFO Browser information.

In a switch-user operation, this data is supplied forany authentication module that must performadditional validations of the administrator account.

Example:"Mozilla/4.0 (Compatible; MSIE 6.0;

Windows NT 5.0)"

XAUTHN_EXISTING_CRED Used only for re-authentication and step-up

authentication. This contains the existing credential of the user as a string. In a switch-user operation, theidentity is the credential of the "switched-to" user.

The xauthn_existing_cred entry in the xnvlist_tauthentication data structure contains an encodedTivoli Access Manager credential. Use thexauthn_util_entry_to_creds() function to access thecredential. An example of how to use the function isincluded in the source code for the sample xauthnapplication.

Example: 0123456

XAUTHN_IPADDR User IPv4 address.


Example: 11.22.33.44

XAUTHN_IPADDR_IPV6 User IPv6 address.


Example: 9::8:7:6




Table 19. Identifiers common to all authentication methods (continued)

Name Description

XAUTHN_QOP Quality of protection. The format is:

authentication_method:version:cipher_used


Examples:

"x509:TLSv1:04""SSK:SSVV3:05"

The quality of protection for Tivoli Access Managerplug in for Web Servers is always none.

XAUTHN_CONFIG Used to set the configuration handle before addingitems to the xnvlist_t* pointer.

Appendix C. Authentication identifiers reference 87



User name and password authentication identifiers

User name and password authentication use the set of identifiers common to allauthentication methods (see Table 19 on page 86) plus a set of identifiers that arespecific to user name and password. The following table lists the specificidentifiers:

Table 20. Identifiers used for user name and password authentication Name Description

XAUTHN_USERNAME User name.

Example: testuser

XAUTHN_PASSWORD User password.

XAUTHN_NEW_PASSWORD User new password. Used only for thexauthn_change_password() function.

XAUTHN_METHOD User authentication method. Refers to the lastmethod used to authenticate the client. Itspossible values are:

token-card

password

Used only for xauthn_change_password() , as apassword strength module.




Certificate authentication identifiers

Certificate authentication uses the set of identifiers common to all authenticationmethods (see Table 19 on page 86) plus a set of identifiers that are specific tocertificate authentication. The following table lists the specific identifiers:

Table 21. Identifiers used for certificate authentication

Name Description

XAUTHN_CERT The certificate body, in DER format.

Example: binary-data

XAUTHN_CERT_DN The DN of the certificate.

Example:

cn=testuser,o=tivoli,c=us

XAUTHN_CERT_ISSUER_DN The DN of the issuer certificate authority.

Example:

[email protected]=issuer,o=tivoli,c=sus

XAUTHN_CERT_SERIAL_NUMBER The client certificate serial number.

Example:

04-67-F3-02

Auto-refresh option for certificate authentication calculates the life time value of the certificate and verifies every time an action using SSLSocket/SSLServerSocket.A SSLSocket/SSLServerSocket is created based on the PDContext. While anewPDContext is created, a thread calculates the life span of the certificate. Thecertificate will be refreshed only if its lifetime is less than the certificate half-lifeperiod. One thread refreshes the context and another thread reloads the refreshedcertificate. A new SSLContext is established with the new certificate, and the server

request is processed.




Token card authentication identifiers

Token card authentication uses the set of identifiers common to all authenticationmethods (see Table 19 on page 86) plus a set of identifiers that are specific to tokencard authentication. The following table lists the specific identifiers:

Table 22. Identifiers used for token card authentication

Name Description

XAUTHN_USERNAME User name.

Example: testuser

XAUTHN_METHOD User authentication method. Used only forxauthn_change_password() , as a password strengthserver.

XAUTHN_TOKEN User token (passcode). This functions like a password.

Example: 0123

XAUTHN_PASSWORD Current passcode of the user. Used only for thexauthn_change_password() function.

XAUTHN_NEW_PASSWORD New PIN of the user. Used only for thexauthn_change_password() function.




HTTP authentication identifiers

HTTP authentication uses the set of identifiers common to all authenticationmethods (see Table 19 on page 86) plus a set of identifiers that are specific to HTTPauthentication. The following table lists the specific identifiers:

Table 23. Identifiers used for HTTP header authentication

Name Description

Request_URI The request URI. This name is a literal string, not a variable.

header_name HTTP header name. The format of the xnvlist_t datastructure differs for the HTTP header authentication method.The header_name stored in xnvlist_t is the header namespecified in the [auth-headers] stanza of the WebSEALconfiguration file. The value is the authenticationinformation passed through that header.

XAUTHN_QUERY_STRING Contains the query string from an HTTP request. The HTTPquery string follows the question mark (?) character.

For example (entered as one line):

<A HREF="example?string=this is a sample">stringsample</A>

generates a variable named "string" with the value "this is asample". The entire query string is contained in theXAUTHN_QUERY_STRING identifier.

XAUTHN_REFERER Contains the location URI from the Referer header of anHTTP request. This URI indicates the location from which auser has linked to a Web page.

Example HTTP Referer header (entered as one line):

Referer:http://w3.ibm.com/hypertext/DataSources/Overview.html

The URI http://w3.ibm.com/hypertext/DataSources/Overview.html is contained in the XAUTHN_REFERER identifier.




Failover authentication identifiers

Failover authentication uses the set of identifiers common to all authenticationmethods (see Table 19 on page 86) plus a set of identifiers that are specific tofailover authentication. The following table lists the specific identifiers:

Table 24. Identifiers used for failover authentication

Name Value

XAUTHN_ATTR Any extended attributes are passed in the xnvlist_t*pointer with XAUTHN_ATTR (xauthn_attr_) prefixed tothem. For example, if you add an attribute calledcreditcard=123412341234, it would show up in thexnvlist as xauthn_attr_creditcard with a value of 123412341234. There can be several entries prefixed withXAUTHN_ATTR.

XAUTHN_FAILOVER_METHOD Value is one of the following:

v failover-password

v failover-certificate

v failover-token-card

v failover-http-request

v failover-cdsso

v failover-kerberosv5

v su-failover-ext-auth-interface

v failover-sso-create

v failover-sso-consume

XAUTHN_NUM_ATTRS Contains a string representation of a number of XAUTHN_ATTR attributes contained in the attribute list.

XAUTHN_USERNAME Contains the user name.

For example:

test-user




EAI identifiers

The external authentication interface (EAI) uses the set of identifiers common to allauthentication methods (see Table 19 on page 86) plus a set of identifiers that arespecific to the EAI. The following table lists the specific identifiers:

Table 25. Identifiers used for EAI authentication

Name Value

XAUTHN_ATTR Any extended attributes are passed in the xnvlist_t*pointer with XAUTHN_ATTR (xauthn_attr_) prefixed tothem. For example, if you add an attribute calledcreditcard=123412341234, it would show up in thexnvlist as xauthn_attr_creditcard with a value of 123412341234. There can be several entries prefixed withXAUTHN_ATTR.

XAUTHN_NUM_ATTRS Contains a string representation of a number of XAUTHN_ATTR attributes contained in the attribute list.

XAUTHN_USERNAME Contains the user name.

For example:

test-user




Token create identifiers

The token create module, used for CDSSO and ECSSO, uses the set of identifierscommon to all authentication methods (see Table 19 on page 86) plus a set of identifiers that are specific to token creation. The following table lists the specificidentifiers:

Table 26. Identifiers used for token creation Identifier Description

XAUTHN_HOSTNAME Contains the source machine name.

XAUTHN_INPUT_URL Destination URL. For example:

http://example.com/request.htm

XAUTHN_SSO_TYPE This is a string that is created and freed by WebSEAL.This string is passed down to the calling library toinform it whether it was called to use the createfunction or the consume function. This string isimportant when both token creation and tokenconsumption are written in the same library.

Values can be SSO_CREATE_TYPE or SSO_CONSUME_TYPE.XAUTHN_TOKEN_TYPE This identifier contains an integer representing the

token type used to determine whether the modulewas called to generate an e-community single signonvouch-for token or a CDSSO authentication token.Valid values for this are the integer 2 for CDSSO andthe integer 3 for e-community single sign-on. Forexample:

XAUTHN_TOKEN_TYPE = 3

XAUTHN_VFT_STATUS This identifier contains the success or failure status of the authentication performed at an e-communitysingle signon "vouch-for" server. For example:

XAUTHN_VFT_STATUS = 320938186

This value is the error status code number.




Token consume identifiers

The token consume module, used for CDSSO and ECSSO, uses the set of identifiers common to all authentication methods (see Table 19 on page 86) plus aset of identifiers that are specific to token consumption. The following table liststhe specific identifiers:

Table 27. Identifiers used for token consumption Identifier Description

XAUTHN_SSO_TYPE This is a string created and released by WebSEAL.This string is passed down to the calling library toinform it whether it was called to use the createfunction or the consume function. This string isimportant when both token creation and tokenconsumption are written into the same library.

Values can be SSO_CREATE_TYPE or SSO_CONSUME_TYPE.

XAUTHN_QUERY_STRING Contains the query string from a redirected CDSSO orECSSO request. The HTTP query string follows thequestion mark (?) character.




Switch user authentication identifiers

An existing authentication module often returns additional information about theuser that is incorporated into the credential of the user. If you are using the switchuser feature in such an environment, you must write a special switch userauthentication module that emulates the behavior of your existing authenticationmodule while supporting the requirement of returning a credential without

requiring the user password for input. Switch user function does not supportExternal Authentication Interface (EAI).

The Tivoli Access Manager external authentication C API provides a set of identifiers that can be used to pass client authentication information to the switchuser authentication module library. This information is passed using a name/valuelist format, where the name is an identifier that specifies the value type.

Tivoli Access Manager supports switch-user authentication for password, tokencard, certificate, HTTP request, and single signon token authentication methods.For more information about switch user authentication, including configurationinstructions, see the IBM Tivoli Access Manager for e-business: WebSEAL

Administration Guide.

The following authentication data identifiers are valid for all of the switch-userauthentication methods:

Table 28. Identifiers used for switch user authentication

Name Value

XAUTHN_SU_METHOD Specifies the type of switch-user authentication method.Must be one of the following values:

v su-password

Username and password authentication

v su-token-card

Token authentication

v su-certificate

X.509 certificate authentication

v su-http-request

HTTP header authentication

v su-cdsso

Cross-domain single signon authentication.

XAUTHN_ADMIN_NAME The user name of the administrator attempting to switchuser. For example:

sec_master

XAUTHN_ADMIN_CRED The credential of the administrator attempting to switch

user, as a string.

The xauthn_admin_cred entry in the xnvlist_tauthentication data structure contains an encoded TivoliAccess Manager credential. Use thexauthn_util_entry_to_creds() function to access thecredential. An example of how to use the function isincluded in the source code for the sample xauthnapplication.




Table 28. Identifiers used for switch user authentication (continued)

Name Value

XAUTHN_USERNAME The user name of the "switched-to" user. For example:

test-user







Appendix D. External authentication interface

Tivoli Access Manager provides an external authentication interface that enablesyou to extend the functionality of the WebSEAL and the plug-in for Web Servers

authentication process. The external authentication interface allows a remoteservice to handle the authentication process for WebSEAL and the plug-in for WebServers. The identity information returned by the external authentication interfaceservice is used to generate user credentials.

This extended authentication functionality is like the existing customauthentication module capability provided by the Web security externalauthentication C API. However, the external authentication interface returns useridentity information in HTTP response headers rather than through theauthentication module interface.

The external authentication interface is not a replacement for built-in or customauthentication modules that are used by WebSEAL and the plug-in for WebServers. However, the external authentication interface can provide a moreconvenient authentication capability for many environments and, unlike theexternal authentication C API, can be used with applications written in anylanguage, including Java.

When using the external authentication interface, the authentication operation isperformed externally on a remote, junctioned server. The design, methodology, andcode for the custom authentication operation is entirely the responsibility of theapplication developer. This developer reference document does not provide anyinstructions for the construction of this custom authentication operation. However,it is expected that identity information resulting from the custom authenticationprocess be returned in specially named HTTP response headers.

For complete information about configuring and using the external authenticationinterface refer to the following document:

v IBM Tivoli Access Manager for e-business: WebSEAL Administration Guide

v IBM Tivoli Access Manager for e-business: Plug-in for Web Servers AdministrationGuide







Appendix E. 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 102

v “Receiving weekly software updates” on page 102

v “Contacting IBM Software Support” on page 103

Searching knowledge bases

If 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 Technotes

v IBM downloads

v IBM Redbooks®

v IBM developerWorks®

v Forums and news groups

v Google

Obtaining fixes

A 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/support

2. Under Products A - Z, click the letter with which your product starts to open aSoftware 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 find a list of fixes,fix packs, and other service updates for your product. For tips on refining your

search, click Search tips.5. Click the name of a fix to read the description.

6. Optional, download the fix.

Registering with IBM Software Support

Before 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:


2. Click Register in the upper right-hand corner of the support page to establishyour user ID and password.

3. Complete the form, and click Submit.

Receiving weekly software updates

After 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


2. 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 tochoose 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 wantto 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












Contacting IBM Software Support

IBM 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 of product 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_HomeBy phone

For 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.html

v For IBM eServer™ software products (including, but not limited to, DB2 andWebSphere 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 Technical

Support 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 of people who provide support for your location:


To contact IBM Software support, follow these steps:

1. “Determining the business impact”2. “Describing problems and gathering information” on page 104

3. “Submitting problems” on page 104

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 E. Support information 103

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












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, but

it is severely limited.Severity 3

The 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 relevant

background 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 problemsymptoms? IBM Software Support is likely to ask for this information.

v Can you create the problem again? If so, what steps were performed toencounter the problem?

v Was any change made to the system? For example, were there changes to thehardware, operating system, networking software, and so on.

v Are you currently using a workaround for this problem? If so, please beprepared 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 of the IBM Software Support Handbook at the following Web address and click

the 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 101 and “Obtaining fixes” on page 101.

Appendix E. Support information 105






Appendix F. 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 in

other 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 may

be 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 it believes 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 agreement

between 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 of those products, their published announcements, or other publicly available sources.IBM has not tested those products and cannot confirm the accuracy of

performance, 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 are

fictitious 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, must

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

Trademarks

IBM, 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 the

United 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, or both.

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

Appendix F. Notices 109



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 Access

Manager. 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 different

meaning.See Refers the reader to a term that is the

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

A

access control. In computer security, the process of ensuring 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. Customersmight 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 computer

language 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






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 granting

and 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 server

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

B

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

C

CA. 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, 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 data

security 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






an external source for a principal or set of conditions.Entitlements are normally application-specific data thatare consumed by the resource manager application insome way or added to the principals credentials for usefurther on in the authorization process. Customersmight 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, a

bitmap, 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 the

built-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 is

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

F

file 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 of protocols, a protocol that can use Transmission ControlProtocol (TCP) and Telnet services to transfer files

between machines.

FTP. See file transfer protocol

G

global 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 are

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

H

host. A computer that is connected to a network andprovides an access point to that network. The host can

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

I

inheritance. An object-oriented programmingtechnique that allows the use of existing classes as a

basis for creating other classes.




Internet protocol (IP). In the Internet suite of protocols, 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 published

through 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 of interprocess 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.

J

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

K

KDC. See key distribution center.

Kerberos. An authentication system that enables twoparties to exchange private information over anotherwise open network. It works by assigning a

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

L

LDAP. 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 does

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

M

management 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 115



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 of stored 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 and

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

N

namespace. (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 of its 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.

O

object. (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 of characteristics 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.

P

PAC. 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 of permissions 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 the

domain. 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 personalize

a 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 mightdevelop 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 server

but should be permitted some services.

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

Q

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

R

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

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

remote cache mode. An operational mode in which aresource manager uses the functions that are provided

by 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 include business 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 customized

with the setup and configuration data that automatesan installation. The setup and configuration data has to

be 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 117



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 in

the 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 of factoring 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.

S

scalability. 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 user

without 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 can

be 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 of authentication levels and enforces a specific level of authentication 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 required by the policy protecting a resource. See also protectedobject policy.

suffix. A distinguished name that identifies the topentry in a locally held directory hierarchy. Because of the relative naming scheme used in LightweightDirectory Access Protocol (LDAP), this suffix applies to

every other entry within that directory hierarchy. Adirectory server can have multiple suffixes, eachidentifying a locally held directory hierarchy.

T

ticket. 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 control

the medium.

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

U

uniform 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 particular

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

V

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

W

Web 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 administrators

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

X

XML. 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 119






Index

Special charactersheader_name 91

Request_URI 91

Aaccessibility ixADK (application development kit)

components 11cross-domain mapping framework API 13EPAC demonstration application 15external authentication C API 12password strength API 14

overview 2amwauthconv 25application development kit (ADK)

components 11cross-domain mapping framework API 13EPAC demonstration application 15external authentication C API 12password strength API 14

overview 2authentication

external authentication interface 99authentication data structure 30authentication interfaces 4

external authentication C API 5external authentication C API modules 5Tivoli Access Manager authorization API 5Tivoli Access Manager runtime 4Web security resource manager 4

authentication mechanisms

stanza entries 21authentication module

adding extended attributes to the credential 38 build instructions 19customizing password strength checking 36customizing the authentication process 32customizing user password change 35example library 19modifying the user name in a credential 40processing post password changes 37software requirements 19task summary 18UTF-8 compatibility 24WebSEAL configuration 21writing custom modules 31

authentication module example library 19authentication process flows 7

authentication 7change password 8extended attributes 9password strength 8post password change 9

authentication stanza entry 55authentication terminology

mechanism 3method 3module 3operations 3

authnmech_info 30

B books

see publications v, viii

Ccdmf module 51cdmf_add_attr_to_list() 74cdmf_add_value_to_attr() 75cdmf_adk directory 13cdmf_create_usr_attr_list() 77cdmf_create_usr_attr() 76cdmf_get_usr_attributes() 51, 52, 78cdmf_map_usr() 51, 52, 79

cdmf_utils.h header file 13cdmf_utils.lib library file 13cdmf.c.example source file 13cdmf.c.skeleton source file 13, 51cdmf.h header file 13cdsso_attrlist_t 52CDSSO_FREE() 81CDSSO_MALLOC() 82CDSSO_REALLOC() 83CDSSO_STRDUP() 84cdsso_usr_info_t 52cdsso-argument 44cdsso-argument stanza entry 55cdsso-auth stanza entry 55cdsso-redirect-url attribute 48

cdssotypes.h header file 13common problems

reportingdescribing problem 104determining business impact 103gathering information 104

submitting problems 104conventions

typeface xconversion library 25

configuration 25cred-ext-attrs stanza entry 38, 41credential

UTF-8 data format 24credential attributes

AUTHENTICATION_LEVEL 15AZN_CRED_AUTH_METHOD 15AZN_CRED_AUTHNMECH_INFO 15AZN_CRED_AUTHZN_ID 15AZN_CRED_BROWSER_INFO 15AZN_CRED_GROUPS 15AZN_CRED_GROUPS_NAMES 15AZN_CRED_IP_ADDRESS 15AZN_CRED_LDAP_DN 15AZN_CRED_MECH_ID 15AZN_CRED_PRINCIPAL_NAME 15AZN_CRED_PRINCIPAL_UUID 15AZN_CRED_QOP_INFO 15




credential attributes (continued)AZN_CRED_VERSION 15table of 15

cross-domain mapping framework API build instructions 51customizing the example source file 51overview 50providing identity mapping 52

providing user attributes 52single signon with a non-WebSEAL server 54software requirements 51specifying extended attributes 52understanding functions and macros 13

cross-domain mapping framework API description 13cross-domain single signon

token consumption 45token creation 44

custom modulesadding extended attributes to the credential 38customizing password strength checking 36customizing the authentication process 32customizing user password change 35modifying the user name in a credential 40processing post password changes 37

writing custom modules 31customer support

contacting 103obtaining fixes 101receiving updates from 102registering with 102searching information centers 101searching knowledge bases 101searching the Internet 101submitting problems 104

Ddata structures 29

authentication data 30extended attributes 29user identity information 29xattr_list_item_t 59xattr_list_t 60xauthn_identity_t 65xnvlist_item_t 70xnvlist_t 71

deprecated APIspassword strength 14

directory names, notation xidisplaying credential attributes 15

Ee-community single signontoken consumption 45

token creation 44education

see Tivoli technical training ixenvironment variables, notation xiEPAC 15

displaying credential attributes 15epac demonstration program 15EPAC example application 15epac.c source file 15extended attribute data structure 29extended attributes 38, 52

extended privilege attribute certificate 15external authentication C API

build instructions 19data structures 29example library 19functions 27initializing 28software requirements 19

writing custom modules 31external authentication C API description 12external authentication interface 99

Ffixes, obtaining 101functions 27

cdmf_add_attr_to_list() 74cdmf_add_value_to_attr() 75cdmf_create_usr_attr_list() 77cdmf_create_usr_attr() 76cdmf_get_usr_attributes() 78cdmf_map_usr() 79xattr_get() 27, 58

xattr_set() 27, 61xauthn_authenticate() 27, 63xauthn_change_password() 27, 64xauthn_initialize() 27, 66xauthn_shutdown() 27, 67xauthn_util_entry_to_creds() 27, 68xauthn_utils_append_extcred_tags() 62xnvlist_get() 27, 69

HHTTP_IV_CREDS

in EPAC example 15

Iidentifier types (authentication)

certificate 89common 86EAI 93failover 92HTTP 91switch user 96token card 90token consume 95token create 94username and password 88

identifiers (authentication)header_name 91

Request_URI 91

XAUTHN_ADMIN_CRED 96XAUTHN_ADMIN_NAME 96XAUTHN_ATTR 92, 93XAUTHN_BROWSER_INFO 86XAUTHN_CERT 89XAUTHN_CERT_DN 89XAUTHN_CERT_ISSUER_DN 89XAUTHN_CONFIG 86XAUTHN_EXISTING_CRED 86XAUTHN_FAILOVER_METHOD 92XAUTHN_HOSTNAME 94XAUTHN_INPUT_URL 94XAUTHN_IPADDR 86




identifiers (authentication) (continued)XAUTHN_IPADDR_IPV6 86XAUTHN_METHOD 88, 90XAUTHN_NEW_PASSWORD 88, 90XAUTHN_NUM_ATTRS 92, 93XAUTHN_PASSWORD 88, 90XAUTHN_QOP 86XAUTHN_QUERY_STRING 91, 95

XAUTHN_REFERER 91XAUTHN_SSO_TYPE 94, 95XAUTHN_SU_METHOD 96XAUTHN_TOKEN 90XAUTHN_TOKEN_TYPE 94XAUTHN_USERNAME 88, 90, 92, 93, 96XAUTHN_VFT_STATUS 94

information centers, searching 101interfaces (authentication) 4

external authentication C API 5external authentication C API modules 5Tivoli Access Manager authorization API 5Tivoli Access Manager runtime 4Web security resource manager 4

Internet, searching 101

Kknowledge bases

information centers 101searching 101the Internet 101

Llibamwauthnconv 25libcdmf module 51libcdmfutils. (so, a, sl) library file 13libpdxauthn.a library file 12libssoconsume module 47

libssocreate module 47libxauthn module 47

MMakefile.cdmf.in makefile 13Makefile.in makefile 15Makefile.win32 makefile 13manuals

see publications v, viiimemory management macros

CDSSO_FREE() 81CDSSO_MALLOC() 82CDSSO_REALLOC() 83CDSSO_STRDUP() 84

module interface 49

Nnotation

environment variables xipath names xitypeface xi

Oonline publications

accessing viiiordering publications ix

Ppasswd-strength stanza entry 36password strength 14password strength API description 14path names, notation xipdxauthn libraries 27pdxauthn_adk directory 12pdxauthn.h header file 12pdxauthn.lib library file 12pkmscdsso page 44pkmsvouchfor 44pkmsvouchfor page 44post password change processing 37post-pwdchg-process stanza entry 37pre-authzn stanza entry 54process flows 7

authentication 7change password 8extended attributes 9password strength 8post password change 9

publications vaccessing online viiiordering ix

Rresource manager 2

Ssample code 38single signon

cross-domain single signon 44customization 43e-community single signon 44

single signon customization built-in token create and consume modules 47cross-domain mapping framework build instructions 51cross-domain mapping framework example source file 51cross-domain mapping framework overview 50cross-domain mapping framework software

requirements 51customizing identity mapping and attribute handling 50example token create and consume modules 47providing identity mapping 52

providing user attributes 52single signon with a non-WebSEAL server 54specifying extended attributes 52token consume module interface 49token consumption

cross-domain single signon 45e-community single signon 45

token create module interface 48token creation

cross-domain single signon 44e-community single signon 44

software updates, receiving 102

Index 123



source filexauthn.c 12

sso-consume stanza entry 48, 55sso-create stanza entry 48, 54ssoconsume module 45ssocreate module 44, 47support

See customer support

switch user authentication 96

Tterminology (authentication)

mechanism 3method 3module 3operations 3

Tivoli Information Center viiiTivoli technical training ixTivoli user groups ixtoken consume 49token consumption

ssoconsume module 45

token createmodule interface 48

token creationssocreate module 44

training, Tivoli technical ixtypeface conventions x

Uuser groups, Tivoli ixuser identity data structure 29UTF-8 25

compatibility 24conversion library 25entitlements service data format 24

user credential data format 24

Vvariables, notation for xi

WWeb security resource manager 2WebSEAL

configuration for custom modules 21

Xxattr_get() 27, 58xattr_list_item_t 29, 59xattr_list_t 29, 60xattr_set() 27, 61xattr.h header file 12xauthn module 47XAUTHN_ADMIN_CRED 96XAUTHN_ADMIN_NAME 96XAUTHN_ATTR 92, 93xauthn_authenticate() 5, 27, 32, 38, 63XAUTHN_BROWSER_INFO 86XAUTHN_CERT 89XAUTHN_CERT_DN 89

XAUTHN_CERT_ISSUER_DN 89xauthn_change_password() 5, 27, 35, 64XAUTHN_CONFIG 86XAUTHN_EXISTING_CRED 86XAUTHN_FAILOVER_METHOD 92XAUTHN_HOSTNAME 94xauthn_identity_t 29, 33, 65xauthn_initialize() 5, 27, 28, 36, 66

XAUTHN_INPUT_URL 94XAUTHN_IPADDR 86XAUTHN_IPADDR_IPV6 86XAUTHN_METHOD 88, 90XAUTHN_NEW_PASSWORD 88, 90XAUTHN_NUM_ATTRS 92, 93XAUTHN_PASSWORD 88, 90XAUTHN_QOP 86XAUTHN_QUERY_STRING 91, 95XAUTHN_REFERER 91xauthn_shutdown() 5, 27, 36, 67XAUTHN_SSO_TYPE 94, 95XAUTHN_SU_METHOD 96XAUTHN_TOKEN 90XAUTHN_TOKEN_TYPE 94XAUTHN_USERNAME 88, 90, 92, 93, 96

xauthn_util_entry_to_creds() 27, 68xauthn_utils_append_extcred_tags() 62XAUTHN_VFT_STATUS 94xauthn.c source file 12xnvlist_get() 27, 48, 69xnvlist_item_t 30, 70xnvlist_t 30, 48, 71xnvlist.h header file 12






Printed in USA

Am611 Web Devref

Documents