You are on page 1of 98

IBM Tivoli Access Manager

WebSEAL Developers Reference


V ersion 4.1

SC32-1135-01

IBM Tivoli Access Manager

WebSEAL Developers Reference


V ersion 4.1

SC32-1135-01

Note Before using this information and the product it supports, read the information in Appendix B, Notices, on page 75.

Fifth Edition (August 2003) This edition replaces GC32-0685-01 Copyright International Business Machines Corporation 1999, 2002. All rights reserved. US Government Users Restricted Rights Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.

Contents
Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . vii
Who should read this book . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . vii What this book contains . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . vii Publications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . viii Release information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . viii Base information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . viii WebSEAL information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . viii Web security information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . viii Developer references . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ix Technical supplements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ix Related publications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . x Accessing publications online . . . . . . . . . . . . . . . . . . . . . . . . . . . . xi Ordering publications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xii Accessibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xii Contacting software support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xii Conventions used in this book . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xii Typeface conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xii Operating system differences . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiii

Part 1. CDAS Developer Reference. . . . . . . . . . . . . . . . . . . . . . . 1


Chapter 1. CDAS overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
Introducing the CDAS . . . . . . . . . . . . . Supported authentication methods . . . . . . . . Enabling dynamic business entitlements . . . . . . CDAS authentication models . . . . . . . . . . . The single authentication CDAS model . . . . . . The credential extended attributes CDAS chaining model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 4 5 5 5 6

Chapter 2. Implementing a custom CDAS library . . . . . . . . . . . . . . . . . . 9


CDAS and External Authentication API components . . . Header files . . . . . . . . . . . . . . . Software requirements for implementing a custom CDAS Using the external authentication C API functions . . . Initialization: xauthn_initialize() . . . . . . . . Shutdown: xauthn_shutdown() . . . . . . . . . Authentication: xauthn_authenticate(). . . . . . . Password change: xauthn_change_password() . . . . Valid user authentication data . . . . . . . . . . Returning the client identity (xauthn_identity_t) . . . . Specifying extended attributes . . . . . . . . . . Building the custom library . . . . . . . . . . . Writing a CDAS for switch user . . . . . . . . . Writing a CDAS for post password change processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 10 10 10 10 11 11 11 11 14 14 15 16 18

Chapter 3. Configuring WebSEAL to use a CDAS . . . . . . . . . . . . . . . . . 19


Configuring and installing the custom CDAS library . . . Additional configuration for an extended attributes CDAS Using the example library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 . 20 . 20

Part 2. CDMF Developer Reference . . . . . . . . . . . . . . . . . . . . . . 23


Chapter 4. Using a CDMF library. . . . . . . . . . . . . . . . . . . . . . . . . 25
Copyright IBM Corp. 1999, 2002

iii

Introducing the Cross-domain Mapping Framework . Using CDMF in a CDSSO environment . . . . Using CDMF in an e-community environment. . CDMF API components . . . . . . . . . . Software requirements . . . . . . . . . . Implementing the CDMF library . . . . . . . The CDMF library partnership . . . . . . . Customizing the CDMF library . . . . . . . . Providing user attributes: cdmf_get_usr_attributes() Providing identity mapping: cdmf_map_usr() . . Naming the custom library . . . . . . . . Specifying extended attributes . . . . . . . .

. . . . . . . . . . . .

. . . . . . . . . . . .

. . . . . . . . . . . .

. . . . . . . . . . . .

. . . . . . . . . . . .

. . . . . . . . . . . .

. . . . . . . . . . . .

. . . . . . . . . . . .

. . . . . . . . . . . .

. . . . . . . . . . . .

. . . . . . . . . . . .

. . . . . . . . . . . .

. . . . . . . . . . . .

. . . . . . . . . . . .

. . . . . . . . . . . .

. . . . . . . . . . . .

. . . . . . . . . . . .

. . . . . . . . . . . .

. . . . . . . . . . . .

. . . . . . . . . . . .

. . . . . . . . . . . .

25 25 26 26 27 27 28 28 28 29 29 29

Chapter 5. CDMF C API reference . . . . . . . . . . . . . . . . . . . . . . . . 31


Summary: CDMF API functions and cdmf_map_usr() . . . . . . . cdmf_get_usr_attributes() . . . . cdmf_create_usr_attr_list() . . . cdmf_create_usr_attr() . . . . . cdmf_add_value_to_attr(). . . . cdmf_add_attr_to_list() . . . . CDSSO_STRDUP() . . . . . . CDSSO_MALLOC() . . . . . CDSSO_FREE() . . . . . . . CDSSO_REALLOC() . . . . . macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 33 35 36 37 38 39 40 41 42 43

Part 3. Password Strength Module Reference . . . . . . . . . . . . . . . . . 45


Chapter 6. Customizing password strength policy . . . . . . . . . . . . . . . . . 47
Password strength policy overview . . . . . . Introducing the Password Strength Policy Module Building the custom Password Strength Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47 . 47 . 48

Part 4. Cross-domain External Interface . . . . . . . . . . . . . . . . . . . . 49


Chapter 7. Creating a custom CDSSO library . . . . . . . . . . . . . . . . . . . 51
Understanding CDSSO token creation and consumption . . . Default token creation . . . . . . . . . . . . . . Default token consumption . . . . . . . . . . . . Customizing the CDSSO shared library . . . . . . . . . Using the example (demonstration) library file . . . . . Creating and building a custom token create/consume library Customizing the token create library interface . . . . . . Customizing the token consume library interface . . . . . Sending SSO requests to a non-WebSEAL server . . . . . . Accepting SSO requests from a non-WebSEAL server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51 52 52 53 53 54 54 55 55 56

Appendix A. External Authentication C API Reference . . . . . . . . . . . . . . . 59


Summary: CDAS and utility API xauthn_initialize() . . . . . xauthn_shutdown() . . . . . xauthn_authenticate() . . . . xauthn_change_password() . . xattr_get() . . . . . . . . xattr_set() . . . . . . . . xauthn_util_entry_to_creds(). . xnvlist_get() . . . . . . . xattr_list_item_t . . . . . . xattr_list_t . . . . . . . . functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59 61 62 63 64 65 66 67 68 69 70

iv

IBM Tivoli Access Manager: WebSEAL Developers Reference

xauthn_identity_t xnvlist_item_t . xnvlist_t . . .

. . .

. . .

. . .

. . .

. . .

. . .

. . .

. . .

. . .

. . .

. . .

. . .

. . .

. . .

. . .

. . .

. . .

. . .

. . .

. . .

. . .

. . .

. . .

. . .

. . .

. . .

. . .

. . .

. . .

. . .

. . .

. . .

. 71 . 72 . 73

Appendix B. Notices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
Trademarks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79

Contents

vi

IBM Tivoli Access Manager: WebSEAL Developers Reference

Preface
Welcome to the IBMTivoliAccess Manager WebSEAL Developers Reference. IBM Tivoli Access Manager (Tivoli Access Manager) is the base software that is required to run applications in the IBM Tivoli Access Manager product suite. It enables the integration of IBM Tivoli Access Manager applications that provide a wide range of authorization and management solutions. Sold as an integrated solution, these products provide an access control management solution that centralizes network and application security policy for e-business applications. Note: IBM Tivoli Access Manager is the new name of the previously released software entitled Tivoli SecureWay Policy Director. Also, for users familiar with the Tivoli SecureWay Policy Director software and documentation, the management server is now referred to as the policy server. This document provides complete administration and programming information for the Cross-domain Authentication Service (CDAS), the Cross-domain Mapping Framework (CDMF), the Password Strength Module, and the cross-domain external interface. The document also contains the complete CDMF API reference and the External Authentication C API reference.

Who should read this book


This guide is for system administrators responsible for the installation, deployment, and administration of Tivoli Access Manager.. Readers should be familiar with the following: v Microsoft Windows and UNIX operating systems v Security management v v v v Internet protocols, including HTTP, HTTPS, and TCP/IP Lightweight Directory Access Protocol (LDAP) and directory services Authentication and authorization Access Manager security model and its capabilities

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

What this book contains


This reference contains the following sections: v v v v v Part 1 CDAS Developer Reference (Chapters 1-3) Part 2 CDMF Developer Reference (Chapters 45) Part 3 Password Strength Module Reference (Chapter 6) Part 4 Cross-domain External Interface (Chapter 7) Appendix A External Authentication C API Reference

Copyright IBM Corp. 1999, 2002

vii

Publications
The Tivoli Access Manager library is organized into the following categories: v Release information v Base information v WebSEAL information v Web security information v Developer references on page ix v Technical supplements on page ix

Release information
v IBM Tivoli Access Manager Read Me First Card GI11-4198-00 (am41_readme.pdf) Provides information for installing and getting started using Tivoli Access Manager. v IBM Tivoli Access Manager Release Notes SC32-1130-00 (am41_relnotes.pdf) Provides late-breaking information, such as software limitations, workarounds, and documentation updates.

Base information
v IBM Tivoli Access Manager Base Installation Guide SC32-1131-01 (am41_install.pdf) Explains how to install, configure, and upgrade Tivoli Access Manager software, including the Web Portal Manager interface. v IBM Tivoli Access Manager Base Administrators Guide SC32-1132-01 (am41_admin.pdf) Describes the concepts and procedures for using Tivoli Access Manager services. Provides instructions for performing tasks from the Web Portal Manager interface and by using the pdadmin command.

WebSEAL information
v IBM Tivoli Access Manager WebSEAL Installation Guide SC32-1133-01 (amweb41_install.pdf) Provides installation, configuration, and removal instructions for the WebSEAL server and the WebSEAL application development kit. v IBM Tivoli Access Manager WebSEAL Administrators Guide SC32-1134-01 (amweb41_admin.pdf) Provides background material, administrative procedures, and technical reference information for using WebSEAL to manage the resources of your secure Web domain.

Web security information


v IBM Tivoli Access Manager for WebSphere Application Server Users Guide SC32-1136-01 (amwas41_user.pdf) Provides installation, removal, and administration instructions for Tivoli Access Manager for IBM WebSphere Application Server. v IBM Tivoli Access Manager for WebLogic Server Users Guide SC32-1137-01 (amwls41_user.pdf)

viii

IBM Tivoli Access Manager: WebSEAL Developers Reference

Provides installation, removal, and administration instructions for Tivoli Access Manager for BEA WebLogic Server. v IBM Tivoli Access Manager Plug-in for Edge Server Users Guide SC32-1138-01 (amedge41_user.pdf) Describes how to install, configure, and administer the plug-in for IBM WebSphere Edge Server application. v IBM Tivoli Access Manager Plug-in for Web Servers Users Guide SC32-1139-01 (amws41_user.pdf) Provides installation instructions, administration procedures, and technical reference information for securing your Web domain using the plug-in for Web servers.

Developer references
v IBM Tivoli Access Manager Authorization C API Developers Reference SC32-1140-01 (am41_authC_devref.pdf) Provides reference material that describes how to use the Tivoli Access Manager authorization C API and the Access Manager service plug-in interface to add Tivoli Access Manager security to applications. v IBM Tivoli Access Manager Authorization Java Classes Developers Reference SC32-1141-01 (am41_authJ_devref.pdf) Provides reference information for using the Java language implementation of the authorization API to enable an application to use Tivoli Access Manager security. v IBM Tivoli Access Manager Administration C API Developers Reference SC32-1142-01 (am41_adminC_devref.pdf) Provides reference information about using the administration API to enable an application to perform Tivoli Access Manager administration tasks. This document describes the C implementation of the administration API. v IBM Tivoli Access Manager Administration Java Classes Developers Reference SC32-1143-01 (am41_adminJ_devref.pdf) Provides reference information for using the Java language implementation of the administration API to enable an application to perform Tivoli Access Manager administration tasks. v IBM Tivoli Access Manager WebSEAL Developers Reference SC32-1135-01 (amweb41_devref.pdf) Provides administration and programming information for the Cross-domain Authentication Service (CDAS), the Cross-domain Mapping Framework (CDMF), and the Password Strength Module.

Technical supplements
v IBM Tivoli Access Manager Command Reference GC32-1107-01 (am41_cmdref.pdf) Provides information about the command line utilities and scripts provided with Tivoli Access Manager. v IBM Tivoli Access Manager Error Message Reference SC32-1144-01 (am41_error_ref.pdf) Provides explanations and recommended actions for the messages produced by Tivoli Access Manager. v IBM Tivoli Access Manager Problem Determination Guide GC32-1106-01 (am41_pdg.pdf)
Preface

ix

Provides problem determination information for Tivoli Access Manager. v IBM Tivoli Access Manager Performance Tuning Guide SC32-1145-01 (am41_perftune.pdf) Provides performance tuning information for an environment consisting of Tivoli Access Manager with the IBM Directory server defined as the user registry.

Related publications
This section lists publications related to the Tivoli Access Manager library. The Tivoli Software Library provides a variety of Tivoli publications such as white papers, datasheets, demonstrations, redbooks, and announcement letters. The Tivoli Software Library is available on the Web at: http://www.ibm.com/software/tivoli/library/ The Tivoli Software Glossary includes definitions for many of the technical terms related to Tivoli software. The Tivoli Software Glossary is available, in English only, from the Glossary link on the left side of the Tivoli Software Library Web page http://www.ibm.com/software/tivoli/library/

IBM Global Security Toolkit


Tivoli Access Manager provides data encryption through the use of the IBM Global Security Toolkit (GSKit). GSKit is included on the IBM Tivoli Access Manager Base CD for your particular platform. The GSKit package installs the iKeyman key management utility, gsk5ikm, which enables you to create key databases, public-private key pairs, and certificate requests. The following document is available on the Tivoli Information Center Web site in the same section as the IBM Tivoli Access Manager product documentation: v Secure Sockets Layer Introduction and iKeyman Users Guide (gskikm5c.pdf) Provides information for network or system security administrators who plan to enable SSL communication in their Tivoli Access Manager environment. IBM DB2 Universal Database is required when installing IBM Directory Server, z/OS, and OS/390 LDAP servers. DB2 is provided on the product CDs for the following operating system platforms: v IBM AIX v Microsoft Windows v Sun Solaris Operating Environment DB2 information is available at: http://www.ibm.com/software/data/db2/

IBM DB2 Universal Database

IBM Directory Server


IBM Directory Server, Version 4.1, is included on the IBM Tivoli Access Manager Base CD for all platforms except Linux for zSeries. You can obtain the IBM Directory Server software for Linux for S/390 at: http://www.ibm.com/software/network/directory/server/download/

IBM Tivoli Access Manager: WebSEAL Developers Reference

If you plan to use IBM Directory Server as your user registry, see the information provided at: http://www.ibm.com/software/network/directory/library/

IBM WebSphere Application Server


IBM WebSphere Application Server, Advanced Single Server Edition 4.0.3, is included on the Web Portal Manager CDs and installed with the Web Portal Manager interface. For information about IBM WebSphere Application Server, see: http://www.ibm.com/software/webservers/appserv/infocenter.html

IBM Tivoli Access Manager for Business Integration


IBM Tivoli Access Manager for Business Integration, available as a separately orderable product, provides a security solution for IBM MQSeries, Version 5.2, and IBM WebSphere MQ for Version 5.3 messages. IBM Tivoli Access Manager for Business Integration allows WebSphere MQSeries applications to send data with privacy and integrity by using keys associated with sending and receiving applications. Like WebSEAL and IBM Tivoli Access Manager for Operating Systems, IBM Tivoli Access Manager for Business Integration, is one of the resource managers that use the authorization services of IBM Tivoli Access Manager for e-business. The following documents associated with IBM Tivoli Access Manager for Business Integration Version 4.1 are available on the Tivoli Information Center Web site: v IBM Tivoli Access Manager for Business Integration Administrators Guide (SC23-4831-00) v IBM Tivoli Access Manager for Business Integration Release Notes (GI11-0957-00) v IBM Tivoli Access Manager for Business Integration Read Me First (GI11-0958-00)

IBM Tivoli Access Manager for Operating Systems


IBM Tivoli Access Manager for Operating Systems, available as a separately orderable product, provides a layer of authorization policy enforcement on UNIX systems in addition to that provided by the native operating system. IBM Tivoli Access Manager for Operating Systems, like WebSEAL and IBM Tivoli Access Manager for Business Integration, is one of the resource managers that use the authorization services of IBM Tivoli Access Manager for e-business. The following documents associated with IBM Tivoli Access Manager for Operating Systems Version 4.1 are available on the Tivoli Information Center Web site: v IBM Tivoli Access Manager for Operating Systems Installation Guide (SC23-4829-00) v IBM Tivoli Access Manager for Operating Systems Administration Guide (SC23-4827-00) v IBM Tivoli Access Manager for Operating Systems Problem Determination Guide (SC23-4828-00) v IBM Tivoli Access Manager for Operating Systems Release Notes (GI11-0951-00) v IBM Tivoli Access Manager for Operating Systems Read Me First (GI11-0949-00)

Accessing publications online


The publications for this product are available online in Portable Document Format (PDF) or Hypertext Markup Language (HTML) format, or both in the Tivoli Software Library: http://www.ibm.com/software/tivoli/library

Preface

xi

To locate product publications in the library, click the Product manuals link on the left side of the Library page. Then, locate and click the name of the product on the Tivoli Software Information Center page. Product publications include release notes, installation guides, users guides, administrators guides, and developers references. Note: To ensure proper printing of PDF publications, select the Fit to page check box in the Adobe Acrobat Print window (which is available when you click File Print).

Ordering publications
You can order many IBM Tivoli publications online at: http://www.elink.ibmlink.ibm.com/public/applications/ publications/cgibin/pbi.cgi You can also order by telephone: v In the United States: 800-879-2755 v In Canada: 800-426-4968 v In other countries, for a list of telephone numbers, see http://www.ibm.com/software/tivoli/order-lit/

Accessibility
Accessibility features help a user who has a physical disability, such as restricted mobility or limited vision, to use software products successfully. With this product, you can use assistive technologies to hear and navigate the interface. You also can use the keyboard instead of the mouse to operate all features of the graphical user interface.

Contacting software support


Before contacting IBM Tivoli Software support with a problem, refer to the IBM Tivoli Software support Web site at: http://www.ibm.com/software/sysmgmt/products/support/ If you need additional help, contact software support by using the methods described in the IBM Software Support Guide at the following Web site: http://techsupport.services.ibm.com/guides/handbook.html The guide provides the following information: v Registration and eligibility requirements for receiving support v Telephone numbers and e-mail addresses, depending on the country in which you are located v A list of information you should gather before contacting customer support

Conventions used in this book


This reference uses several conventions for special terms and actions and for operating system-dependent commands and paths.

Typeface conventions
The following typeface conventions are used in this reference:

xii

IBM Tivoli Access Manager: WebSEAL Developers Reference

Bold

Lowercase commands or mixed case commands that are difficult to distinguish from surrounding text, keywords, parameters, options, names of Java classes, and objects are in bold. Variables, titles of publications, and special words or phrases that are emphasized are in italic.

Italic

Monospace Code examples, command lines, screen output, file and directory names that are difficult to distinguish from surrounding text, system messages, text that the user must type, and values for arguments or command options are in monospace.

Operating system differences


This book uses the UNIX convention for specifying environment variables and for directory notation. When using the Windows command line, replace $variable with %variable% for environment variables and replace each forward slash (/) with a backslash (\) in directory paths. If you are using the bash shell on a Windows system, you can use the UNIX conventions.

Preface

xiii

xiv

IBM Tivoli Access Manager: WebSEAL Developers Reference

Part 1. CDAS Developer Reference


Chapter 1. CDAS overview . . . . . . . . . Introducing the CDAS . . . . . . . . . . . Supported authentication methods . . . . . . Enabling dynamic business entitlements . . . . CDAS authentication models . . . . . . . . . The single authentication CDAS model . . . . The credential extended attributes CDAS chaining model . . . . . . . . . . . . . . . 3 3 4 5 5 5 6

Chapter 2. Implementing a custom CDAS library . 9 CDAS and External Authentication API components 9 Header files . . . . . . . . . . . . . 10 Software requirements for implementing a custom CDAS . . . . . . . . . . . . 10 Using the external authentication C API functions 10 Initialization: xauthn_initialize() . . . . . . 10 Shutdown: xauthn_shutdown() . . . . . . . 11 Authentication: xauthn_authenticate(). . . . . 11 Password change: xauthn_change_password() . . 11 Valid user authentication data . . . . . . . . 11 Returning the client identity (xauthn_identity_t) . . 14 Specifying extended attributes . . . . . . . . 14 Building the custom library . . . . . . . . . 15 Writing a CDAS for switch user . . . . . . . 16 Writing a CDAS for post password change processing . . . . . . . . . . . . . . . 18 Chapter 3. Configuring WebSEAL to use a CDAS Configuring and installing the custom CDAS library Additional configuration for an extended attributes CDAS . . . . . . . . . . . . Using the example library . . . . . . . . . 19 19 20 20

Copyright IBM Corp. 1999, 2002

IBM Tivoli Access Manager: WebSEAL Developers Reference

Chapter 1. CDAS overview


The IBMTivoliAccess Manager WebSEAL Cross-domain Authentication Service (CDAS) is a library mechanism that allows you to substitute the default WebSEAL authentication mechanism with a custom process that ultimately returns a Tivoli Access Manager identity to WebSEAL. In addition, a secondary (chained) CDAS can be called to supply extended attribute data (business entitlements) for inclusion in the users credential. You use the resources of the Tivoli Access Manager External Authentication C API (Appendix A) to customize a CDAS library. Topic Index: v Introducing the CDAS on page 3 v CDAS authentication models on page 5

Introducing the CDAS


WebSEAL provides a set of default authentication mechanismsin the form of built-in librariesto support clients who access WebSEAL via username and password, client-side certificate, token passcode, IP address, or HTTP header. For authentication to succeed, these clients must be members of a Tivoli Access Manager LDAP user registry. The Cross-domain Authentication Service (CDAS) allows you to substitute the default built-in WebSEAL authentication mechanism with a highly flexible library mechanism that allows custom handling and processing of extended attribute and client authentication information. The Tivoli Access Manager External Authentication C API provides you with the necessary resources to build your own custom CDAS library that can handle your extended attribute and authentication requirements. A CDAS can return a Tivoli Access Manager identity to WebSEAL for authentication against an Tivoli Access Manager user registry. You can customize the CDAS library to handle authentication data and extended attribute data according to your security requirements: v The custom CDAS can process authentication data internally and return a Tivoli Access Manager identity. v The custom CDAS can direct authentication data to be processed by an external authentication mechanism and third-party registry. A Tivoli Access Manager identity is returned to WebSEAL. This method allows you to authenticate clients who are not direct members of the Tivoli Access Manager secure domain. v The custom CDAS can add extended attribute information (known as business entitlements) to the users Tivoli Access Manager credential. These business entitlements can be extracted from the credential directly using the authorization API or inserted in the HTTP headers of requests directed across a junction to a back-end application server.

Copyright IBM Corp. 1999, 2002

The basic steps for implementing a custom CDAS library include: 1. Identify the type of authentication method and data that you want to process 2. Build a custom library using the External Authentication C API 3. Configure WebSEAL to use the custom library for the specified data Both standard built-in and custom libraries load directly into WebSEAL memory and run as part of the WebSEAL process.

Supported authentication methods


You use the [authentication-mechanisms] stanza of the webseald.conf configuration file to configure supported authentication data types and implementation mechanisms. Examples of authentication data types include digital certificates, username and password, and token passcode. Examples of implementation mechanisms include the standard libraries included with WebSEAL and custom-built libraries. In the webseald.conf configuration file, you represent the supported authentication data with an identifier parameter. You specify the implementation mechanism with the name of the library (built-in or custom):
<authentication-mechanism-parameter> = <library-name>

The following identifiers specify local built-in libraries: v passwd-ldap v cert-ssl This library handles digital certificates. For more information on WebSEALs use of digital certificates, see Chapter 5 of the IBM Tivoli Access Manager WebSEAL Administrators Guide. token-cdas http-request sso-create sso-consume

v v v v

v switch user parameters v failover cookie parameters failover-password failover-token-card failover-certificate failover-http-request failover-cdsso

Note: WebSEAL uses failover cookies to maintain session state, including authentication information, across replicated servers. Refer to Chapter 5 of the IBM Tivoli Access Manager WebSEAL Administrators Guide for complete details regarding WebSEALs use of failover cookies. The following additional identifiers (and any of the identifiers listed above) can be used to specify custom libraries for external CDAS servers: v passwd-cdas v cred-ext-attrs (used for a chained extended attributes CDAS library)

IBM Tivoli Access Manager: WebSEAL Developers Reference

Note: Refer to Chapter 5 of the IBM Tivoli Access Manager WebSEAL Administrators Guide for complete details regarding WebSEAL authentication.

Enabling dynamic business entitlements


Business enterprises and their partners often have the need to share common entitlements such as partner data (in a business-to-business relationship) or customer data (in a business-to-customer relationship). Through an extension of the Cross-domain Authentication Service (CDAS), Tivoli Access Manager provides a flexible mechanism that allows you to place entiltlement information, in the form of extended attributes, into user credentials at the point of authentication. These business entitlements can be used in any situation where this data is required. For example, entitlement data can be extracted from the credential directly by an application using the authorization API or inserted in the HTTP headers of requests directed across a junction to a back-end application server. There are two methods you can use to supply business entitlement data to a user credential: v A single custom CDAS can be written to perform the authentication operation and, additionally, supply the extended attribute data. The authentication CDAS is specified by an authentication mechanism identifier parameter in the webseald.conf configuration file, as described in the previous section. For more details on configuring an authentication mechanism, refer to the IBM Tivoli Access Manager WebSEAL Administrators Guide. v A second custom CDAS can be written to supply extended attribute data. In this scenario, the authentication operation is performed by a built-in authentication mechanism or a custom CDAS. The second CDAS is then called to supply extended attribute data for inclusion in the user credential (CDAS chaining). This credential extended attributes CDAS is specified by the cred-ext-attrs identifier in the webseald.conf configuration file. See Additional configuration for an extended attributes CDAS on page 20

CDAS authentication models


The custom CDAS library must be written by the application developer. In addition, you must configure WebSEAL to recognize the specific type of authentication data being passed to the CDAS mechanism. When WebSEAL receives a client request, it passes the appropriate authentication data to the custom library as a list of name/value pairs. For example, if the CDAS library is written to handle username and password authentication, the client authentication data must contain the users name and the users password. However, if the library is written to handle certificate authentication, the data must contain the clients certificate, the distinguished name (DN) of the certificate, and the DN of the certificate issuer.

The single authentication CDAS model


The following diagram illustrates an example of the single authentication CDAS functionality. The individual numbered steps are described below the diagram:

Chapter 1. CDAS overview

WebSEAL
authentication information

User Registry

1 Client
authn info

Resource Manager
External Registry

4
identity

Custom CDAS Shared Library

External Authentication Service

Figure 1. Example CDAS authentication model

1. The client supplies authentication information to WebSEAL. 2. In this example, WebSEAL is configured to use a custom CDAS library to handle this type of authentication data. The CDAS library could authenticate this user internally and pass the resulting Tivoli Access Manager identity back to WebSEAL (Step 4). For example, the library could accept a digital certificate, modify the Distinguished Name (DN) data, and return the modified DN as the Tivoli Access Manager identity. 3. The custom library could instead send the data to an external authentication service that performs its own authentication of the client, perhaps using a third-party (legacy) user registry. 4. The CDAS returns to WebSEAL either: a. A successful status code (indicating a successful authentication attempt) and a Tivoli Access Manager user identity. b. An unsuccessful status code, indicating a failed authentication attempt. In addition, the custom CDAS can be written to provide extended attribute data to WebSEAL (for inclusion in the user credential). 5. Creating the user credential: a. For a successful status code, WebSEAL tries to match the user identity with an entry in the Tivoli Access Manager user registry (LDAP). If a match is found, WebSEAL treats the client as authenticated. Otherwise, it treats the client as unauthenticated. b. For an unsuccessful status code, WebSEAL automatically treats the client as unauthenticated. A successful authentication results in a Tivoli Access Manager credential for the user. Any extended attribute data is included in the credential and can be extracted later for appropriate use. The credential allows the user to participate in the Tivoli Access Manager secure domain.

The credential extended attributes CDAS chaining model


A second CDAS module can be chained to a built-in or custom CDAS authentication module. The initial authentication module (built-in or custom CDAS) is responsible for creating the Tivoli Access Manager identity and can optionally (in the case of a custom CDAS) include extended attribute data. The second CDAS in the chain is used only to add extended attribute data.

IBM Tivoli Access Manager: WebSEAL Developers Reference

If Tivoli Access Manager successfully authenticates the identity received from the CDAS chain, a credential is built for the user that includes the identity information and the extended attribute data. The following diagram illustrates an example of the CDAS chain functionality. The individual numbered steps are described below the diagram:

WebSEAL
External Registry

Authentication Module
(built-in or CDAS libraries)

3 External Authentication Service

2 1 Client
authn info

4
identity

authentication information

Resource Manager 7 5
identity and authn info

6
identity and attributes build credential

User Registry

Extended Attributes CDAS

Figure 2. Example extended attributes CDAS model

1. The client supplies authentication information to WebSEAL. 2. In this example, WebSEAL is configured to use a custom CDAS library to handle this type of authentication data. The CDAS library could authenticate this user internally and pass the resulting Tivoli Access Manager identity back to the resource manager (Step 4). For example, the library could accept a digital certificate, modify the Distinguished Name (DN) data, and return the modified DN as the Tivoli Access Manager identity. 3. The custom library could instead send the data to an external authentication service that performs its own authentication of the client, perhaps using a third-party (legacy) user registry. 4. The Tivoli Access Manager identity is then passed to the resource manager. 5. The PD identity (and the original authentication information) is passed to the second CDAS which is written to provide extended attribute data. 6. The extended attributes CDAS returns to WebSEAL either: a. A successful status code (indicating a successful authentication attempt) and a Tivoli Access Manager user identity (plus attributes). b. An unsuccessful status code, indicating a failed authentication attempt. 7. Creating the user credential: a. For a successful status code, WebSEAL tries to match the user identity with an entry in the Tivoli Access Manager user registry (LDAP). If a match is found, WebSEAL treats the client as authenticated. Otherwise, it treats the client as unauthenticated.

Chapter 1. CDAS overview

b. For an unsuccessful status code, WebSEAL automatically treats the client as unauthenticated. A successful authentication results in a Tivoli Access Manager credential for the user. The extended attribute data is included in the credential and can be extracted later for appropriate use. The credential allows the user to participate in the Tivoli Access Manager secure domain.

IBM Tivoli Access Manager: WebSEAL Developers Reference

Chapter 2. Implementing a custom CDAS library


The specific operation of a customized authentication and mapping service are determined entirely by the CDAS developer. It is the responsibility of the developer to use the resources of the External Authentication C API (Appendix A) to implement the authentication and data handling requirements of a particular application. Topic Index: v CDAS and External Authentication API components on page 9 v v v v v v v Using the external authentication C API functions on page 10 Valid user authentication data on page 11 Returning the client identity (xauthn_identity_t) on page 14 Specifying extended attributes on page 14 Building the custom library on page 15 Writing a CDAS for switch user on page 16 Writing a CDAS for post password change processing on page 18

CDAS and External Authentication API components


The WebSEAL CDAS and External Authentication C API can be found in the PDWebADK package (part of PDWeb) and consists of the following components: v v v v v API header files API library (utility functions) Source file Example pre-built CDAS library file (for demonstration only) Makefiles (for building custom libraries)

The CDAS and External Authentication C API components are located in a directory named pdxauthn_adk. The API components are contained in the following subdirectories:
Directory include lib Contents This directory contains the C header files. See Header files on page 10. This directory contains the CDAS authentication static library files: - UNIX systems: libpdxauthn.a - Windows systems: pdxauthn.lib The example directory contains: - Source file (xauthn.c) for customization - Makefile - A pre-built platform-specific example library to demonstrate a functional CDAS.

example

Copyright IBM Corp. 1999, 2002

Header files
The following header files are contained in the include directory.
Files pdxauthn.h xnvlist.h xattr.h Contents Definition of function prototypes, client identity, and error codes used for authentication API functions User authentication data structure utility functions User extended attributes data structure utility functions

Software requirements for implementing a custom CDAS


The WebSEAL ADK provides all the necessary resources for CDAS application development. The minimum installation for CDAS application development consists of a single system with the following Tivoli Access Manager components (installed in the order listed): v Tivoli Access Manager Runtime (PDRTE) v v v v Tivoli Access Tivoli Access Tivoli Access Tivoli Access Manager Manager Manager Manager policy server (PDMgr) authorization ADK (PDAuthADK) WebSEAL (PDWeb) WebSEAL ADK (PDWebADK)

(For instructions regarding installation and configuration of Tivoli Access Manager components, please refer to the IBM Tivoli Access Manager Base Installation Guide and the IBM Tivoli Access Manager WebSEAL Installation Guide.)

Using the external authentication C API functions


You create a custom CDAS library by first customizing the xauthn.c source file located in the example sub-directory of the WebSEAL External Authentication ADK (pdxauthn_adk). A custom CDAS library must implement each of the following four External Authentication C API functions: v Initialization: xauthn_initialize() v Shutdown: xauthn_shutdown() v Authentication: xauthn_authenticate() v Password change: xauthn_change_password()

Initialization: xauthn_initialize()
WebSEAL loads the CDAS library and initializes it by calling xauthn_initialize(). This function contains the argc and argv parameters. These parameters contain the values specified in the library definition located in the webseald.conf configuration file. The library definition uses the following syntax:
<authn-mechanism-parameter> = <library-name>[&arg1]...[ argN]

The library definition defines all entries after the ampersand character (&) to be initialization parameters. Unlike the C language argv, the argv[0] array entry is the first parameter. For more information, see the reference page for xauthn_initialize().

10

IBM Tivoli Access Manager: WebSEAL Developers Reference

Shutdown: xauthn_shutdown()
During shutdown, WebSEAL calls the xauthn_shutdown() interface to stop the CDAS library process. Note: The shutdown interface is not functional in Tivoli Access Manager 4.1. It exists for future development and implementation. The xauthn_shutdown() interface is called with the same argc and argv parameters that were passed to the xauthn_initialize() interface when the library was first initialized. For more information, see the reference page for xauthn_shutdown().

Authentication: xauthn_authenticate()
Once the CDAS library is configured, WebSEAL passes the client request to the library through the xauthn_authenticate() interface. User authentication information is passed to this interface in a name/value data list (xnvlist_t). The content of the name/value data list can vary and is specific to the configured authentication method. Valid user authentication data on page 11 lists the possible client authentication data handled by the library. The xauthn_authenticate() interface performs the application-specific authentication process based on the authentication information found in the data list, and returns the resulting client identity (xauthn_identity_t) to WebSEAL. It is important to note that the client identity returned through this interface can contain additional user information. For more information, see the reference page for xauthn_authenticate().

Password change: xauthn_change_password()


This interface allows the user to make changes to the account password that is stored in the third-party user registry. Only the username and password authentication method supports this function. If the external authentication mechanism you are going to implement does not support password changes, this function should return:
XAUTHN_S_UNSUPPORTED_AUTHN_METHOD

User authentication information is passed to this interface in a name/value data list (xnvlist_t). The data list contains the users name, the old password, and the new password. Valid user authentication data on page 11 lists the possible parameters passed to this function. For more information, see the reference page for xauthn_change_password().

Valid user authentication data


WebSEAL can pass a variety of client authentication information to the library. 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 by using the utility function xnvlist_get().
Chapter 2. Implementing a custom CDAS library

11

For more information on retrieving values from xnvlist_t, see the reference page for xnvlist_get(). The following tables display the identifiers that are passed to the library by the WebSEAL authentication service. The actual identifiers passed down depend on the type of authentication methods. Some identifiers are common to all authentication methods. These are identified in Table 1. The identifiers that are specific to each authentication method are displayed in the other tables that follow.
Table 1. Identifiers common to all authentication methods Name xauthn_browser_info Description Browser information Example: "Mozilla/4.0 (Compatible; MSIE 6.0; Windows NT 5.0)" Authentication methods: all xauthn_existing_cred Used only for reauthentication. This contains the users existing credential as a string. Example: 0123456 Authentication methods: all xauthn_ipaddr User IP address. For example: 11.22.33.44 Authentication methods: all xauthn_qop Quality of protection. The format is authentication_method:version:cipher_used Examples: "x509:TLSv1:04" "SSK:SSVV3:05" Authentication methods: all Table 2. Identifiers for username-password authentication Name xauthn_username Description User name. Example: testuser Authentication method: Usernamepassword or token card. xauthn_password User password Authentication method: Usernamepassword xauthn_new_password User new password. Used only for the xauthn_change_password() function. Authentication method: Usernamepassword

12

IBM Tivoli Access Manager: WebSEAL Developers Reference

Table 3. Identifiers for X.509 certificate authentication Name xauthn_cert Description The certificate body, in DER format. Example: (binary data) Authentication method: X.509 certificate xauthn_cert_dn The certificates DN. Example: cn=testuser,o=tivoli,c=us Authentication method: X.509 certificate xauthn_cert_issuer_dn The issuers (certificate authority) DN. Example: MAIL=issuer@mail.com CN=issuer,o=tivoli,c=sus Authentication method: X.509 certificate Table 4. Identifier for token card authentication Name xauthn_token Description User token (passcode). This functions like a password. Example: 0123 Authentication method:Token card. Table 5. Identifiers for single sign-on token authentication Name xauthn_sso_type Description This is a string that is created and freed by WebSEAL. This is passed down to the calling library to inform it whether it was called to use the create function or the consume function. This is important when both token creation and token consumption are written into the same library. For more information, see Chapter 7, Creating a custom CDSSO library, on page 51. Values can be xauthn.sso.create or xauthn.sso.consume. Authentication method: SSO xauthn_input_url Destination URL. . Example: http://foo.com/request.htm Authentication method: SSO

Chapter 2. Implementing a custom CDAS library

13

Table 6. HTTP header authentication methods Name Request-URI Description The request URI. This name is a literal string, not a variable. Example: Authentication method: HTTP header. Header-name HTTP header name. The format of the xnvlist_t data structure differs for the HTTP header authentication method. The <header-name> stored in xnvlist_t is the header name specified in the [auth-headers] stanza of the webseald.conf configuration file. The value is the authentication information passed via that header. Authentication method: HTTP header.

Returning the client identity (xauthn_identity_t)


The CDAS library is required to return the resulting client identity back to WebSEAL. The client identity is defined by the xauthn_identity_t data structure. This structure is returned by xauthn_authenticate(). See the reference pages for xauthn_identity_t and xauthn_authenticate().

Specifying extended attributes


The Tivoli Access Manager CDAS allows you to add extended attribute data (business entitlements) to a user credential. These business entitlements can be used in any situation where this type of data is required. For example, entitlement data can be extracted from the credential directly by an application using the Authorization API or inserted in the HTTP headers of requests directed across a junction to a back-end application server. The structure of the returned client identity (xauthn_identity_t) allows you to specify extended attribute information. This additional information becomes part of the resulting Tivoli Access Manager credential. You define extended attribute information with the xattr_list_t data structure. Extended attributes must be added to the credential at the time of authentication. The extended 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 via a call to the xattr_set() function and can be retrieved using the xattr_get() function. In order for WebSEAL to recognize the extended attribute as tag/value data, the tag name is prefixed with the macro XAUTHN_TAG_VALUE_PREFIX, which is defined as tagvalue_. The following section of the xauthn.c demo program illustrates this action:
char *tag = (char *) malloc(1024+XAUTHN_TAG_VALUE_KEY_PREFIX+1); char *tag_data = (char *) malloc(1024);

14

IBM Tivoli Access Manager: WebSEAL Developers Reference

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 supply tag/value data (business entitlements) in a custom CDAS:
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 */ }

Building the custom library


You build the CDAS library by running a compiler called by the make command against the customized source file xauthn.c. When compiling the library, make sure you add the include directory of the ADK to the compiler command line. When linking the library, make sure you include the appropriate pdxauthn library (see CDAS and External Authentication API components on page 9). The ADK has provided a generic Makefile template named Makefile.in under the example directory. You can use the Makefile to compile the required library with minimum changes. Details on how to use the Makefile.in template are included inside the template itself.

Chapter 2. Implementing a custom CDAS library

15

Writing a CDAS for switch user


An existing CDAS authentication mechanism often returns additional information about the user that is incorporated into the users credential. If you are using the switch user feature in such an environment, you must write a special switch user CDAS that emulates the behavior of your existing CDAS while supporting the requirement of returning a credential without requiring the user password for input. The Tivoli Access Manager CDAS provides a set of identity components that can be used to pass client authentication information to the switch user CDAS library. This 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 by using the utility function xnvlist_get(). The following switch-user authentication methods are supported: v Switch user password v Switch user token card v Switch user certificate v Switch user HTTP request v Switch user CDSSO The following authentication data identifiers are valid for all of the switch-user authentication methods:
Table 7. Valid identifiers for switch-user authentication methods Identifiers for switch-user authentication methods Name xauthn_su_method Value Specifies the type of switch-user authentication method. Must be one of the following values: v su-password Usernamepassword 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 sign-on authentication. xauthn_admin_name The user name of the administrator attempting to switch user Example: sec_master

16

IBM Tivoli Access Manager: WebSEAL Developers Reference

Table 7. Valid identifiers for switch-user authentication methods (continued) xauthn_admin_cred The credential of the administrator attempting to switch user, as a string The xauthn_admin_cred entry in the xnvlist_t authentication data structure contains an encoded Tivoli Access Manager credential. Use the xauthn_util_entry_to_creds() function to access the credential. An example of how to use the function is included in the sample xauthn source code included in the PDWebADK package. xauthn_existing_cred During reauthentication, the credential of the switched-to user, as a string The xauthn_existing_cred entry in the xnvlist_t authentication data structure contains an encoded Tivoli Access Manager credential. Use the xauthn_util_entry_to_creds() function to access the credential. An example of how to use the function is included in the sample xauthn source code included in the PDWebADK package. xauth_username The user name of the switched-to user Example: test-user xauthn_ipaddr Administrator IP address This data is supplied for any CDAS that must perform additional validations of the administrators account.For example: 11.22.33.44 xauthn_qop Administrator quality of protection. The format is authentication_method:version:cipher_used Examples: "x509:TLSv1:04" "SSK:SSVV3:05" This data is supplied for any CDAS that must perform additional validations of the administrators account. xauthn_browser_info Administrator browser information This data is supplied for any CDAS that must perform additional validations of the administrators account. Example: "Mozilla/4.0 (Compatible; MSIE 6.0; Windows NT 5.0)"

Chapter 2. Implementing a custom CDAS library

17

Writing a CDAS for post password change processing


WebSEAL provides support for customized post password change processing. A CDAS authentication module can be written to be called after a password is successfully changed through WebSEAL by using the pkms password change page. This feature enables passwords in external user registries, which may be unknown to Tivoli Access Manager, to be updated with passwords that the user changed during the course of attempting authentication when challenged by WebSEAL. When a users password is successfully changed, WebSEAL checks the authentication mechanism that is in use to see if it is enabled for post password change processing. When it is enabled, WebSEAL loads the shared library containing the custom CDAS and calls it. The post password change module uses the external authentication interface. The CDAS 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 an input parameter. The xnvlist_t contains the following data: v Name of the user who needs the password to be changed v Users current password v Users new password Note that the post password change processing module does not call xauthn_authenticate(). User authentication is done through the default WebSEAL authentication mechanism. The password change occurs after authentication is complete, and the post password change processing occurs after the user has supplied a new password. The post password change processing module returns status to WebSEAL. WebSEAL audits the return status but does not take action based on it. The implementor of the CDAS must handle any error conditions that arise, or that are passed back to the post password change module. When a users password change returns successfully to the default configured authentication mechanism in Tivoli Access Manager, then a status of password change success is returned to the user. This occurs no regardless of the return status from the post password change processing module.

18

IBM Tivoli Access Manager: WebSEAL Developers Reference

Chapter 3. Configuring WebSEAL to use a CDAS


By default, WebSEAL is set to authenticate clients over SSL using built-in support for Basic Authentication (BA) user names and passwords (LDAP user registry). WebSEAL contains other built-in authentication mechanisms that support authentication via client-side certificates, Forms, token passcode, HTTP header, and IP address. You can also configure WebSEAL to accept the following authentication data types that are handled by a custom CDAS. Examples include: v Username and password belonging to a third-party user registry v Client-side certificate v Token passcode v HTTP header v IP address v Single sign-on (create and consume libraries) If you require a custom CDAS, you must configure WebSEAL to recognize the specific authentication information type and process that information via the custom library. This chapter discusses the specific configuration steps you must perform so that WebSEAL can use the CDAS interface. Topic Index: v Configuring and installing the custom CDAS library on page 19 v Using the example library on page 20

Configuring and installing the custom CDAS library


Perform the following steps to configure WebSEAL to use a custom CDAS library: 1. Enter the appropriate authentication identifier parameter, with the name of the library, in the [authentication-mechanisms] stanza of the webseald.conf configuration file. See Supported authentication methods on page 4. For example, if you want to externalize LDAP username/password authentication using a custom library named libxauthn.so (for a Solaris system), enter the following line:
[authentication-mechanisms] passwd-ldap = libxauthn.so

2. If the custom library accepts any arguments during initialization and shutdown, they can be specified in the following format (using the libxauthn.so library as an example):
passwd-ldap = libxauthn.so&<arg1> <arg2> .... <argN>

3. Copy the custom library to the WebSEAL lib directory. For example, using the sample library provided with the ADK for Solaris (libxauthn.so):
# cp <build-dir>/libxauthn.so /opt/pdweb/lib

4. Additionally, ensure that this custom library file has both read and execute operating system file permissions for the ivmgr user. 5. Restart WebSEAL (webseald).
Copyright IBM Corp. 1999, 2002

19

Additional configuration for an extended attributes CDAS


CDAS chaining allows a second CDAS module to be called after the initial authentication module (built-in or custom CDAS) for the purpose of adding extended attribute data to the Tivoli Access Manager identity. Typically, the Tivoli Access Manager identity is obtained via a standard built-in authentication module. The secondary custom CDAS provides the additional extended attribute data. 1. Use the cred-ext-attrs parameter in the [authentication-mechanisms] stanza of the webseald.conf configuration file to specify the custom library for the secondary CDAS module. For example (for a Solaris system):
cred-ext-attrs = libxauthn2.so

2. Arguments can be specified as discussed in the previous section.

Using the example library


The Tivoli Access Manager CDAS comes with an example (demonstration) library that implements a generic username and password CDAS authentication mechanism. The sample library is an interactive program that displays all the available client authentication data and prompts for a user identity. In addition, the example library can be used as an extended attributes CDAS. 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 CDAS ADK package. To use the sample library, configure WebSEAL as described in Configuring and installing the custom CDAS library on page 19. Then execute WebSEAL (webseald) in the foreground. For example (on a Solaris system):
# /opt/pdweb/bin/webseald -foreground

The program user interfacefor client authentication dataappears as follows:


--------------------------------------------------------Access Manager WebSEAL Version 4.1 (Build 010904) Copyright (C) IBM Corporation 2000-2002 All Rights Reserved. ============================== User Authentication Information: ============================== xauthn_username: charles (7) xauthn_password: abcdefgh (8) xauthn_ipaddr: 127.0.0.1 (9) xauthn_qop: SSK: SSLV3: 04 (14) xauthn_browser_info: Mozilla/4.7 [en] (WinNT; U) (27) Enter the user identity: testuser ---------------------------------------------------------

The user identity (testuser in the example above) is returned to WebSEAL. The program user interfacefor tag/value dataappears as follows:
--------------------------------------------------------Access Manager WebSEAL Version 4.1 (Build 010904) Copyright (C) IBM Corporation 2000-2002 All Rights Reserved. ============================== User Authentication Information: ==============================

20

IBM Tivoli Access Manager: WebSEAL Developers Reference

xauthn_username: charles (7) xauthn_password: abcdefgh (8) xauthn_ipaddr: 127.0.0.1 (9) xauthn_qop: SSK: SSLV3: 04 (14) xauthn_browser_info: Mozilla/4.7 [en] (WinNT; U) (27) Using existing name: testuser Enter the test tag: <tag> Enter the test tag data: <value> ---------------------------------------------------------

Chapter 3. Configuring WebSEAL to use a CDAS

21

22

IBM Tivoli Access Manager: WebSEAL Developers Reference

Part 2. CDMF Developer Reference


Chapter 4. Using a CDMF library . . . . . . Introducing the Cross-domain Mapping Framework Using CDMF in a CDSSO environment . . . . Using CDMF in an e-community environment. . CDMF API components . . . . . . . . . . Software requirements . . . . . . . . . . Implementing the CDMF library . . . . . . . The CDMF library partnership . . . . . . . Customizing the CDMF library . . . . . . . . Providing user attributes: cdmf_get_usr_attributes() . . . . . . . . . Providing identity mapping: cdmf_map_usr() . . Naming the custom library . . . . . . . . Specifying extended attributes . . . . . . . . Chapter 5. CDMF C API reference Summary: CDMF API functions and cdmf_map_usr() . . . . . . . cdmf_get_usr_attributes() . . . . cdmf_create_usr_attr_list() . . . cdmf_create_usr_attr() . . . . . cdmf_add_value_to_attr(). . . . cdmf_add_attr_to_list() . . . . CDSSO_STRDUP() . . . . . . CDSSO_MALLOC() . . . . . CDSSO_FREE() . . . . . . . CDSSO_REALLOC() . . . . . . . . macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 25 25 26 26 27 27 28 28 28 29 29 29

. . . 31 . . . 31 . . . 33 . . . 35 . . . 36 . . . 37 . . . 38 . . . 39 . . . 40 . . . 41 . . . 42 . . . 43

Copyright IBM Corp. 1999, 2002

23

24

IBM Tivoli Access Manager: WebSEAL Developers Reference

Chapter 4. Using a CDMF library


The specific operation of a customized CDMF library is determined entirely by the developer. It is the responsibility of the developer to use the CDMF API functions and utilities to implement the required cross domain identity mapping and extended user attribute handling. Topic Index: v Introducing the Cross-domain Mapping Framework on page 25 v CDMF API components on page 26 v Implementing the CDMF library on page 27 v Customizing the CDMF library on page 28 v Specifying extended attributes on page 29

Introducing the Cross-domain Mapping Framework


The Cross-domain Mapping Framework (CDMF) is a programming interface you can use to build a custom library that provides mapping services for a user identity and handles any extended user attributes. The CDMF is an important component used with the two Tivoli Access Manager cross domain single sign-on solutions: v Cross-domain Single Sign-on (CDSSO) v E-community Single Sign-on

Using CDMF in a CDSSO environment


The Tivoli Access Manager Cross-domain Single Sign-on (CDSSO) provides a mechanism for transferring user credentials across multiple secure domains. CDSSO allows Web users to perform a single sign-on and move seamlessly between two separate secure domains. CDSSO supports the goals of scalable network architecture by allowing the integration of multiple secure domains. For example, a large corporate extranet can be set up with two or more unique domainseach with its own users and object space. CDSSO allows movement of users between the domains with a single sign-on. When a user makes a request to a resource located in another domain, the CDSSO mechanism transfers an encrypted user identity token from the first domain to the second domain. The second domain now has the users identity (as authenticated in the first domain) and the user is not forced to perform another login. In many CDSSO scenarios, the default one-to-one mapping between users from different domains may not suit all deployment requirements. The CDMF allows the mapping of a remote user to a local user identity. For CDSSO background, administration, and configuration information, refer to the IBM Tivoli Access Manager WebSEAL Administrators Guide.

Copyright IBM Corp. 1999, 2002

25

Using CDMF in an e-community environment


E-community single sign-on is another implementation of cross-domain authentication in a Tivoli Access Manager environment. The goal of cross-domain authentication is to allow users to access resources across multiple servers in multiple domains without re-authentication. An e-community is a group of distinct domains (Tivoli Access Manager or DNS) that participate in a business relationship. These participating domains can be configured as part of one business (and perhaps using different DNS names for geographic reasons), or as disparate businesses with a shared relationship (for example, company headquarters, a life insurance company, and a financial management company). Authentication information about the users who participate in the e-community (including the user names and passwords used for authentication) is maintained in the home domain. This arrangement allows a single point of reference for administration issues, such as help desk calls within the e-community that all refer to the home domain. Individual e-community domains manage their own user identities and associated privileges. You can use the CDMF to map a user from a remote domain to a valid user in the local domain. If the e-community domains share global identities, this mapping function is not required. For e-community background, administration, and configuration information, refer to the IBM Tivoli Access Manager WebSEAL Administrators Guide.

CDMF API components


The CDMF API can be found in the PDWebADK package (part of PDWeb) and consists of the following components: v v v v API library (CDMF API and utility functions) API header file Demonstration (example) CDMF file Makefiles

The CDMF components are located in a directory named cdmf_adk. The following table lists the files included in this directory:
Files cdmf.c.skeleton Description The source file that can be customized by the developer to implement the CDMF logic. This file needs to be renamed to cdmf.c and then compiled and linked into the CDMF library. Example cdmf.c file This example performs a simple user mapping and performs some manipulation of the CDSSO attribute lists. The header file for cdmf.c. The header file providing utility functions for manipulating extended user attribute lists. The header file that provides definitions of types and macros used in cdmf.c.

cdmf.c.example

cdmf.h cdmf_utils.h cdssotypes.h

26

IBM Tivoli Access Manager: WebSEAL Developers Reference

Files Windows only: cdmf_utils.lib Makefile.win32 UNIX only: libcdmfutils. (so, a, sl)

Description

The library for the utility functions in cdmf_utils.h. The nmake Makefile used to build the custom CDMF library.

The library for the utility functions defined in cdmf_utils.h. - .so for Solaris - .a for AIX - .sl for HP-UX The template Makefile used to build the CDMF library. Change this file to suit your platform.

Makefile.cdmf.in

Software requirements
There are no software dependencies when building the CDMF library. To use a CDMF library, you must have at least two Tivoli Access Manager secure domains installed, each containing a WebSEAL server.

Implementing the CDMF library


1. Edit the cdmf.c.skelton source file and modify the cdmf_map_usr and cdmf_get_usr_attributes functions to enable the required user mapping and user attribute handling. 2. Rename the modified cdmf.c.skeleton file to cdmf.c. 3. For UNIX platforms, edit Makefile.cdmf.in and make any modifications required to build the library for the appropriate development platform. Instructions appear in the comments at the top of the file. For Windows platforms, Makefile.win32 requires no modification. 4. Build the custom CDMF library. Provide the following platform-specific name for the library file:
Solaris AIX HP-UX Windows libcdmf.so libcdmf.a libcdmf.sl cdmf.dll

See Customizing the CDMF library on page 28 Note: If you build the CDMF library on a Solaris system using C++ and Sun Workshop 5 or greater, the library must be built with the compat=4 flag. 5. Stop the WebSEAL server process (webseald). 6. Replace the original CDMF library that was shipped with the Tivoli Access Manager product with the customized version. 7. Start webseald.

Chapter 4. Using a CDMF library

27

The CDMF library partnership


Two CDMF libraries always work as partners. One CDMF libraryassociated with the local WebSEAL server (CDSSO) or the vouch for server (e-community)supplies extended attributes in the authentication token (CDSSO) or vouch for reply token (e-community). The second CDMF library, which is written as a partner to the first, performs the following operations: v Expects possible extended attributes. v Maps the remote user identity to a local user identity. The second CDMF library is associated with the WebSEAL server in the remote domain that is the target of the request.

Customizing the CDMF library


The custom CDMF library must contain two application programming interfaces. The first interface, called by the local WebSEAL server (CDSSO) or the vouch for server (e-community), serves the request by providing extended user attribute information. The second interface is called by the WebSEAL server in the remote domain (CDSSO) or the target WebSEAL server (e-community) and provides user identity mapping services for the request. v Providing user attributes: cdmf_get_usr_attributes() v Providing identity mapping: cdmf_map_usr()

Providing user attributes: cdmf_get_usr_attributes()


The cdmf_get_usr_attributes() interface allows extended user attributes to be passed in the authentication token (CDSSO) or the vouch for reply token (e-community) and is called by WebSEAL in the following situations: v When a CDSSO request is initiated by a user accessing the /pkmscdsso page on the local WebSEAL server. v When an e-community vouch for server generates a vouch for reply token for another WebSEAL server in the e-community. The input parameter to this function is the short name of the user on the local WebSEAL server (CDSSO) or the vouch for server (e-community). The output parameter is the attribute list constructed by the CDMF utility functions. In a CDSSO scenario, the attribute list is included in the authentication token that is constructed and sent to the remote WebSEAL server that is the target of the request. In an e-community scenario, this attribute list is included in the vouch for reply token sent to the remote WebSEAL server that is the target of the request. The CDMF library at the remote WebSEAL server can use the information contained in this attribute list when producing a user identity.

28

IBM Tivoli Access Manager: WebSEAL Developers Reference

Providing identity mapping: cdmf_map_usr()


The cdmf_map_usr() interface is called by WebSEAL to perform the mapping from the remote user to a local user identity and is required in the following situations: v When a URL containing a CDSSO authentication token is received by WebSEAL. When a CDSSO request originating in domain A is received by the domain B WebSEAL server, the identity of the local user must be determined. The cdmf_map_usr() interface is called to map the remote user (who initiated the CDSSO request) to a local user identity. v When a URL containing an e-community vouch for token is received by WebSEAL. When a vouch for reply token is received by a WebSEAL server (which is the target of the request) from a vouch for server, that WebSEAL server may be required 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, which contains the user name, domain, and an attribute list. This input information is used by the custom CDMF library to determine a local user identity. Any information contained in the attribute list was added by the cdmf_get_usr_attributes function call to the first CDMF library. The output information is also contained in a cdsso_usr_info_t data type. The only required field is the user name, which is the short name of the local (or requesting) user. The local users attribute list is an optional field that can be filled out if the users credential requires extended attributes. Because the credentials extended attribute list only supports one value, only the first value for each attribute will become part of the users credential. The domain field is ignored. v If the final user mapping is successful, CDMF_SUCCESS should be returned. v If no identity mapping occurs, CDMF_NOMAP should be returned. v If an error occurs, CDMF_FAILURE should be returned. v If CDMF_SUCCESS is not returned, no memory clean up is performed on the local user information.

Naming the custom library


You must name the custom library appropriately for your platform:
Platform Solaris AIX HP-UX Windows libcdmf.so libcdmf.a libcdmf.sl cdmf.dll File Name

Specifying extended attributes


Both CDMF application programming interfaces support additional user information in the form of a CDSSO attribute list. Although this type is called a CDSSO attribute list, this list can be used by the CDMF functions to communicate user information in both CDSSO and e-community scenarios.
Chapter 4. Using a CDMF library

29

The CDSSO attribute list cdsso_attrlist_t is a name/multiple value data list that is defined in cdssotypes.h. The utility functions that are required to construct this list are defined in the file cdmf_utils.h. These utility functions perform the following operations: v Create a CDSSO user attribute list v Create a CDSSO user attribute v Add a value to a CDSSO user attribute v Add a CDSSO 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()

30

IBM Tivoli Access Manager: WebSEAL Developers Reference

Chapter 5. CDMF C API reference


v Summary: CDAS and utility API functions on page 59 CDMF API functions: v cdmf_map_usr() on page 33 v cdmf_get_usr_attributes() on page 35 Utility API functions: v cdmf_create_usr_attr_list() on page 36 v cdmf_create_usr_attr() on page 37 v cdmf_add_value_to_attr() on page 38 v cdmf_add_attr_to_list() on page 39 Memory management macros: v CDSSO_STRDUP() on page 40 v CDSSO_MALLOC() on page 41 v CDSSO_FREE() on page 42 v CDSSO_REALLOC() on page 43

Summary: CDMF API functions and macros


The CDMF API functions are located in one directory. CDMF API functions You implement the following two CDMF API functions in your custom CDAS: v cdmf_map_usr() v cdmf_get_usr_attributes() Utility functions The following four utility functions facilitate data manipulation for extended user attributes: v cdmf_create_usr_attr_list() v cdmf_create_usr_attr() v cdmf_add_value_to_attr() v cdmf_add_attr_to_list() Memory management macros The following memory management macros should be used so WebSEAL can safely clean up any allocated memory: v CDSSO_STRDUP() v CDSSO_MALLOC() v CDSSO_FREE() v CDSSO_REALLOC() Windows-specific macros
Copyright IBM Corp. 1999, 2002

31

The following two macros are required when building the shared library on a Windows platform. The macros should not be redefined or changed. v CDMF_DECLSPEC() v CDMF_CALLTYPE()

32

IBM Tivoli Access Manager: WebSEAL Developers Reference

cdmf_map_usr()
Map a remote user into a local user.

Syntax
int cdmf_map_usr( cdsso_user_info_t *remote_usr, cdsso_user_info_t *local_usr );

Description
The WebSEAL cdsso authentication mechanism calls this interface to determine the identity of the local user during a CDSSO authentication or an e-community vouch for operation. The remote user information is received in a cdsso_usr_info_t structure. This information includes the remote user name, the remote domain name, and possibly an extended attribute list. This information should be used to determine the identity of the local user. If the local users identity is successfully determined, then CDMF_SUCCESS should be returned. The local user information is returned in a cdsso_usr_info_t structure. The local user information that can be returned in this structure consists of 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 should be used to construct the list. Information from this attribute list is included in the Tivoli Access Manager credential for that client. When cdmf_map_user() successfully returns the users identity, the function should return CDMF_SUCCESS. In this case, the implementor of cdmf_map_user() should not free the memory for the cdsso_user_into_t structure local_usr. This structure is freed by WebSEAL. If cdmf_map_user() fails, CDMF_FAILURE should be returned. If the function completes, but is not able to determine the identity of the local user, CDMF_NOMAP should be returned. When either CDMF_FAILURE or CDMF_NOMAP is returned, WebSEAL does not clean up the memory used by the cdsso_user_info_t structure local_usr. In these cases, the implementor of cdmf_map_user() must clean up this memory.

Parameters
Input remote_usr Out of domain user. Input/Output local_usr User mapped to in this domain.

Chapter 5. CDMF C API reference

33

Return Values
If successful, the function returns CDMF_SUCCESS. If no user mapping is available, the function returns CDMF_NOMAP. Upon failure, the function returns CDMF_FAILURE.

34

IBM Tivoli Access Manager: WebSEAL Developers Reference

cdmf_get_usr_attributes()
Retrieves the extended attributes for the specified user.

Syntax
int cdmf_get_usr_attributes( char *usr, cdsso_attrlist_t **attr_list );

Description
WebSEAL calls this interface: v When a CDSSO request is initiated by a user accessing the /pkmscdsso page on the local WebSEAL server. v When an e-community vouch for server generates a vouch for reply token for another WebSEAL server in the e-community. In a CDSSO operation, the extended attribute list returned by this function is sent to the remote WebSEAL server (the target of the request) inside the authentication token. In an e-community vouch for operation, the attribute list returned by this function is sent to the remote WebSEAL server (the target of the request) inside the vouch for reply token. The remote WebSEAL server can use these extended attributes 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 should set attr_list to NULL. Note: WebSEAL frees the memory allocated by this function. The implementor of the function should not free the pointer **attr_list.

Parameters
Input usr User name. Output attr_list Extended attributes for input user.

Return Values
If successful, the function returns CDMF_SUCCESS. Upon failure, the function returns CDMF_FAILURE.

Chapter 5. CDMF C API reference

35

cdmf_create_usr_attr_list()
Create an empty attribute list.

Syntax
cdsso_attrlist_t * cdmf_create_usr_attr_list( void );

Description
Create an empty attribute list. The caller is responsible for freeing the memory used by the list.

Parameters
None.

Return Values
If successful, the function returns a pointer to the newly allocated list. Otherwise, the function returns NULL.

36

IBM Tivoli Access Manager: WebSEAL Developers Reference

cdmf_create_usr_attr()
Create a new user attribute.

Syntax
cdsso_usr_attr_t * cdmf_create_usr_attr( char *attr_name );

Description
Create a new user attribute. A copy is made of the name. The caller is responsible for freeing the memory used by the new attribute.

Parameters
Input attr_name Name of the new attribute.

Return Values
If successful, the function returns a pointer to the newly allocated attribute. Otherwise, the function returns NULL.

Chapter 5. CDMF C API reference

37

cdmf_add_value_to_attr()
Add a new value to a user attribute.

Syntax
int cdmf_add_value_to_attr( char *new_value, cdsso_usr_attr_t *attr );

Description
Add a new value to a user attribute. A copy of the value is made. This function can 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.

Parameters
Input new_value New value to be added to the attribute. Output attr Updated user attribute object.

Return Values
If successful, the function returns TRUE. Otherwise, the function returns FALSE.

38

IBM Tivoli Access Manager: WebSEAL Developers Reference

cdmf_add_attr_to_list()
Add the specified user attribute to the specified user attribute list.

Syntax
int cdmf_add_attr_to_list( cdsso_usr_attr_t *new_attr, cdsso_attrlist_t *list );

Description
Add the specified user attribute to the specified user attribute list. The new attribute is added to an existing list. The caller is responsible for freeing memory used by the attribute list. The new attribute is part of the attribute list, and hence the memory for it is freed when the attribute list is freed.

Parameters
Input new_attr New attribute to be added to the list. Output list Updated list.

Return Values
If successful, the function returns TRUE. Otherwise, the function returns FALSE.

Chapter 5. CDMF C API reference

39

CDSSO_STRDUP()
Duplicate the specified string.

Syntax
void* CDSSO_STRDUP( char *dest, char *src );

Description
Duplicate the specified string. The caller is responsible for freeing the string when it is no longer neeed.

Parameters
dest Destination string. src Source string.

Return Values
When successful, returns a pointer to the new memory. Returns NULL if the call fails.

40

IBM Tivoli Access Manager: WebSEAL Developers Reference

CDSSO_MALLOC()
Allocate a portion of memory of the specified size.

Syntax
void *CDSSO_MALLOC( size_t size, );

Description
Allocate a portion of memory of the specified size. The caller is responsible for freeing the allocated memory.

Parameters
size Size in bytes of memory to allocate.

Return Values
Returns a pointer to newly allocated memory. Returns NULL if the call fails.

Chapter 5. CDMF C API reference

41

CDSSO_FREE()
Deallocate the specified memory.

Syntax
void CDSSO_FREE( void *ptr, );

Description
Deallocate the specified memory.

Parameters
ptr A pointer to the memory to be deallocated.

Return Values
Success: none. Error: none

42

IBM Tivoli Access Manager: WebSEAL Developers Reference

CDSSO_REALLOC()
Reallocate a memory block.

Syntax
void *CDSSO_REALLOC( void *curr_ptr, size_t new_size );

Description
Reallocate a memory block. The caller is responsible for freeing the allocated memory.

Parameters
curr_ptr Point to the existing memory to be deallocated. new_size Size in bytes of the new portion of memory.

Return Values
Returns a pointer to the reallocated (and possibly moved) memory block. Returns NULL is any memory errors are encountered.

Chapter 5. CDMF C API reference

43

44

IBM Tivoli Access Manager: WebSEAL Developers Reference

Part 3. Password Strength Module Reference


Chapter 6. Customizing password strength policy . . . . . . . . . . . . . . Password strength policy overview . . . . Introducing the Password Strength Policy Module . . . . . . . . . . . . . Building the custom Password Strength Module . . 47 . . 47 . . . 47 . 48

Copyright IBM Corp. 1999, 2002

45

46

IBM Tivoli Access Manager: WebSEAL Developers Reference

Chapter 6. Customizing password strength policy


Password strength refers to the stipulations placed on the construction of a password by password policy rules. This chapter discusses how you can customize your password strength policy using the password strength module provided in the Tivoli Access Manager authorization ADK package. Topic Index: v Password strength policy overview on page 47 v Building the custom Password Strength Module on page 48

Password strength policy overview


Password strength refers to the stipulations placed on the construction of a password by password policy rules. Tivoli Access Manager provides two means of controlling password strength policy: v Five pdadmin password policy commands v A plugable authentication module that allows you to customize a password policy

Introducing the Password Strength Policy Module


Tivoli Access Manager provides resources that allow you to customize your password strength policy. This password strength module is part of the PDAuthADK installation package. The instructions for using this module are in a README file located in the pwdstr_adk directory. The contents of this README are reproduced in Building the custom Password Strength Module on page 48. Password strength policy module conditions: v The module is only called when a password is changed via the pkmspasswd command. The module is not called if passwords are created or changed using the Web portal manager or the pdadmin utility. v The module should be a supplement, not a replacement, to the five standard pdadmin policy parameters. Refer to the IBM Tivoli Access Manager WebSEAL Administrators Guide for information on the pdadmin policy commands. v The password strength module is checked before the pdadmin policy parameters. Examples of custom password policies: v Performing checks against a database of previously used passwords (history) v Performing a dictionary look-up to prevent use of a word commonly used in a language

Copyright IBM Corp. 1999, 2002

47

Building the custom Password Strength Module


The following module files are located in the pwdstr_adk directory:
File Name pwdstrauthn.o pwdstrg.c Description The object file for the password strength module. The source file that implements the function password_strength(). This is compiled and linked into the shared library pwdstrauthn. The template for the Makefile used to build the pwdstrauthn shared library.

Makefile.allplat.in

Procedure: 1. Edit pwdstrg.c and modify the function password_strength() to enforce the custom password policy. 2. Edit Makefile.allplat.in and make the necessary modifications to build on the appropriate platform. There are instructions in the comments at the top of this file. 3. Build the pwdstrauthn shared library:
Solaris AIX HP-UX Windows libpwdstrauthn.so libpwdstrauthn.a libpwdstrauthn.sl pwdstrauthn.dll

4. Stop the webseald server (WebSEAL). 5. Place the pwdstrauthn shared library where it can be loaded. UNIX: /usr/lib Windows: anywhere in the path 6. Edit the [authentication-mechanisms] stanza of the webseald.conf configuration file and add: For Solaris:
passwd-strength = libpwdstrauthn.so

For AIX:
passwd-strength = libpwdstrauthn.a

For Windows:
passwd-strength = pwdstrauthn.dll

7. Restart the webseald server. 8. When you change a users password using the pkmspasswd utility, the password_strength() function is called before any registry specific password checks.

48

IBM Tivoli Access Manager: WebSEAL Developers Reference

Part 4. Cross-domain External Interface


Chapter 7. Creating a custom CDSSO library . . Understanding CDSSO token creation and consumption . . . . . . . . . . . . . . Default token creation . . . . . . . . . . Default token consumption . . . . . . . . Customizing the CDSSO shared library . . . . . Using the example (demonstration) library file . Creating and building a custom token create/consume library . . . . . . . . . Customizing the token create library interface . . Customizing the token consume library interface Sending SSO requests to a non-WebSEAL server . . Accepting SSO requests from a non-WebSEAL server . . . . . . . . . . . . . . . . 51 51 52 52 53 53 54 54 55 55 56

Copyright IBM Corp. 1999, 2002

49

50

IBM Tivoli Access Manager: WebSEAL Developers Reference

Chapter 7. Creating a custom CDSSO library


WebSEALs cross-domain single sign-on solutions include Cross-domain Single Sign-on (CDSSO) and e-community. Both cross-domain single sign-on solutions employ authentication tokens that describe or vouch for the user identity to the destination server. The construction of these tokens by the initial server is called token creation. The decoding and use of the token by the destination server is called token consumption. This chapter describes how to build custom library files that can create and consume tokens used in cross-domain and cross-server single sign-on solutions. For complete background information and configuration procedures for the default WebSEAL CDSSO functionality, see Chapter 6 of the IBM Tivoli Access Manager WebSEAL Administrators Guide.

Understanding CDSSO token creation and consumption


The default WebSEAL CDSSO functionality allows users to seamlessly log on to other WebSEAL or non-WebSEAL servers. The initial and destination servers can be located in the same secure domain, or in different domains (cross-domain). CDSSO is primarily designed to provide a single sign-on solution between two servers located in different domains. CDSSO functions when a user makes a request to a remote resource by clicking on a specially constructed link located on a page belonging to the initial WebSEAL server. The user must have a valid account with the initial WebSEAL server and must have successfully logged in. The link refers to a special CDSSO management page called pkmscdsso. The CDSSO mechanism (triggered by this link) creates and encodes a special CDSSO authentication token containing the users existing credential information, plus any extended credential attributes that further identify the user. The user identity, required by the destination server, is defined by the information in this token. The token is sent off as a query string argument in a specially formatted redirect to the destination server where the resource is located. The destination server recognizes the special format of the incoming request as a CDSSO request containing authentication information. The token is decoded and the server now has the users identity (as authenticated on the first sever). If the user has an equivalent account with this server, the server logs the user on. Otherwise, further identity mapping may be required. If the destination server is a WebSEAL server, the Cross-domain Mapping Function (CDMF) can be called to perform this mapping requirement. Successful authentication, with valid authorization checks, results in the requested resource being served to the user. Throughout this exchange, the user was not forced to perform a second login. The next two sections explain how token creation and consumption occurs for the default CDSSO functionality between two WebSEAL servers. Complete configuration information for default CDSSO functionality between two WebSEAL servers is covered in Chapter 6 of the IBM Tivoli Access Manager WebSEAL Administrators Guide.

Copyright IBM Corp. 1999, 2002

51

Default token creation


CDSSO token creation occurs when an authenticated user on webseal1 requests a resource from webseal2 through a special link located on webseal1. The link refers to a special CDSSO management page called pkmscdsso that calls the CDSSO built-in token create library (ssocreate). The link also contains the destination URL where the resource is located. The following example illustrates a CDSSO link to a remote resource:
http://webseal1/pkmscdsso?http://webseal2/resource.html

Once this link is activated, the token create library encodes the authenticated users existing credential information and includes the information as a query string argument in a redirected request to the resource on webseal2, using the destination URL supplied in the link. The cdsso-argument parameter in the [cdsso] stanza of the webseald.conf configuration file tells the default token create library what name to use as a label for the encoded token information in the query string argument (default = PD-ID). It is this unique label that triggers the token consume library on webseal2. The following example illustrates the format of a CDSSO redirected request:
http://webseal2/resource.html?PD-ID=<encoded-authentication-token>

You can create your own custom token create library that formats and encodes the arguments included in the redirected request. The custom library can alter the format and content of the redirected request to accommodate the consumption requirements of another WebSEAL server or a non-WebSEAL server. For example, if you are using a WebSEAL server, a call to a CDMF can be coded to supply extended attributes that further define the users identity. Creating a custom token create library is explained later in this chapter.

Default token consumption


The webseal2 server receives the redirected request and recognizes the request as a CDSSO request because of the PD-ID token argument label. The PD-ID label is also defined for webseal2 by the cdsso-argument parameter in the [cdsso] stanza of the webseald.conf configuration file. The PD-ID label in the request triggers a call to the built-in token consume library (ssoconsume). The library decodes the query string containing the token and reveals the users identity information. The webseal2 server can use this information to authenticate the user and perform authorization on the resource request. You can create your own token consume library that handles the incoming query string information. The custom library can be written to correctly decode a token created from the custom requirements of another WebSEAL server or a non-WebSEAL server. For example, if you are using a WebSEAL server, a call to a CDMF can be coded to map the token authentication information to an identity known to this destination server. Creating a custom token consume library is explained later in this chapter.

52

IBM Tivoli Access Manager: WebSEAL Developers Reference

Customizing the CDSSO shared library


You can create a custom CDSSO token create/consume library by modifying the example xauthn.c source file included with the WebSEAL External Authentication ADK. The xauthn.c source file is located in the example sub-directory of the ADK (pdxauthn_adk). The components of the WebSEAL External Authentication ADK and the use of the API functions are fully explained in Chapter 2 of this developers reference (Implementing a CDAS shared library). The complete External Authentication API reference can be found in Appendix A of this developers reference.

Using the example (demonstration) library file


Token create and token consume functionality can be contained in one library, or separated into two individual libraries. WebSEAL uses two distinct built-in libraries to handle the token creation and token consumption tasks of the default CDSSO functionality: v UNIX: libssocreate.{so | a | sl} and libssoconsume.{so | a | sl} v Windows: ssocreate.dll and ssoconsume.dll The WebSEAL ADK provides a pre-built platform-specific example library that demonstrates CDSSO functionality similar to the functionality provided by the built-in default libraries. The example library performs both token creation and token consumption tasks and was built from the xauthn.c source file. You use the xauthn.c source file as the starting point for building your own custom library. In addition, the example library provides output data during the token creation and consumption processing when you use the library in a test environment. This output is sent by default to the WebSEAL log file (msg_webseald.log). The output can be useful for analyzing the proper functionality of the library. The example library file is located in the example sub-directory of the WebSEAL External Authentication ADK (pdxauthn_adk) and has the following platform-specific file name:
Example CDSSO Library File Name Solaris libxauthn.so AIX libxauthn.a Windows xauthn.dll HP-UX libxauthn.sl

Since both the create and consume functionality are contained within the same library file, you must specify the full path name to this library for both the sso-create and sso-consume parameters in the [authentication-mechanisms] stanza of the webseald.conf configuration file. For example (Solaris):
[authentication-mechanisms] sso-create = /opt/pdweb/pdxauthn_adk/example/libxauthn.so sso-consume = /opt/pdweb/pdxauthn_adk/example/libxauthn.so

You can use the following default directory to store your custom libraries: v UNIX: /opt/pdweb/lib/ v Windows: C:\Program Files\Tivoli\PDWeb\bin\ Similarly, you must specify the full path name to the custom library in the webseald.conf configuration file. For example (Solaris):
Chapter 7. Creating a custom CDSSO library

53

[authentication-mechanisms] sso-create = /opt/pdweb/lib/custom-library.so sso-consume = /opt/pdweb/lib/custom-library.so

Creating and building a custom token create/consume library


You create a custom token create/consume library by first customizing the xauthn.c source file located in the example sub-directory of the WebSEAL External Authentication ADK (pdxauthn_adk). Information contained in the remainder of this chapter and in the xauthn.c source file itself provides further detail on how to create your custom library. You can give the custom library any file name. The file name is defined when you compile and build the library. Information contained in the Makefile template provides platform-specific instructions on compiling and building the library from the source file.

Customizing the token create library interface


WebSEAL passes client authentication information to the custom token create library. 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 by using the utility function xnvlist_get(). For more information on retrieving values from xnvlist_t, see the reference page for xnvlist_get(). The token create functionality typically generates a redirected request containing the destination URL of the resource and the encoded credential of the user. A custom token create library must generate a customized version of this redirect. The following valid user authentication data from WebSEAL, provided as an xnvlist_t data structure, is passed to the token creation interface: v xauthn_sso_type v xauthn_input_url v xauthn_ipaddr v xauthn_qop v xauthn_browser_info v xauthn_exisiting_cred The xauthn_sso_type is set to SSO_CREATE. The xauthn_input_url is set to the destination URL where the resource is located. For example:
http://webseal2.cruz.com/resource.html

For descriptions of the other authentication data types, see Valid user authentication data on page 11. Normally a custom library using the xauthn interface (for token create/consume functionality) is required to return a client identity back to WebSEAL using the xauthn_identity_t identity structure. However, the actual requirement of a token create library is to return a redirected request string (URL). This string can be passed back to WebSEAL by storing the redirect URL string in the xattr_list_t data structure of the identity structure. The information provided to xattr_list_t can be set using the xattr_set() utility. You must set the value of this URL string using the name cdsso-redirect-url. The identity structure is then passed to WebSEAL and the

54

IBM Tivoli Access Manager: WebSEAL Developers Reference

request is redirected using the URL string provided as cdsso-redirect-url.


Output Name cdsso-redirect-url Description Redirected request URL string with encoded authentication data.

The value for cdsso-redirect-url appears similar to the following example:


http://webseal2/resource.html?TOKEN=<encoded-authentication-data>

The above redirect URL string is constructed using the destination URL from the link activated on the original server, plus the user credential information passed in from the xauthn_existing_cred authentication identifier created for the authenticated user by the original WebSEAL server. In addition, the custom token create library can call out to include extended attributes that further define the users identity.

Customizing the token consume library interface


The label identifying the encoded token argument string (configured in the cdsso-argument parameter in webseald.conf) allows the receiving WebSEAL server to recognize the incoming request as a redirected CDSSO request and to invoke the token consume library. The token consume library decodes the token information and passes down the following valid user authentication data, provided as an xnvlist_t data structure: v xauthn_sso_type v v v v v xauthn_query_string xauthn_ipaddr xauthn_qop xauthn_browser_info xauthn_exisiting_cred

The xauthn_sso_type is set to SSO_CONSUME. The xauthn_query_string is set to the query string of the redirected request containing encoded authentication data and, optionally, additional attributes. For example:
?TOKEN=encoded_data

For descriptions of the other authentication data types, see Valid user authentication data on page 11. The token consume library returns a client identity back to WebSEAL using the xauthn_identity_t identity structure. WebSEAL can use this identity information to authenticate the user and continue processing the request.

Sending SSO requests to a non-WebSEAL server


CDSSO is a functionality that provides a single sign-on solution between two WebSEAL servers. This section describes how to set up a WebSEAL server to send a single sign-on request to a non-WebSEAL destination server. 1. Create a custom token create library based on the example xauthn.c source file. This code must be written to generate redirected requests in a format acceptable by the non-WebSEAL destination server.

Chapter 7. Creating a custom CDSSO library

55

2. In the webseald.conf configuration file, set the sso-create authentication mechanism parameter to the full path name of the token create library file. For example (Solaris):
[authentication-mechanisms] sso-create = /opt/pdweb/lib/libxauthn.so

You must specify a full path name to this the library. 3. Enable WebSEAL to process single sign-on requests by communication type:
[cdsso] cdsso-auth = {http | https | both}

4. Create a special link on the appropriate page of this WebSEAL server that requests the single sign-on to the non-WebSEAL server and activates the token create library. For example:
http://webseal/pkmscdsso?https://non-webseal/resource.html

If the customized library fails for some reason, an xnvlist attribute should be allocated with the specified return value name (see the example code), but with a null value. WebSEAL can then serve a WebSEAL Not Found error page to the browser. When the CDSSO link is activated by an authenticated user, the token create library constructs a redirected request made up of the request URL and encoded identity information describing the user. The format and contents of the redirected request URL, constructed by the custom library, must be compatible with how the non-WebSEAL destination server is configured to accept and read this request.

Accepting SSO requests from a non-WebSEAL server


This section describes how to set up a WebSEAL server to accept a single sign-on request from a non-WebSEAL server. 1. Create a custom token consume library based on the example xauthn.c source file. This code must be written to successfully parse and decode requests in a format created by the non-WebSEAL source server. 2. In the webseald.conf configuration file, set the sso-consume authentication mechanism parameter to the full path name of the token create library file. For example (Solaris):
[authentication-mechanisms] sso-consume = /opt/pdweb/lib/libxauthn.so

You must specify a full path name to this the library. 3. Enable WebSEAL to process single sign-on requests by communication type:
[cdsso] cdsso-auth = {http | https | both}

4. Set the cdsso-argument label to the appropriate value that matches what the non-WebSEAL server sends in its request and that uniquely identifies the request as a single sign-on request to be handled by WebSEALs CDSSO functionality:
[cdsso] cdsso-argument = <token-argument-ID>

WebSEAL receives the redirected request URL from the non-WebSEAL server. The token-argument-ID label informs WebSEAL that this is a CDSSO request.

56

IBM Tivoli Access Manager: WebSEAL Developers Reference

The token consume library is activated. The library parses and decodes the query string of the request. The resulting user identity is passed to WebSEAL which uses it to authenticate the user and continue processing the resource request. The custom library must be written to understand the format and contents of the query string constructed by the non-WebSEAL server. If authentication is not successful, WebSEAL presents the user with a login prompt.

Chapter 7. Creating a custom CDSSO library

57

58

IBM Tivoli Access Manager: WebSEAL Developers Reference

Appendix A. External Authentication C API Reference


v Summary: CDAS and utility API functions on page 59 CDAS API Functions: v v v v xauthn_initialize() on page 61 xauthn_shutdown() on page 62 xauthn_authenticate() on page 63 xauthn_change_password() on page 64

Utility API Functions: v v v v xattr_get() on page 65 xattr_set() on page 66 xauthn_util_entry_to_creds() on page 67 xnvlist_get() on page 68

Data Structures: v xattr_list_item_t on page 69 v xattr_list_t on page 70 v xauthn_identity_t on page 71 v xnvlist_item_t on page 72 v xnvlist_t on page 73

Summary: CDAS and utility API functions


You must implement the following four CDAS API functions in your custom CDAS shared library: v xauthn_initialize() v xauthn_shutdown() v xauthn_authenticate() v xauthn_change_password() The static library file libpdxauthn.a (for UNIX) or pdxauthn.lib (for Windows) contains the utility functions. To use these utilities, you must link your custom shared library to this file. There are four utility functions that facilitate data manipulation: v xattr_get() v xattr_set() These two utility functions allow you to construct extended attributes for the Tivoli Access Manager identity. v xauth_util_entry_to_creds() v xnvlist_get() This utility function retrieves authentication data from the xnvlist_t data structure that was passed to the xauthn_authenticate() and xauthn_change_password() functions. The CDAS implementation makes use of the following five data structures:
Copyright IBM Corp. 1999, 2002

59

v v v v v

xattr_list_item_t xattr_list_t xauthn_identity_t xnvlist_item_t xnvlist_t

60

IBM Tivoli Access Manager: WebSEAL Developers Reference

xauthn_initialize()
Initializes the specified CDAS shared library.

Syntax
xauthn_status_t xauthn_initialize( int argc, const char **argv );

Description
Use this initialization function to initialize an authentication shared library. The input parameters argc and argv are built from parameters specified in the [authentication-mechanisms] stanza of the webseald.conf configuration file. The following example definition uses the sample CDAS shared library:
passwd-ldap = libxauthn.so& -dbms sys.db

In the above 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 agrc and argv. Therefore, the implementor of this function should not free either of these parameters.

Parameters
Input argc The number of arguments contained in the argv array. argv The string arguments passed in the service definition for this service instance.

Return Values
If successful, the function returns XAUTHN_S_COMPLETE. Other possible error codes can be found in the pdxauthn.h header file.

Appendix A. External Authentication C API Reference

61

xauthn_shutdown()
Shuts down the specified CDAS shared library.

Syntax
xauthn_status_t xauthn_shutdown( int argc, const char **argv );

Description
During the normal shutdown, the WebSEAL authentication dispatcher calls this interface to perform any shut down processes that may required by the custom environment. The input parameters argc and argv are built from the parameters specified in the [authentication-mechanisms] stanza of the webseald.conf configuration file. The following example definition uses the sample CDAS shared library:
passwd-ldap = libxauthn.so& -dbms sys.db

In the above example, xauthn_shutdown() 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.

Parameters
Input argc The number of arguments contained in the argv array. argv The string arguments passed in the service definition for this service instance.

Return Values
If successful, the function returns XAUTHN_S_COMPLETE. Other possible error codes can be found in the pdxauthn.h header file. Note: The shutdown interface is not functional in Tivoli Access Manager 4.1. It exists for future development and implementation.

62

IBM Tivoli Access Manager: WebSEAL Developers Reference

xauthn_authenticate()
Performs the CDAS authentication.

Syntax
xauthn_status_t xauthn_authenticate( xnvlist_t *authnInfo, xauthn_identity_t *ident );

Description
The authentication dispatcher calls this interface to perform the customer-specific external authentication. Client authentication information is passed by the dispatcher through the input argument authnInfo. Refer to Valid user authentication data on page 11 for the list of authentication data that authnInfo can contain. Based on the authentication information, this function implements the specific authentication mechanism and stores the resulting client information in ident. This information is then returned to WebSEAL. It is important to note that the client identity ident can contain additional user information. WebSEAL frees ident. The implementor of this function should not free ident.

Parameters
Input authnInfo The authnInfo parameter is a name/value data list containing client authentication information. Input/Output ident The ident parameter contains the authenticated user information.

Return Values
If successful, the function returns XAUTHN_S_COMPLETE. Other possible error codes can be found in the pdxauthn.h header file.

Appendix A. External Authentication C API Reference

63

xauthn_change_password()
Performs the password change.

Syntax
xauthn_status_t xauthn_change_password( xnvlist_t *authnInfo );

Description
The authentication dispatcher calls this interface to implement a custom password change mechanism. This interface is only supported only for username and password authentication mechanism. Client password change information is passed by the dispatcher through the input argument authnInfo. Refer to Valid user authentication data on page 11 for the list of authentication data that authnInfo can contain.

Parameters
Input authnInfo The authnInfo parameter is a name/value data list containing client authentication information.

Return Values
If successful, the function returns XAUTHN_S_COMPLETE. XAUTHN_S_UNSUPPORTED_AUTHN_METHOD is returned if the external authentication process does not support password changes. Other possible error codes can be found in the pdxauthn.h header file.

64

IBM Tivoli Access Manager: WebSEAL Developers Reference

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

Syntax
int xattr_get( xattr_list_t *list, char *name, char **value );

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

Parameters
Input list A pointer to the name/value list. name A pointer to a name of the attribute to retrieve. Output value A pointer to a pointer that stores the value of a given name. The caller of this function should not free the value returned.

Return Values
This function returns 0 upon success. Otherwise, it returns 1.

Appendix A. External Authentication C API Reference

65

xattr_set()
Stores a name and a value into the extended attribute list.

Syntax
int xattr_set( xattr_list_t *list, char *name, char *value );

Description
Stores a name and a value into the extended attribute list. The caller does not need to free name or value. These will be freed when the attribute list is freed.

Parameters
Input list A pointer to the name/value list. name A pointer to a name. The name should be dynamically allocated using malloc(). value A pointer to a value of the given name. The value should be dynamically allocated using malloc().

Return Values
This function returns 0 upon success. Otherwise, it returns 1.

66

IBM Tivoli Access Manager: WebSEAL Developers Reference

xauthn_util_entry_to_creds()
Converts a value from an xnvlist_t into a credential.

Syntax
azn_creds_h_t xauthn_util_entry_to_creds( const char *value, int vlen );

Description
Some entries in the xnvlist_t authentication data structure passed into xauthn_authenticate() and xauthn_change_password() are actually encoded credentials. This function converts the encoded credential into an azn_creds_h_t which can then be manipulated using the functions defined by the Tivoli Access Manager authorization API. The caller does not need to free the returned azn_creds_h_t.

Parameters
Input value The value retrieved by the call to xvnlist_get() for the entry which contains the credential. vlen The length returned by the call to xnvlist_get() for the entry which contains the credential.

Return Values
The function returns a valid credential if successful, or AZN_C_INVALID_HANDLE if an error occurs.

Appendix A. External Authentication C API Reference

67

xnvlist_get()
Retrieves the value and length of a given name in the name/value list.

Syntax
int xnvlist_get( xnvlist_t *list, char *name, char **value, int *vlen );

Description
Retrieves the value and length of a given name in the name/value list.

Parameters
Input list A pointer to the name/value list. name A pointer to a name whose value is to be retrieved. Output value A pointer to a pointer that stores the value of a given name. The caller of this function should free the memory for the **value when finished. vlen A pointer to a pointer that stores the length of the returned value.

Return Values
This function returns 0 upon success. Otherwise, it returns 1.

68

IBM Tivoli Access Manager: WebSEAL Developers Reference

xattr_list_item_t
The data structure that holds a single extended attribute.

Definition
typedef struct { char *name; char *value; } xattr_list_item_t;

Values
name A string representing the name of the extended attribute. value A string representing the value of the extended attribute.

Appendix A. External Authentication C API Reference

69

xattr_list_t
A list of extended attributes to be added to the credential.

Definition
typedef struct { long length; xattr_list_item_t *items; } xattr_list_t;

Values
length The number of elements in the list. items An array of xttr_list_item_t structures.

70

IBM Tivoli Access Manager: WebSEAL Developers Reference

xauthn_identity_t
The data structure used to hold information about a users Tivoli Access Manager identity.

Definition
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;

Values
prin_type Should be set to XAUTHN_PRIN_TYPE_DN name Not valid. dn The users LDAP Distinguished Name (DN) or the LDAP user name. uraf_name Not valid. user_info Information added to the credential as an extended attribute called azn_cred_user_info. authnmech_info Authentication method information. Added to the credential as an extended attribute called azn_cred_mech_id. xattrs The xattr_list_t data structure can be used to return any extended user attributes.

Description
The prin_type indicates the user registry used to generate a credential from the identity. 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.

Appendix A. External Authentication C API Reference

71

xnvlist_item_t
The data structure that holds a single item of authentication data.

Definition
typedef struct { char *name; char *value; int vlen; } xnvlist_item_t;

Values
name A string representing the name of the item. Valid names are descibed in Valid user authentication data on page 11. value An array of bytes representing the value of the item. vlen The length of the value array.

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

72

IBM Tivoli Access Manager: WebSEAL Developers Reference

xnvlist_t
The data structure that holds a list of xnvlist_item_t authentication data structures.

Definition
typedef struct { long length; xnvlist_item_t *items; } xnvlist_t;

Values
length The number of elements in the items array. items An array of xnvlist_item_t.

Appendix A. External Authentication C API Reference

73

74

IBM Tivoli Access Manager: WebSEAL Developers Reference

Appendix B. Notices
This information was developed for products and services offered in the U.S.A. IBM may not offer the products, services, or features discussed in this document in other countries. Consult your local IBM representative for information on the products and services currently available in your area. Any reference to an IBM product, program, or service is not intended to state or imply that only that IBM product, program, or service may be used. Any functionally equivalent product, program, or service that does not infringe any IBM intellectual property right may be used instead. However, it is the users responsibility to evaluate and verify the operation of any non-IBM product, program, or service. IBM may have patents or pending patent applications covering subject matter described in this document. The furnishing of this document does not give you any license to these patents. You can send license inquiries, in writing, to: IBM Director of Licensing IBM Corporation North Castle Drive Armonk, NY 10504-1785 U.S.A For license inquiries regarding double-byte (DBCS) information, contact the IBM Intellectual Property Department in your country or send inquiries, in writing, to: IBM World Trade Asia Corporation Licensing 2-31 Roppongi 3-chome Minato-ku Tokyo 106 Japan The following paragraph does not apply to the United Kingdom or any other country where such provisions are inconsistent with local law: INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION AS IS WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or implied warranties in certain transactions, therefore, this statement may not apply to you. This information could include technical inaccuracies or typographical errors. Changes are periodically made to the information herein; these changes will be incorporated in new editions of the publication. IBM may make improvements and/or changes in the product(s) and/or the program(s) described in this publication at any time without notice. Any references in this information to non-IBM Web sites are provided for convenience only and do not in any manner serve as an endorsement of those Web sites. The materials at those Web sites are not part of the materials for this IBM product and use of those Web sites is at your own risk.

Copyright IBM Corp. 1999, 2002

75

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 purpose of enabling: (i) the exchange of information between independently created programs and other programs (including this one) and (ii) the mutual use of the information which has been exchanged, should contact: IBM Corporation 2Z4A/101 11400 Burnet Road Austin, TX 78758 USA 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 material available 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 controlled environment. Therefore, the results obtained in other operating environments may vary significantly. Some measurements may have been made on development-level systems and there is no guarantee that these measurements will be the same on generally available systems. Furthermore, some measurement may have been estimated through extrapolation. Actual results may vary. Users of this document should 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 the suppliers of those products. All statements regarding IBMs future direction or intent are subject to change or withdrawal without notice, and represent goals and objectives only. This information contains examples of data and reports used in daily business operations. To illustrate them as completely as possible, the examples include the names of individuals, companies, brands, and products. All of these names are fictitious and any similarity to the names and addresses used by an actual business enterprise is entirely coincidental. COPYRIGHT LICENSE: This information contains sample application programs in source language, which illustrates programming techniques on various operating platforms. You may copy, modify, and distribute these sample programs in any form without payment to IBM, for the purposes of developing, using, marketing or distributing application programs conforming to the application programming interface for the operating platform for which the sample programs are written. These examples have not been thoroughly tested under all conditions. IBM, therefore, cannot guarantee or imply reliability, serviceability, or function of these programs. You may copy,

76

IBM Tivoli Access Manager: WebSEAL Developers Reference

modify, and distribute these sample programs in any form without payment to IBM for the purposes of developing, using, marketing, or distributing application programs conforming to IBMs 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 rights reserved.

Trademarks
The following terms are trademarks or registered trademarks of International Business Machines Corporation in the United States, other countries, or both: AIX DB2 IBM IBM logo SecureWay Tivoli Tivoli logo WebSphere Microsoft, Windows, Windows NT, and the Windows logo are trademarks of Microsoft Corporation in the United States, other countries, or both. Java and all Java-based trademarks and logos are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States and other countries. UNIX is a registered trademark of The Open Group in the United States and other countries. Other company, product, and service names may be trademarks or service marks of others.

Appendix B. Notices

77

78

IBM Tivoli Access Manager: WebSEAL Developers Reference

Index A
authentication data, valid 11 authentication methods 4 cdssotypes.h 26 cert-ssl 4 cred-ext-attrs 4, 5, 20 credential extended attributes

B
business entitlements 5

E
extended attributes 5, 20, 29

C
CDAS API authentication methods 4 build custom library 15 components 9 example library 20 overview 3 programming 10 returning the client identity 14 software requirements 10 specifying extended attributes 14 understanding functions 59 valid authentication data 11 CDAS custom library configure and install 19 extended attributes configuration 20 CDAS example library 20 CDAS model extended attributes chain model 6 single authentication library 5 CDMF API components 26 customizing library 28 implementing custom library 27 in a CDSSO environment 25 in an e-community environment 26 naming the custom library file 29 overview 25 providing extended user attributes 28 providing identity mapping 29 roles of duo libraries 28 software requirements 27 specifying extended attributes 29 understanding functions and macros 31 cdmf_add_attr_to_list() 39 cdmf_add_value_to_attr() 38 cdmf_create_usr_attr_list() 36 cdmf_create_usr_attr() 37 cdmf_get_usr_attributes() 27, 28, 35 cdmf_map_usr() 27, 29, 33 cdmf_utils.h 26 cdmf_utils.lib 26 cdmf.c.examples 26 cdmf.c.skeleton 26, 27 cdmf.h 26 cdsso_attrlist_t 29 CDSSO_FREE() 42 CDSSO_MALLOC() 41 CDSSO_REALLOC() 43 CDSSO_STRDUP() 40 cdsso_usr_info_t 29 Copyright IBM Corp. 1999, 2002

H
http-request 4

L
libcdmfutils 26 libpdxauthn.a 9 libpwdstrauthn 48

M
Makefile.allplat.in 48 Makefile.cdmf.in 26 Makefile.in 15 Makefile.win32 26

P
passwd-cdas 4 passwd-ldap 4 password strength module Makefile.allplat.in 48 overview 47 password_strength 48 pwdstrauthn.o 48 pwdstrg.c 48 pdadmin policy 47 pdxauthn 15 pdxauthn_adk 9 pdxauthn.h 10 pdxauthn.lib 9 pkmspasswd 47 post password change 18 pwdstrauthn.dll 48 pwdstrauthn.o 48 pwdstrg.c 48

R
related publications Request-URI 12 x

S
sso-consume 4 sso-create 4

79

T
token-cdas 4

X
xattr_get() 14, 65 xattr_list_item_t 69 xattr_list_t 14, 70 xattr_set() 14, 66 xattr.h 10 xauthn_admin_cred 12 xauthn_admin_name 12 xauthn_authenticate() 11, 63 xauthn_browser_info 12 xauthn_cert 12 xauthn_cert_dn 12 xauthn_cert_issuer_dn 12 xauthn_change_password() 11, 64 xauthn_existing_cred 12 xauthn_identity_t 11, 14, 71 xauthn_initialize() 10, 61 xauthn_ipaddr 12 xauthn_new_password 12 xauthn_password 12 xauthn_qop 12 xauthn_shutdown() 11, 62 xauthn_su_method 12 xauthn_token 12 xauthn_username 12 xauthn_util_entry_to_creds() 67 xauthn.c 9 xnvlist_get() 11, 68 xnvlist_item_t 72 xnvlist_t 11, 73 xnvlist.h 10

80

IBM Tivoli Access Manager: WebSEAL Developers Reference

Printed in U.S.A.

SC32-1135-01