webseal developerâ€™s reference - ibm - united states

IBM Tivoli Access Manager

WebSEAL Developer’s ReferenceVersion 3.9

GC23-4683-00

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

Fifth Edition (April 2002)

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 Contractwith IBM Corp.

Contents

Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . vWho should read this reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . vWhat this reference contains . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . vPublications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . v

IBM Tivoli Access Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . vRelated publications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . viiiAccessing publications online. . . . . . . . . . . . . . . . . . . . . . . . . . . . . xOrdering publications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xProviding feedback about publications. . . . . . . . . . . . . . . . . . . . . . . . . . x

Accessibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiContacting customer support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiConventions used in this book . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xi

Typeface conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xi

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

Chapter 1. CDAS API overview . . . . . . . . . . . . . . . . . . . . . . . . . . 3Introducing the CDAS API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

Supported authentication methods . . . . . . . . . . . . . . . . . . . . . . . . . . . 4Enabling dynamic business entitlements . . . . . . . . . . . . . . . . . . . . . . . . . 4

CDAS authentication models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5The single authentication CDAS model . . . . . . . . . . . . . . . . . . . . . . . . . 5The credential extended attributes CDAS chaining model . . . . . . . . . . . . . . . . . . . 6

Chapter 2. Implementing a CDAS shared library . . . . . . . . . . . . . . . . . . 9CDAS API components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

Header files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9Software requirements for implementing a custom CDAS . . . . . . . . . . . . . . . . . . . 10

Programming the CDAS shared library . . . . . . . . . . . . . . . . . . . . . . . . . . 10Initialization: xauthn_initialize() . . . . . . . . . . . . . . . . . . . . . . . . . . . 10Shutdown: xauthn_shutdown() . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10Authentication: xauthn_authenticate(). . . . . . . . . . . . . . . . . . . . . . . . . . 11Password change: xauthn_change_password() . . . . . . . . . . . . . . . . . . . . . . . 11

Valid user authentication data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12Returning the client identity (xauthn_identity_t) . . . . . . . . . . . . . . . . . . . . . . . 15Specifying extended attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15Building the custom shared library . . . . . . . . . . . . . . . . . . . . . . . . . . . 16Writing a CDAS for switch user . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

Chapter 3. Configuring WebSEAL to use a CDAS . . . . . . . . . . . . . . . . . 17Configuring and installing the CDAS shared library . . . . . . . . . . . . . . . . . . . . . . 17

Additional configuration for an extended attributes CDAS . . . . . . . . . . . . . . . . . . 18Using the example shared library . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

Chapter 4. Authentication C API reference . . . . . . . . . . . . . . . . . . . . 21Summary: CDAS and utility API functions . . . . . . . . . . . . . . . . . . . . . . . . . 21xauthn_initialize() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23xauthn_shutdown() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24xauthn_authenticate() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25xauthn_change_password() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26xattr_get() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27xattr_set() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28xauthn_util_entry_to_creds(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29xnvlist_get() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

© Copyright IBM Corp. 1999, 2002 iii

xattr_list_item_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31xattr_list_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32xauthn_identity_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33xnvlist_item_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34xnvlist_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

Part 2. CDMF API Developer Reference . . . . . . . . . . . . . . . . . . . . 37

Chapter 5. Using a CDMF shared library . . . . . . . . . . . . . . . . . . . . . 39Introducing the Cross-domain Mapping Framework . . . . . . . . . . . . . . . . . . . . . . 39

Using CDMF in a CDSSO environment . . . . . . . . . . . . . . . . . . . . . . . . . 39Using CDMF in an e-community environment. . . . . . . . . . . . . . . . . . . . . . . 40

CDMF API components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40Software requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

Implementing the CDMF shared library . . . . . . . . . . . . . . . . . . . . . . . . . . 41The CDMF library partnership . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

Customizing the CDMF shared library . . . . . . . . . . . . . . . . . . . . . . . . . . 42Providing user attributes: cdmf_get_usr_attributes() . . . . . . . . . . . . . . . . . . . . . 42Providing identity mapping: cdmf_map_usr() . . . . . . . . . . . . . . . . . . . . . . . 42Naming the custom shared library. . . . . . . . . . . . . . . . . . . . . . . . . . . 43

Specifying extended attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

Chapter 6. CDMF C API reference . . . . . . . . . . . . . . . . . . . . . . . . 45Summary: CDMF API functions and macros . . . . . . . . . . . . . . . . . . . . . . . . 45cdmf_map_usr() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47cdmf_get_usr_attributes() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48cdmf_create_usr_attr_list() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49cdmf_create_usr_attr() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50cdmf_add_value_to_attr(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51cdmf_add_attr_to_list() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52CDSSO_STRDUP() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53CDSSO_MALLOC() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54CDSSO_FREE() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55CDSSO_REALLOC() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56

Part 3. Password Strength Module Reference . . . . . . . . . . . . . . . . . 57

Chapter 7. Customizing password strength policy . . . . . . . . . . . . . . . . . 59Password strength policy overview . . . . . . . . . . . . . . . . . . . . . . . . . . . 59

Introducing the Password Strength Policy Module . . . . . . . . . . . . . . . . . . . . . 59Building the custom Password Strength Module . . . . . . . . . . . . . . . . . . . . . . . 60

Appendix. Notices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61Trademarks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65

iv IBM Tivoli Access Manager: WebSEAL Developer’s Reference

Preface

Welcome to the IBM®Tivoli®Access Manager WebSEAL Developer’s Reference.

This document provides complete administration and programming informationfor the Cross-domain Authentication Service (CDAS), the Cross-domain MappingFramework (CDMF), and the Password Strength Module.

This developer’s reference contains three sections:v Part 1 – CDAS API Developer Referencev Part 2 – CDMF API Developer Referencev Part 3 – Password Strength Module Developer Reference

Who should read this referenceThis reference is for system administrators responsible for programming andapplication integration tasks in an Access Manager WebSEAL environment.

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

Telnetv Lightweight Directory Access Protocol (LDAP) and directory servicesv A supported user registryv Authentication and authorization

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

What this reference containsThis reference contains the following sections:v Part 1 – CDAS API Developer Reference (Chapters 1-4)v Part 2 – CDMF API Developer Reference (Chapters 5-6)v Part 3 – Password Strength Module Developer Reference (Chapter 7)

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

IBM Tivoli Access ManagerThe Access Manager library is organized into the following categories:v Release informationv Base information

© Copyright IBM Corp. 1999, 2002 v

v WebSEAL informationv Web security informationv Developer reference informationv Supplemental technical information

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

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

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

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

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

v IBM Tivoli Access Manager for e-business Release Notes

GI11-0919 (am39_relnotes.pdf)Provides late-breaking information, such as software limitations, workarounds,and documentation updates.

Base informationv IBM Tivoli Access Manager Base Installation Guide

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

v IBM Tivoli Access Manager Base Administrator’s Guide

GC23-4684 (am39_admin.pdf)Describes the concepts and procedures for using Access Manager services.Provides instructions for performing tasks from the Web portal managerinterface and by using the pdadmin command.

v IBM Tivoli Access Manager Base for Linux on zSeries™ Installation Guide

GC23-4796 (am39_zinstall.pdf)Explains how to install and configure Access Manager Base for Linux on thezSeries platform.

WebSEAL informationv IBM Tivoli Access Manager WebSEAL Installation Guide

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

v IBM Tivoli Access Manager WebSEAL Administrator’s Guide

GC23-4682 (amweb39_admin.pdf)Provides background material, administrative procedures, and technicalreference information for using WebSEAL to manage the resources of yoursecure Web domain.

v IBM Tivoli Access Manager WebSEAL Developer’s Reference

vi IBM Tivoli Access Manager: WebSEAL Developer’s Reference

GC23-4683 (amweb39_devref.pdf)Provides administration and programming information for the Cross-domainAuthentication Service (CDAS), the Cross-domain Mapping Framework (CDMF),and the Password Strength Module.

v IBM Tivoli Access Manager WebSEAL for Linux on zSeries Installation Guide

GC23-4797 (amweb39_zinstall.pdf)Provides installation, configuration, and removal instructions for WebSEALserver and the WebSEAL application development kit for Linux on the zSeriesplatform.

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

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

v IBM Tivoli Access Manager for WebLogic Server User’s Guide

GC32-0851 (amwls39_user.pdf)Provides installation, removal, and administration instructions for AccessManager for BEA WebLogic Server.

v IBM Tivoli Access Manager Plug-in for Edge Server User’s Guide

GC23-4685 (amedge39_user.pdf)Describes how to install, configure, and administer the plug-in for IBMWebSphere Edge Server.

v IBM Tivoli Access Manager Plug-in for Web Servers User’s Guide

GC23-4686 (amws39_user.pdf)Provides installation instructions, administration procedures, and technicalreference information for securing your Web domain using the plug-in for Webservers application.

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

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

v IBM Tivoli Access Manager Authorization Java Classes Developer’s Reference

GC23-4688 (am39_authJ_devref.pdf)Provides reference information for using the Java™ language implementation ofthe authorization API to enable an application to use Access Manager security.

v IBM Tivoli Access Manager Administration C API Developer’s Reference

GC32-0843 (am39_adminC_devref.pdf)Provides reference information about using the administration API to enable anapplication to perform Access Manager administration tasks. This documentdescribes the C implementation of the administration API.

v IBM Tivoli Access Manager Administration Java Classes Developer’s Reference

SC32-0842 (am39_adminJ_devref.pdf)Provides reference information for using the Java language implementation ofthe administration API to enable an application to perform Access Manageradministration tasks.

Preface vii

v IBM Tivoli Access Manager WebSEAL Developer’s Reference

GC23-4683 (amweb39_devref.pdf)Provides administration and programming information for the Cross-domainAuthentication Service (CDAS), the Cross-domain Mapping Framework (CDMF),and the Password Strength Module.

Technical supplementsv IBM Tivoli Access Manager Performance Tuning Guide

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

v IBM Tivoli Access Manager Capacity Planning Guide

GC32-0847 (am39_capplan.pdf)Assists planners in determining the number of WebSEAL, LDAP, and backendWeb servers needed to achieve a required workload.

v IBM Tivoli Access Manager Error Message Reference

SC32-0845 (am39_error_ref.pdf)Provides explanations and recommended actions for the messages produced byAccess Manager.

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

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

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

IBM DB2® Universal Database™

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

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

IBM Global Security ToolkitAccess Manager provides data encryption through the use of IBM Global SecurityToolkit (GSKit). GSKit is shipped on the IBM Tivoli Access Manager Base CD foryour particular platform.

The GSKit package installs the iKeyman key management utility (gsk5ikm), whichenables you to create key databases, public-private key pairs, and certificaterequests. The following document is available in the /doc/GSKit directory:v Secure Sockets Layer Introduction and iKeyman User’s Guide

gskikm5c.pdf

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

IBM SecureWay DirectoryIBM SecureWay Directory, Version 3.2.2, is shipped on the IBM Tivoli AccessManager Base CD for your particular platform. If you plan to install the IBM

viii IBM Tivoli Access Manager: WebSEAL Developer’s Reference

SecureWay Directory server as your user registry, the following documents areavailable in the /doc/Directory path on the IBM Tivoli Access Manager Base CDfor your particular platform:v IBM SecureWay Directory Installation and Configuration Guide

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

Windows® operating systems.v IBM SecureWay Directory Release Notes

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

v IBM SecureWay Directory Readme Addendum

(addendum322.pdf)Provides information about changes and fixes that occurred after the IBMSecureWay Directory documentation had been translated. This file is in Englishonly.

v IBM SecureWay Directory Server Readme

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

v IBM SecureWay Directory Client Readme

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

v SSL Introduction and iKeyman User’s Guide

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

v IBM SecureWay Directory Configuration Schema

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

v IBM SecureWay Directory Tuning Guide

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

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

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

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

Preface ix

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

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

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

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

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

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

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

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

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

You can also order by telephone by calling one of these numbers:v In the United States: 800-879-2755v In Canada: 800-426-4968v In other countries, for a list of telephone numbers, see the following Web site:

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

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

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

x IBM Tivoli Access Manager: WebSEAL Developer’s Reference

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

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

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

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

you are locatedv What information to gather before contacting support

Conventions used in this bookThis guide uses several conventions for special terms and actions, operatingsystem-dependent commands and paths, and margin graphics.

Typeface conventionsThe following typeface conventions are used in this book:

Bold Command names and options, keywords, and other informationthat you must use literally appear in bold.

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

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

Preface xi

xii IBM Tivoli Access Manager: WebSEAL Developer’s Reference

Part 1. CDAS API Developer Reference

Chapter 1. CDAS API overview . . . . . . . 3Introducing the CDAS API . . . . . . . . . 3

Supported authentication methods . . . . . . 4Enabling dynamic business entitlements . . . . 4

CDAS authentication models . . . . . . . . . 5The single authentication CDAS model . . . . 5The credential extended attributes CDAS chainingmodel . . . . . . . . . . . . . . . 6

Chapter 2. Implementing a CDAS shared library . 9CDAS API components . . . . . . . . . . . 9

Header files . . . . . . . . . . . . . 9Software requirements for implementing acustom CDAS . . . . . . . . . . . . 10

Programming the CDAS shared library . . . . . 10Initialization: xauthn_initialize() . . . . . . 10Shutdown: xauthn_shutdown() . . . . . . . 10Authentication: xauthn_authenticate(). . . . . 11Password change: xauthn_change_password() . . 11

Valid user authentication data . . . . . . . . 12Returning the client identity (xauthn_identity_t) . . 15Specifying extended attributes . . . . . . . . 15Building the custom shared library . . . . . . 16Writing a CDAS for switch user . . . . . . . 16

Chapter 3. Configuring WebSEAL to use a CDAS 17Configuring and installing the CDAS shared library 17

Additional configuration for an extendedattributes CDAS . . . . . . . . . . . . 18

Using the example shared library . . . . . . . 18

Chapter 4. Authentication C API reference . . . 21Summary: CDAS and utility API functions . . . . 21xauthn_initialize() . . . . . . . . . . . . 23xauthn_shutdown() . . . . . . . . . . . . 24xauthn_authenticate() . . . . . . . . . . . 25xauthn_change_password() . . . . . . . . . 26xattr_get() . . . . . . . . . . . . . . . 27xattr_set() . . . . . . . . . . . . . . . 28xauthn_util_entry_to_creds(). . . . . . . . . 29xnvlist_get() . . . . . . . . . . . . . . 30xattr_list_item_t . . . . . . . . . . . . . 31xattr_list_t . . . . . . . . . . . . . . . 32xauthn_identity_t . . . . . . . . . . . . 33xnvlist_item_t . . . . . . . . . . . . . 34xnvlist_t . . . . . . . . . . . . . . . 35

© Copyright IBM Corp. 1999, 2002 1

2 IBM Tivoli Access Manager: WebSEAL Developer’s Reference

Chapter 1. CDAS API overview

The IBM®Tivoli®Access Manager Cross-domain Authentication Service (CDAS) is ashared library mechanism that allows you to substitute the default WebSEALauthentication mechanism with a custom process that ultimately returns an AccessManager identity to WebSEAL.

In addition, a secondary (“chained”) CDAS can be called to supply extendedattribute data (business entitlements) for inclusion in the user’s credential.

Topic Index:v “Introducing the CDAS API” on page 3v “CDAS authentication models” on page 5

Introducing the CDAS APIWebSEAL provides a set of default authentication mechanisms—in the form ofbuilt-in shared libraries—to support clients who access WebSEAL via usernameand password, client-side certificate, token passcode, IP address, or HTTP header.For authentication to succeed, these clients must be members of the AccessManager LDAP user registry.

The Cross-domain Authentication Service (CDAS) allows you to substitute thedefault built-in WebSEAL authentication mechanism with a highly flexible sharedlibrary mechanism that allows custom handling and processing of extendedattribute and client authentication information.

The CDAS API provides you with the necessary resources to build your owncustom CDAS shared library that can handle your extended attribute andauthentication requirements. The CDAS can return an Access Manager identity toWebSEAL for authentication against the Access Manager user registry.

You can customize the CDAS shared library to handle authentication data andextended attribute data according to your security requirements:v The custom CDAS can process authentication data internally and return an

Access Manager identity.v The custom CDAS can direct authentication data to be processed by an external

authentication mechanism and third-party registry. An Access Manager identityis returned to WebSEAL.This method allows you to authenticate clients who are not direct members ofthe Access Manager secure domain.

v The custom CDAS can add extended attribute information (known as businessentitlements) to the user’s Access Manager credential.These business entitlements can be extracted from the credential directly usingthe authorization API or inserted in the HTTP headers of requests directedacross a junction to a back-end application server.

The basic steps for implementing a custom CDAS shared library include:1. Identify the type of authentication method and data that you want to process2. Build a custom shared library using the CDAS API


3. Configure WebSEAL to use the custom shared library for the specified data

Both standard built-in and custom shared libraries load directly into WebSEALmemory and run as part of the WebSEAL process.

Supported authentication methodsYou use the [authentication-mechanisms] stanza of the webseald.confconfiguration file to configure supported authentication data types andimplementation mechanisms.

Examples of authentication data types include digital certificates, username andpassword, and token passcode. Examples of implementation mechanisms includethe standard shared libraries included with WebSEAL and custom-built sharedlibraries.

In the webseald.conf configuration file, you represent the supported authenticationdata with an identifier parameter. You specify the implementation mechanism withthe name of the shared library (standard or custom):<authentication-mechanism-parameter> = <shared-library>

The following identifiers specify local built-in shared libraries:v passwd-ldapv cert-sslv token-cdasv http-requestv cdsso

The following identifiers can be used to specify custom shared libraries for externalCDAS servers:v passwd-cdasv cert-cdasv token-cdasv http-requestv cred-ext-attrs (used for a ″chained″ extended attributes CDAS library)

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

Enabling dynamic business entitlementsBusiness enterprises and their partners often have the need to share commonentitlements such as partner data (in a business-to-business relationship) orcustomer data (in a business-to-customer relationship).

Through an extension of the Cross-domain Authentication Service (CDAS), AccessManager provides a flexible mechanism that allows you to place entiltlementinformation, in the form of extended attributes, into user credentials at the point ofauthentication.

These business entitlements can be used in any situation where this data isrequired. For example, entitlement data can be extracted from the credentialdirectly by an application using the authorization API or inserted in the HTTPheaders 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 usercredential: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 identifierparameter in the webseald.conf configuration file, as described in the previoussection. For more details on configuring an authentication mechanism, refer tothe IBM Tivoli Access Manager WebSEAL Administrator’s Guide.

v A second custom CDAS can be written to supply extended attribute data. In thisscenario, the authentication operation is performed by a built-in authenticationmechanism or a custom CDAS. The second CDAS is then called to supplyextended attribute data for inclusion in the user credential (CDAS chaining).This credential extended attributes CDAS is specified by the cred-ext-attrsidentifier in the webseald.conf configuration file. See “Additional configurationfor an extended attributes CDAS” on page 18

CDAS authentication modelsThe custom CDAS shared library must be written by the application developer. Inaddition, you must configure WebSEAL to recognize the specific type ofauthentication data being passed to the CDAS mechanism. When WebSEALreceives a client request, it passes the appropriate authentication data to thecustom shared library as a list of name/value pairs.

For example, if the CDAS library is written to handle username and passwordauthentication, the client authentication data must contain the user’s name and theuser’s password. However, if the shared library is written to handle certificateauthentication, the data must contain the client’s certificate, the distinguished name(DN) of the certificate, and the DN of the certificate issuer.

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

1. The client supplies authentication information to WebSEAL.2. In this example, WebSEAL is configured to use a custom CDAS shared library

to handle this type of authentication data.

Client

ResourceManager

ExternalAuthentication

Service

authenticationinformation

identity

1

WebSEAL

Custom CDAS SharedLibrary

authninfo

2

3

4

UserRegistry

ExternalRegistry

5

Figure 1. Example CDAS authentication model

Chapter 1. CDAS API overview 5

The CDAS shared library could authenticate this user internally and pass theresulting Access Manager identity back to WebSEAL (Step 4). For example, theshared library could accept a digital certificate, modify the Distinguished Name(DN) data, and return the modified DN as the Access Manager identity.

3. The custom shared library could instead send the data to an externalauthentication 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

an 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 attributedata 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 Access Manager user registry (LDAP). If a match is found,WebSEAL treats the client as authenticated. Otherwise, it treats the client asunauthenticated.

b. For an unsuccessful status code, WebSEAL automatically treats the client asunauthenticated.

A successful authentication results in an Access Manager credential for the user.Any extended attribute data is included in the credential and can be extractedlater for appropriate use. The credential allows the user to participate in theAccess Manager secure domain.

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

If Access Manager successfully authenticates the identity received from the CDASchain, a credential is built for the user that includes the identity information andthe extended attribute data.

The following diagram illustrates an example of the CDAS chain functionality. Theindividual numbered steps are described below the diagram:


1. The client supplies authentication information to WebSEAL.2. In this example, WebSEAL is configured to use a custom CDAS shared library

to handle this type of authentication data.The CDAS shared library could authenticate this user internally and pass theresulting Access Manager identity back to the resource manager (Step 4). Forexample, the shared library could accept a digital certificate, modify theDistinguished Name (DN) data, and return the modified DN as the AccessManager identity.

3. The custom shared library could instead send the data to an externalauthentication service that performs its own authentication of the client,perhaps using a third-party (legacy) user registry.

4. The 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) andan 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 withan entry in the Access Manager user registry (LDAP). If a match is found,WebSEAL treats the client as authenticated. Otherwise, it treats the client asunauthenticated.

b. For an unsuccessful status code, WebSEAL automatically treats the client asunauthenticated.A successful authentication results in an Access Manager credential for theuser. The extended attribute data is included in the credential and can beextracted later for appropriate use. The credential allows the user toparticipate in the Access Manager secure domain.

Client

ResourceManager

ExternalAuthentication

Service

authenticationinformation

identity

1

WebSEAL

Authentication Module(built-in or CDAS libraries)

authninfo

2

3

4

UserRegistry

ExternalRegistry

6

Extended AttributesCDAS

5identity

andattributes

buildcredentialidentity

and authn info

7

Figure 2. Example extended attributes CDAS model

Chapter 1. CDAS API overview 7

Chapter 2. Implementing a CDAS shared library

The specific operation of a customized authentication and mapping service aredetermined entirely by the CDAS developer. It is the responsibility of thedeveloper to use the resources of the CDAS API to implement the authenticationand data handling requirements of a particular application.

Topic Index:v “CDAS API components” on page 9v “Programming the CDAS shared library” on page 10v “Valid user authentication data” on page 11v “Returning the client identity (xauthn_identity_t)” on page 15v “Specifying extended attributes” on page 15v “Building the custom shared library” on page 16v “Writing a CDAS for switch user” on page 16

CDAS API componentsThe CDAS API can be found in the PDWebADK package (part of PDWeb) andconsists of the following components:v API library (utility functions)v API header filesv Example CDAS shared library file (for demonstration only)v Makefiles

The CDAS API is located in a directory named pdxauthn_adk. The APIcomponents are contained in the following subdirectories:

Directory Contents

include This directory contains the C header files.See “Header files” on page 9.

lib This directory contains the CDAS authentication staticlibrary files:- UNIX systems: libpdxauthn.a- Windows systems: pdxauthn.lib

example The example directory contains:- Source file (xauthn.c)- Makefile- A pre-built platform-specific example shared library todemonstrate a functional CDAS.

Header filesThe following header files are contained in the include directory.

Files Contents

pdxauthn.h Definition of function prototypes, client identity, and error codesused for authentication API functions

xnvlist.h User authentication data structure utility functions


Files Contents

xattr.h User extended attributes data structure utility functions

Software requirements for implementing a custom CDASThe CDAS API provides all the necessary resources for CDAS applicationdevelopment.

The minimum installation consists of a single system with the following AccessManager components (installed in the order listed):v Access Manager Runtime (PDRTE)v Access Manager policy server (PDMgr)v Access Manager authorization ADK (PDAuthADK)v Access Manager WebSEAL (PDWeb)v Access Manager WebSEAL ADK (PDWebADK)

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

Programming the CDAS shared libraryA custom CDAS shared library must implement each of the following four CDASAPI 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 shared library and initializes it by callingxauthn_initialize().

This function contains the argc and argv parameters. These parameters contain thevalues specified in the shared library definition located in the webseald.confconfiguration file. The shared library definition uses the following syntax:<authn-mechanism-parameter> = <shared-library>[&arg1]...[ argN]

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

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

Shutdown: xauthn_shutdown()During shutdown, WebSEAL calls the xauthn_shutdown() interface to stop theCDAS shared library process.

Note: The shutdown interface is not functional in Access Manager 3.9. It exists forfuture development and implementation.


The xauthn_shutdown() interface is called with the same argc and argv parametersthat were passed to the xauthn_initialize() interface when the shared library wasfirst initialized.

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

Authentication: xauthn_authenticate()Once the CDAS shared library is configured, WebSEAL passes the client request tothe shared library through the xauthn_authenticate() interface.

User authentication information is passed to this interface in a name/value datalist (xnvlist_t). The content of the name/value data list can vary and is specific tothe configured authentication method. “Valid user authentication data” on page 11lists the possible client authentication data handled by the shared library.

The xauthn_authenticate() interface performs the application-specificauthentication process based on the authentication information found in the datalist, and returns the resulting client identity (xauthn_identity_t) to WebSEAL.

It is important to note that the client identity returned through this interface cancontain 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 isstored in the third-party user registry. Only the username and passwordauthentication method supports this function. If the external authenticationmechanism you are going to implement does not support password changes, thisfunction should return:XAUTHN_S_UNSUPPORTED_AUTHN_METHOD

User authentication information is passed to this interface in a name/value datalist (xnvlist_t). The data list contains the user’s name, the old password, and thenew password. “Valid user authentication data” on page 11 lists the possibleparameters passed to this function.

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

Valid user authentication dataWebSEAL can pass a variety of client authentication information to the sharedlibrary. The information is passed using a name/value list format, where the nameis an identifier that specifies the value type.

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

For more information on retrieving values from xnvlist_t, see the reference pagefor xnvlist_get().

The following table lists the possible names and values for each authenticationmethod:

Chapter 2. Implementing a CDAS shared library 11

Authentication Method Name Value

Username/Password xauthn_usernamexauthn_passwordxauthn_ipaddrxauthn_qopxauthn_browser_infoxauthn_new_password(only forxauthn_change_passwordinterface)xauthn_existing_cred

- User name- User password- User IP address- Quality of protection- Browser information- User new password

- During reauthentication,the user’s existing credentialas a string.

X.509 Certificate xauthn_cert

xauthn_cert_dnxauthn_cert_issuer_dnxauthn_ipaddrxauthn_qopxauthn_browser_infoxauthn_existing_cred

- The certificate body in- DER format- The certificate’s DN- The issuer’s DN- User IP address- Quality of protection- Browser information- During reauthentication,the user’s existing credentialas a string.

Token xauthn_usernamexauthn_tokenxauthn_ipaddrxauthn_qopxauthn_browser_infoxauthn_existing_cred

- User name- User token (passcode)- User IP address- Quality of protection- Browser information- During reauthentication,the user’s existing credentialas a string.

IP Address xauthn_ipaddrxauthn_qopxauthn_browser_infoxauthn_existing_cred

- User’s IP Address- Quality of protection- Browser information- During reauthentication,the user’s existing credentialas a string.

HTTP Header “Request-URI”xauthn_ipaddrxauthn_qopxauthn_browser_info<header-name>xauthn_existing_cred

- The request URI.- User’s IP Address- Quality of protection- Browser information- HTTP header name- During reauthentication,the user’s existing credentialas a string.



Switch User - Password xauthn_su_methodxauthn_admin_name

xauthn_admin_cred

xauthn_existing_cred

xauthn_username

xauthn_ipaddrxauthn_qop

xauthn_browser_info

- “su-password”- The user name of theadministrator attemptingto switch user- The credential of theadministrator attemptingto switch user, as a string- During reauthentication,the credential of the“switched-to” user, as astring- The user name of the“switched-to” user- Administrator IP address- Administrator quality ofprotection- Administrator browserinformation

Switch User - Token Card xauthn_su_methodxauthn_admin_name

xauthn_admin_cred


xauthn_username


xauthn_browser_info

- “su-token-card”- The user name of theadministrator attemptingto switch user- The credential of theadministrator attemptingto switch user, as a string- During reauthentication,the credential of the“switched-to” user, as astring- The user name of the“switched-to” user- Administrator IP address- Administrator quality ofprotection- Administrator browserinformation

Switch User - Certificate xauthn_su_methodxauthn_admin_name

xauthn_admin_cred


xauthn_username


xauthn_browser_info

- “su-certificate”- The user name of theadministrator attemptingto switch user- The credential of theadministrator attemptingto switch user, as a string- During reauthentication,the credential of the“switched-to” user, as astring- The user name of the“switched-to” user- Administrator IP address- Administrator quality ofprotection- Administrator browserinformation



Switch User - HTTPRequest

xauthn_su_methodxauthn_admin_name

xauthn_admin_cred


xauthn_username


xauthn_browser_info

- “su-http-request”- The user name of theadministrator attemptingto switch user- The credential of theadministrator attemptingto switch user, as a string- During reauthentication,the credential of the“switched-to” user, as astring- The user name of the“switched-to” user- Administrator IP address- Administrator quality ofprotection- Administrator browserinformation

Switch User - CDSSO xauthn_su_methodxauthn_admin_name

xauthn_admin_cred


xauthn_username


xauthn_browser_info

- “su-cdsso”- The user name of theadministrator attemptingto switch user- The credential of theadministrator attemptingto switch user, as a string- During reauthentication,the credential of the“switched-to” user, as astring- The user name of the“switched-to” user- Administrator IP address- Administrator quality ofprotection- Administrator browserinformation

Notes concerning the HTTP header authentication method names and values:v The “Request-URI” name is a literal string, not a variable.v The format of the xnvlist_t data structure differs for the HTTP header

authetication method. The <header-name> stored in xnvlist_t is the header namespecified in the [auth-headers] stanza of the webseald.conf configuration file.The value is the authentication information passed via that header.

Notes concerning the xauthn_admin_cred and xauthn_existing_cred xnvlist_tentries:

The xauthn_admin_cred and xauthn_existing_cred entries in the xnvlist_tauthentication data structure contain encoded Access Manager credentials. Use thexauthn_util_entry_to_creds() function to access the credential. An example of howto use the function is included in the sample xauthn source code included in thePDWebADK package.


Returning the client identity (xauthn_identity_t)The CDAS shared library is required to return the resulting client identity back toWebSEAL. The client identity is defined by the xauthn_identity_t data structure.

See the reference page for xauthn_identity_t.

Specifying extended attributesThe Access Manager CDAS allows you to add extended attribute data (businessentitlements) to a user credential. These business entitlements can be used in anysituation where this type of data is required. For example, entitlement data can beextracted from the credential directly by an application using the AuthorizationAPI or inserted in the HTTP headers of requests directed across a junction to aback-end application server.

The structure of the returned client identity (xauthn_identity_t) allows you tospecify extended attribute information. This additional information becomes part ofthe resulting Access Manager credential. You define extended attribute informationwith 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 datacannot 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, thetag name is prefixed with the macro XAUTHN_TAG_VALUE_PREFIX, which isdefined as “tagvalue_”.

The following section of the xauthn.c demo program illustrates this action:char *tag = (char *) malloc(1024);char *tag_data = (char *) malloc(1024);

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

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

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

The following example illustrates a method of calling xattr_set to supply tag/valuedata (business entitlements) in a custom CDAS:xattr_set(&ident->xattrs,

strdup(“tagvalue_ldap-emplpoyee-number”)strdup(“12345678”) );

xattr_set(&ident->xattrs,strdup(“tagvalue_ldap-employee-phone”)strdup(“888-888-8888”) );


Building the custom shared libraryWhen compiling the shared library, make sure you add the include directory ofthe ADK to the compiler command line. When linking the library, make sure youinclude the appropriate pdxauthn library (see “CDAS API components” on page9).

The ADK has provided a generic Makefile template named Makefile.in under theexample directory. You can use the Makefile to compile the required library withminimum changes. Details on how to use the Makefile.in template are includedinside the template itself.

Writing a CDAS for switch userAn existing CDAS authentication mechanism often returns additional informationabout the user that is incorporated into the user’s credential. If you are using theswitch user feature in such an environment, you must write a special switch userCDAS that emulates the behavior of your existing CDAS while supporting therequirement of returning a credential without requiring the user password forinput.

The Access Manager CDAS API provides a set of identity components that can beused to pass client authentication information to the shared switch user CDASlibrary. This information is passed using a name/value list format, where the nameis an identifier that specifies the value type.

The information is stored in the xnlist_t data type. Values can be accessed by usingthe utility function xnvlist_get().

Identity components appropriate for a switch user CDAS include:xauthn_su_methodxauthn_admin_namexauthn_admin_credxauthn_existing_credxauthn_usernamexauthn_qopxauthn_ipaddrxauthn_browser_info

The xauthn_browser_info, xauthn_qop, and xauthn_ipaddr identity componentsrepresent those of the administrator, not the “switched to” user. This data issupplied for any CDAS that must perform additional validations of theadministrator’s account.

Refer to “Valid user authentication data” on page 11.


Chapter 3. Configuring WebSEAL to use a CDAS

By default, WebSEAL is set to authenticate clients over SSL using built-in supportfor Basic Authentication (BA) user names and passwords (LDAP user registry).WebSEAL contains other built-in authentication mechanisms that supportauthentication via client-side certificates, Forms, token passcode, HTTP header, andIP address.

You can also configure WebSEAL to accept the following authentication data typesthat are handled by a custom CDAS. Examples include:v Username and password belonging to a third-party user registryv Client-side certificatev Token passcodev HTTP headerv IP address

If you require a custom CDAS, you must configure WebSEAL to recognize thespecific authentication information type and process that information via thecustom shared library.

This chapter discusses the specific configuration steps you must perform so thatWebSEAL can use the CDAS interface.

Topic Index:v “Configuring and installing the CDAS shared library” on page 17v “Using the example shared library” on page 18

Configuring and installing the CDAS shared libraryPerform the following steps to configure WebSEAL to use a custom CDAS sharedlibrary:1. Enter the appropriate authentication identifier parameter, with the name of the

shared library, in the [authentication-mechanisms] stanza of the webseald.confconfiguration file. See “Supported authentication methods” on page 4.For example, if you want to externalize LDAP username/passwordauthentication using a custom shared library named libxauthn.so (for a Solarissystem), enter the following line:passwd-ldap = libxauthn.so

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

3. Copy the custom library to the WebSEAL lib directory and create a soft link tothe system lib directory. For example, using the sample shared libraryprovided with the ADK for Solaris (libxauthn.so):# cp <build-dir>/libxauthn.so /opt/pdweb/lib# ln -s /opt/pdweb/lib/libxauthn.so /usr/lib

4. Restart WebSEAL (webseald).


Additional configuration for an extended attributes CDASCDAS chaining allows a second CDAS module to be called after the initialauthentication module (built-in or custom CDAS) for the purpose of addingextended attribute data to the Access Manager identity. Typically, the AccessManager identity is obtained via a standard built-in authentication module. Thesecondary 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 shared library for thesecondary 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 shared libraryThe Access Manager CDAS API comes with an example shared library thatimplements a generic username and password CDAS authentication mechanism.The sample library is an interactive program that displays all the available clientauthentication data and prompts for a user identity.

In addition, the example shared library can be used as an extended attributesCDAS. In this case, the prompts ask for tag/value data instead of clientauthentication data.

The example library is located in the example directory of the CDAS ADKpackage. To use the sample shared library, configure WebSEAL as described in“Configuring and installing the CDAS shared library” on page 17.

Then execute WebSEAL (webseald) in the foreground. For example (on a Solarissystem):# /opt/pdweb/bin/webseald -foreground

The program user interface—for client authentication data—appears as follows:---------------------------------------------------------Access Manager WebSEAL Version 3.9 (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 interface—for tag/value data—appears as follows:---------------------------------------------------------Access Manager WebSEAL Version 3.9 (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)Using existing name: testuserEnter the test tag: <tag>Enter the test tag data: <value>---------------------------------------------------------

Chapter 3. Configuring WebSEAL to use a CDAS 19

Chapter 4. Authentication C API referencev “Summary: CDAS and utility API functions” on page 21

CDAS API Functions:

v “xauthn_initialize()” on page 23v “xauthn_shutdown()” on page 24v “xauthn_authenticate()” on page 25v “xauthn_change_password()” on page 26

Utility API Functions:

v “xattr_get()” on page 27v “xattr_set()” on page 28v “xauthn_util_entry_to_creds()” on page 29v “xnvlist_get()” on page 30

Data Structures:

v “xattr_list_item_t” on page 31v “xattr_list_t” on page 32v “xauthn_identity_t” on page 33v “xnvlist_item_t” on page 34v “xnvlist_t” on page 35

Summary: CDAS and utility API functionsYou must implement the following four CDAS API functions in your customCDAS 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 customshared 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 theAccess Manager identity.

v xauth_util_entry_to_creds()v xnvlist_get()

This utility function retrieves authentication data from the xnvlist_t datastructure that was passed to the xauthn_authenticate() andxauthn_change_password() functions.

The CDAS implementation makes use of the following five data structures:


v xattr_list_item_tv xattr_list_tv xauthn_identity_tv xnvlist_item_tv xnvlist_t


xauthn_initialize()Initializes the specified CDAS shared library.

Syntaxxauthn_status_txauthn_initialize(

int argc,const char **argv

);

DescriptionUse this initialization function to initialize an authentication shared library. Theinput parameters argc and argv are built from parameters specified in the[authentication-mechanisms] stanza of the webseald.conf configuration file. Thefollowing 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 argvarray contains the following values:argv[0] = “-dbms”argv[1] = “sys.db”

Input parameters should not be modified.

ParametersInput

argcThe number of arguments contained in the argv array.

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

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

Chapter 4. Authentication C API reference 23

xauthn_shutdown()Shuts down the specified CDAS shared library.

Syntaxxauthn_status_txauthn_shutdown(

int argc,const char **argv

);

DescriptionDuring the normal shutdown, the WebSEAL authentication dispatcher calls thisinterface to perform any shut down processes that may required by the customenvironment. The input parameters argc and argv are built from the parametersspecified in the [authentication-mechanisms] stanza of the webseald.confconfiguration file. The following example definition uses the sample CDAS sharedlibrary:passwd-ldap = libxauthn.so& -dbms sys.db

In the above example, xauthn_shutdown() is called with an argc value of 2. Theargv array contains the following values:argv[0] = “-dbms”argv[1] = “sys.db”

ParametersInput

argcThe number of arguments contained in the argv array.

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


Note: The shutdown interface is not functional in Access Manager 3.9. It exists forfuture development and implementation.


xauthn_authenticate()Performs the CDAS authentication.

Syntaxxauthn_status_txauthn_authenticate(

xnvlist_t *authnInfo,xauthn_identity_t *ident

);

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

Refer to “Valid user authentication data” on page 11 for the list of authenticationdata that authnInfo can contain.

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

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

ParametersInput

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

Input/Output

identThe ident parameter contains the authenticated user information.



xauthn_change_password()Performs the password change.

Syntaxxauthn_status_txauthn_change_password(

xnvlist_t *authnInfo);

DescriptionThe authentication dispatcher calls this interface to implement a custom passwordchange mechanism. This interface is only supported only for username andpassword authentication mechanism. Client password change information ispassed by the dispatcher through the input argument authnInfo.

Refer to “Valid user authentication data” on page 11 for the list of authenticationdata that authnInfo can contain.

ParametersInput

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

Return ValuesIf successful, the function returns XAUTHN_S_COMPLETE.

XAUTHN_S_UNSUPPORTED_AUTHN_METHOD is returned if the externalauthentication process does not support password changes.

Other possible error codes can be found in the pdxauthn.h header file.


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

Syntaxintxattr_get(

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

);

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

ParametersInput

listA pointer to the name/value list.

nameA pointer to a name of the attribute to retrieve.

Output

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

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


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

Syntaxintxattr_set(

xattr_list_t *list,char *name,char *value

);

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

ParametersInput


nameA pointer to a name. The name should be dynamically allocated usingmalloc().

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



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

Syntaxazn_creds_h_txauthn_util_entry_to_creds(

const char *value,int vlen

);

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

ParametersInput

valueThe value retrieved by the call to xvnlist_get() for the entry which contains thecredential.

vlenThe length returned by the call to xnvlist_get() for the entry which containsthe credential.

Return ValuesThe function returns a valid credential if successful, orAZN_C_INVALID_HANDLE if an error occurs.


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

Syntaxintxnvlist_get(

xnvlist_t *list,char *name,char **value,int *vlen

);

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

ParametersInput


nameA pointer to a name whose value is to be retrieved.

Output

valueA pointer to a pointer that stores the value of a given name. The caller of thisfunction should free the memory for the **value when finished.

vlenA pointer to a pointer that stores the length of the returned value.



xattr_list_item_tThe data structure that holds a single extended attribute.

Definitiontypedef struct {

char *name;char *value;

} xattr_list_item_t;

Valuesname

A string representing the name of the extended attribute.

valueA string representing the value of the extended attribute.


xattr_list_tA list of extended attributes to be added to the credential.


long length;xattr_list_item_t *items;

} xattr_list_t;

Valueslength

The number of elements in the list.

itemsAn array of xttr_list_item_t structures.


xauthn_identity_tThe data structure used to hold information about a user’s Access Manageridentity.


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;

Valuesprin_type

Should be set to XAUTHN_PRIN_TYPE_DN

nameNot valid.

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

uraf_nameNot valid.

user_infoInformation added to the credential as an extended attribute calledazn_cred_user_info.

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

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

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


xnvlist_item_tThe data structure that holds a single item of authentication data.


char *name;char *value;int vlen;

} xnvlist_item_t;

Valuesname

A string representing the name of the item. Valid names are descibed in “Validuser authentication data” on page 11.

valueAn array of bytes representing the value of the item.

vlenThe length of the “value” array.

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


xnvlist_tThe data structure that holds a list of xnvlist_item_t authentication data structures.


long length;xnvlist_item_t *items;

} xnvlist_t;

Valueslength

The number of elements in the “items” array.

itemsAn array of xnvlist_item_t.


Part 2. CDMF API Developer Reference

Chapter 5. Using a CDMF shared library . . . . 39Introducing the Cross-domain Mapping Framework 39

Using CDMF in a CDSSO environment . . . . 39Using CDMF in an e-community environment. . 40

CDMF API components . . . . . . . . . . 40Software requirements . . . . . . . . . . 41

Implementing the CDMF shared library . . . . . 41The CDMF library partnership . . . . . . . 41

Customizing the CDMF shared library . . . . . 42Providing user attributes:cdmf_get_usr_attributes() . . . . . . . . . 42Providing identity mapping: cdmf_map_usr() . . 42Naming the custom shared library. . . . . . 43

Specifying extended attributes . . . . . . . . 43

Chapter 6. CDMF C API reference . . . . . . 45Summary: CDMF API functions and macros . . . 45cdmf_map_usr() . . . . . . . . . . . . . 47cdmf_get_usr_attributes() . . . . . . . . . . 48cdmf_create_usr_attr_list() . . . . . . . . . 49cdmf_create_usr_attr() . . . . . . . . . . . 50cdmf_add_value_to_attr(). . . . . . . . . . 51cdmf_add_attr_to_list() . . . . . . . . . . 52CDSSO_STRDUP() . . . . . . . . . . . . 53CDSSO_MALLOC() . . . . . . . . . . . 54CDSSO_FREE() . . . . . . . . . . . . . 55CDSSO_REALLOC() . . . . . . . . . . . 56


Chapter 5. Using a CDMF shared library

The specific operation of a customized CDMF shared library is determined entirelyby the developer. It is the responsibility of the developer to use the CDMF APIfunctions and utilities to implement the required cross domain identity mappingand extended user attribute handling.

Topic Index:v “Introducing the Cross-domain Mapping Framework” on page 39v “CDMF API components” on page 40v “Implementing the CDMF shared library” on page 41v “Customizing the CDMF shared library” on page 42v “Specifying extended attributes” on page 43

Introducing the Cross-domain Mapping FrameworkThe Cross-domain Mapping Framework (CDMF) is a programming interface youcan use to build a custom shared library that provides mapping services for a useridentity and handles any extended user attributes.

The CDMF is an important component used with the two Access Manager crossdomain single sign-on solutions:v Cross-domain Single Sign-on (CDSSO)v E-community Single Sign-on

Using CDMF in a CDSSO environmentThe Access Manager Cross-domain Single Sign-on (CDSSO) provides a mechanismfor transferring user credentials across multiple secure domains. CDSSO allowsWeb users to perform a single sign-on and move seamlessly between two separatesecure domains.

CDSSO supports the goals of scalable network architecture by allowing theintegration of multiple secure domains. For example, a large corporate extranet canbe set up with two or more unique domains—each with its own users and objectspace. CDSSO allows movement of users between the domains with a singlesign-on.

When a user makes a request to a resource located in another domain, the CDSSOmechanism transfers an encrypted user identity token from the first domain to thesecond domain. The second domain now has the user’s identity (as authenticatedin 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 fromdifferent domains may not suit all deployment requirements. The CDMF allowsthe mapping of a remote user to a local user identity.

For CDSSO background, administration, and configuration information, refer to theIBM Tivoli Access Manager WebSEAL Administrator’s Guide.


Using CDMF in an e-community environmentE-community single sign-on is another implementation of cross-domainauthentication in an Access Manager environment. The goal of cross-domainauthentication is to allow users to access resources across multiple servers inmultiple domains without re-authentication.

An “e-community” is a group of distinct domains (Access Manager or DNS) thatparticipate in a business relationship. These participating domains can beconfigured as part of one business (and perhaps using different DNS names forgeographic reasons), or as disparate businesses with a shared relationship (forexample, company headquarters, a life insurance company, and a financialmanagement company).

Authentication information about the users who participate in the e-community(including the user names and passwords used for authentication) is maintained inthe home domain. This arrangement allows a single point of reference foradministration issues, such as help desk calls within the e-community that all referto the home domain.

Individual e-community domains manage their own user identities and associatedprivileges. You can use the CDMF to map a user from a remote domain to a validuser in the local domain. If the e-community domains share global identities, thismapping function is not required.

For e-community background, administration, and configuration information, referto the IBM Tivoli Access Manager WebSEAL Administrator’s Guide.

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

Files Description

cdmf.c.skeleton The source file that can be customized by thedeveloper to implement the CDMF logic. This fileneeds to be renamed to cdmf.c and then compiled andlinked into the CDMF shared library.

cdmf.c.example Example cdmf.c fileThis example performs a simple user mapping andperforms some manipulation of the CDSSO attributelists.

cdmf.h The header file for cdmf.c.

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

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

Windows only:

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


Files Description

Makefile.win32 The nmake Makefile used to build the custom CDMFshared library.

UNIX only:

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

Makefile.cdmf.in The template Makefile used to build the CDMFlibrary. Change this file to suit your platform.

Software requirementsThere are no software dependencies when building the CDMF shared library.

To use a CDMF shared library, you must have at least two Access Manager securedomains installed, each containing a WebSEAL server.

Implementing the CDMF shared library1. 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 anduser 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 shared library. Provide the following platform-specificname for the shared library file:

Solaris libcdmf.so

AIX libcdmf.a

HP-UX libcdmf.sl

Windows cdmf.dll

See “Customizing the CDMF shared library” on page 42

Note: If you build the CDMF shared library on a Solaris system using C++ andSun Workshop 5 or greater, the shared 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 Access Manager

product with the customized version.7. Start webseald.

The CDMF library partnershipTwo CDMF libraries always work as partners. One CDMF library—associated withthe local WebSEAL server (CDSSO) or the “vouch for” server

Chapter 5. Using a CDMF shared library 41

(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 thefollowing 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 remotedomain that is the target of the request.

Customizing the CDMF shared libraryThe custom CDMF shared library must contain two application programminginterfaces. The first interface, called by the local WebSEAL server (CDSSO) or the“vouch for” server (e-community), serves the request by providing extended userattribute 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 identitymapping 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 bepassed 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 localWebSEAL server (CDSSO) or the “vouch for” server (e-community).

The output parameter is the attribute list constructed by the CDMF utilityfunctions.

In a CDSSO scenario, the attribute list is included in the authentication token thatis constructed and sent to the remote WebSEAL server that is the target of therequest.

In an e-community scenario, this attribute list is included in the “vouch for” replytoken sent to the remote WebSEAL server that is the target of the request.

The CDMF library at the remote WebSEAL server can use the informationcontained in this attribute list when producing a user identity.

Providing identity mapping: cdmf_map_usr()The cdmf_map_usr() interface is called by WebSEAL to perform the mapping fromthe 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 BWebSEAL server, the identity of the local user must be determined. Thecdmf_map_usr() interface is called to map the remote user (who initiated theCDSSO request) to a local user identity.

v When a URL containing an e-community “vouch for” token is received byWebSEAL.When a “vouch for” reply token is received by a WebSEAL server (which is thetarget of the request) from a “vouch for” server, that WebSEAL server may berequired to map the identity of the requesting user to a local user identity.

The input parameter to this function is the cdsso_usr_info_t data type, whichcontains the user name, domain, and an attribute list. This input information isused by the custom CDMF shared library to determine a local user identity. Anyinformation contained in the attribute list was added by thecdmf_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 onlyrequired field is the user name, which is the short name of the local (or requesting)user. The local user’s attribute list is an optional field that can be filled out if theuser’s credential requires extended attributes.

Because the credential’s extended attribute list only supports one value, only thefirst value for each attribute will become part of the user’s credential. The domainfield 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 shared libraryYou must name the custom shared library appropriately for your platform:

Platform File Name

Solaris libcdmf.so

AIX libcdmf.a

HP-UX libcdmf.sl

Windows cdmf.dll

Specifying extended attributesBoth CDMF application programming interfaces support additional userinformation in the form of a CDSSO attribute list.

Although this type is called a CDSSO attribute list, this list can be used by theCDMF functions to communicate user information in both CDSSO ande-community scenarios.

The CDSSO attribute list cdsso_attrlist_t is a name/multiple value data list that isdefined in cdssotypes.h.

Chapter 5. Using a CDMF shared library 43

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

These utility functions perform the following operations:v Create a CDSSO user attribute listv Create a CDSSO user attributev Add a value to a CDSSO user attributev 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()


Chapter 6. CDMF C API referencev “Summary: CDAS and utility API functions” on page 21

CDMF API functions:

v “cdmf_map_usr()” on page 47v “cdmf_get_usr_attributes()” on page 48

Utility API functions:

v “cdmf_create_usr_attr_list()” on page 49v “cdmf_create_usr_attr()” on page 50v “cdmf_add_value_to_attr()” on page 51v “cdmf_add_attr_to_list()” on page 52

Memory management macros:

v “CDSSO_STRDUP()” on page 53v “CDSSO_MALLOC()” on page 54v “CDSSO_FREE()” on page 55v “CDSSO_REALLOC()” on page 56

Summary: CDMF API functions and macrosThe 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 userattributes: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 cansafely clean up any allocated memory:v CDSSO_STRDUP()v CDSSO_MALLOC()v CDSSO_FREE()v CDSSO_REALLOC()

Windows-specific macros


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


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

Syntaxintcdmf_map_usr(

cdsso_user_info_t *remote_usr,cdsso_user_info_t *local_usr

);

DescriptionThe WebSEAL cdsso authentication mechanism calls this interface to determine theidentity 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. Thisinformation includes the remote user name, the remote domain name, and possiblyan extended attribute list. This information should be used to determine theidentity of the local user.

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

If an attribute list is to be returned, then the functions defined in cdmf_utils.hshould be used to construct the list. Information from this attribute list is includedin the Access Manager credential for that client.

If the function is not able to determine the identity of the local user,CDMF_NOMAP should be returned.

Note that if CDMF_SUCCESS is not returned, no memory clean up is performedon the fields of the local user structure.

ParametersInput

remote_usrOut of domain user.

Input/Output

local_usrUser mapped to in this domain.

Return ValuesIf successful, the function returns CDMF_SUCCESS.

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

Upon failure, the function returns CDMF_FAILURE.

Chapter 6. CDMF C API reference 47

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

Syntaxintcdmf_get_usr_attributes(

char *usr,cdsso_attrlist_t **attr_list

);

DescriptionWebSEAL 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 sentto the remote WebSEAL server (the target of the request) inside the authenticationtoken.

In an e-community “vouch for” operation, the attribute list returned by thisfunction 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 usermapping.

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.

ParametersInput

usrUser name.

Output

attr_listExtended attributes for input user.

Return ValuesIf successful, the function returns CDMF_SUCCESS.

Upon failure, the function returns CDMF_FAILURE.


cdmf_create_usr_attr_list()Create an empty attribute list.

Syntaxcdsso_attrlist_t *cdmf_create_usr_attr_list(

void);

DescriptionCreate an empty attribute list.

ParametersNone.

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

Otherwise, the function returns NULL.


cdmf_create_usr_attr()Create a new user attribute.

Syntaxcdsso_usr_attr_t *cdmf_create_usr_attr(

char *attr_name);

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

ParametersInput

attr_nameName of the new attribute.

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

Otherwise, the function returns NULL.


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

Syntaxintcdmf_add_value_to_attr(

char *new_value,cdsso_usr_attr_t *attr

);

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

ParametersInput

new_valueNew value to be added to the attribute.

Output

attrUpdated user attribute object.

Return ValuesIf successful, the function returns TRUE.

Otherwise, the function returns FALSE.


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

Syntaxintcdmf_add_attr_to_list(

cdsso_usr_attr_t *new_attr,cdsso_attrlist_t *list

);

DescriptionAdd the specified user attribute to the specified user attribute list.

ParametersInput

new_attrNew attribute to be added to the list.

Output

listUpdated list.

Return ValuesIf successful, the function returns TRUE.

Otherwise, the function returns FALSE.


CDSSO_STRDUP()Duplicate the specified string.

SyntaxCDSSO_STRDUP(

char *dest,char *src

);

DescriptionDuplicate the specified string.

Parametersdest

Destination string.

src Source string.

Return ValuesNone.


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

Syntaxvoid *CDSSO_MALLOC(

size_t size,);

DescriptionAllocate a portion of memory of the specified size.

Parameterssize

Size of memory to allocate.

Return ValuesReturns a pointer to newly allocated memory.


CDSSO_FREE()Deallocate the specified memory.

SyntaxCDSSO_FREE(

void *ptr,);

DescriptionDeallocate the specified memory.

Parametersptr A pointer to the memory to be deallocated.

Return ValuesNone.


CDSSO_REALLOC()Reallocate a memory block.

Syntaxvoid *CDSSO_REALLOC(

void *curr_ptr,size_t new_size

);

DescriptionReallocate a memory block.

Parameterscurr_ptr

Point to the existing memory to be deallocated.

new_sizeSize of the new portion of memory.

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


Part 3. Password Strength Module Reference

Chapter 7. Customizing password strengthpolicy . . . . . . . . . . . . . . . . 59Password strength policy overview . . . . . . 59

Introducing the Password Strength PolicyModule . . . . . . . . . . . . . . . 59

Building the custom Password Strength Module . . 60


Chapter 7. Customizing password strength policy

Password strength refers to the stipulations placed on the construction of apassword by password policy rules. This chapter discusses how you can customizeyour password strength policy using the password strength module provided inthe Access Manager authorization ADK package.

Topic Index:v “Password strength policy overview” on page 59v “Building the custom Password Strength Module” on page 60

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

policy

Introducing the Password Strength Policy ModuleAccess Manager provides resources that allow you to customize your passwordstrength policy. This password strength module is part of the PDAuthADKinstallation package.

The instructions for using this module are in a README file located in thepwdstr_adk directory. The contents of this README are reproduced in “Buildingthe custom Password Strength Module” on page 60.

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 Webportal manager or the pdadmin utility.

v The module should be a supplement, not a replacement, to the five standardpdadmin policy parameters.Refer to the IBM Tivoli Access Manager WebSEAL Administration Guide forinformation on the pdadmin policy commands.

v The password strength module is checked before the pdadmin policyparameters.

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


Building the custom Password Strength ModuleThe following module files are located in the pwdstr_adk directory:

File Name Description

pwdstrauthn.o The object file for the password strength module.

pwdstrg.c The source file that implements the functionpassword_strength().This is compiled and linked into the shared librarypwdstrauthn.

Makefile.allplat.in The template for the Makefile used to build thepwdstrauthn shared library.

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 ofthis file.

3. Build the pwdstrauthn shared library:

Solaris libpwdstrauthn.so

AIX libpwdstrauthn.a

HP-UX libpwdstrauthn.sl

Windows pwdstrauthn.dll

4. Stop the webseald server (WebSEAL).5. Place the pwdstrauthn shared library where it can be loaded.

UNIX: /usr/libWindows: anywhere in the path

6. Edit the [authentication-mechanisms] stanza of the webseald.confconfiguration 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 user’s password using the pkmspasswd utility, the

password_strength() function is called before any registry specific passwordchecks.


Appendix. Notices

This information was developed for products and services offered in the U.S.A.

IBM may not offer the products, services, or features discussed in this document inother countries. Consult your local IBM representative for information on theproducts and services currently available in your area. Any reference to an IBMproduct, program, or service is not intended to state or imply that only that IBMproduct, program, or service may be used. Any functionally equivalent product,program, or service that does not infringe any IBM intellectual property right maybe used instead. However, it is the user’s responsibility to evaluate and verify theoperation of any non-IBM product, program, or service.

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

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

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

IBM World Trade Asia CorporationLicensing2-31 Roppongi 3-chomeMinato-kuTokyo 106Japan

The following paragraph does not apply to the United Kingdom or any othercountry where such provisions are inconsistent with local law: INTERNATIONALBUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION ″AS IS″WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED,INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OFNON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULARPURPOSE. Some states do not allow disclaimer of express or implied warranties incertain 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 beincorporated in new editions of the publication. IBM may make improvementsand/or changes in the product(s) and/or the program(s) described in thispublication at any time without notice.

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


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

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

IBM Corporation2Z4A/10111400 Burnet RoadAustin, TX 78758USA

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

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

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

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

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

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

COPYRIGHT LICENSE:

This information contains sample application programs in source language, whichillustrates programming techniques on various operating platforms. You may copy,modify, and distribute these sample programs in any form without payment toIBM, for the purposes of developing, using, marketing or distributing applicationprograms conforming to the application programming interface for the operatingplatform for which the sample programs are written. These examples have notbeen thoroughly tested under all conditions. IBM, therefore, cannot guarantee orimply reliability, serviceability, or function of these programs. You may copy,


modify, and distribute these sample programs in any form without payment toIBM for the purposes of developing, using, marketing, or distributing applicationprograms conforming to IBM’s application programming interfaces.

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

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

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

AIXDB2IBMIBM logoSecureWayTivoliTivoli logoWebSphere

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

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

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

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

Appendix. Notices 63

Index

Aauthentication data, valid 11authentication methods 4

Bbusiness entitlements 4

CCDAS API

authentication methods 4build custom library 16components 9example shared library 18overview 3programming 10returning the client identity 15software requirements 10specifying extended attributes 15understanding functions 21valid authentication data 11

CDAS custom libraryconfigure and install 17extended attributes configuration 18

CDAS example library 18CDAS model

extended attributes chain model 6single authentication library 5

CDMF APIcomponents 40customizing shared library 42implementing custom library 41in a CDSSO environment 39in an e-community environment 40naming the custom library file 43overview 39providing extended user attributes 42providing identity mapping 42roles of duo libraries 41software requirements 41specifying extended attributes 43understanding functions and macros 45

cdmf_add_attr_to_list() 52cdmf_add_value_to_attr() 51cdmf_create_usr_attr_list() 49cdmf_create_usr_attr() 50cdmf_get_usr_attributes() 41, 42, 48cdmf_map_usr() 41, 42, 47cdmf_utils.h 40cdmf_utils.lib 40cdmf.c.examples 40cdmf.c.skeleton 40, 41cdmf.h 40cdsso 4cdsso_attrlist_t 43CDSSO_FREE() 55CDSSO_MALLOC() 54CDSSO_REALLOC() 56CDSSO_STRDUP() 53

cdsso_usr_info_t 43cdssotypes.h 40cert-cdas 4cert-ssl 4cred-ext-attrs 4, 5, 18credential

extended attributes 4

Eextended attributes 4, 18, 43

Hhttp-request 4

Llibcdmfutils 40libpdxauthn.a 9libpwdstrauthn 60

MMakefile.allplat.in 60Makefile.cdmf.in 40Makefile.in 16Makefile.win32 40

Ppasswd-cdas 4passwd-ldap 4password strength module

Makefile.allplat.in 60overview 59password_strength 60pwdstrauthn.o 60pwdstrg.c 60

pdadmin policy 59pdxauthn 16pdxauthn_adk 9pdxauthn.h 9pdxauthn.lib 9pkmspasswd 59pwdstrauthn.dll 60pwdstrauthn.o 60pwdstrg.c 60

RRequest-URI 11

Ttoken-cdas 4


Xxattr_get() 15, 27xattr_list_item_t 31xattr_list_t 15, 32xattr_set() 15, 28xattr.h 9xauthn_admin_cred 11xauthn_admin_name 11xauthn_authenticate() 11, 25xauthn_browser_info 11xauthn_cert 11xauthn_cert_dn 11xauthn_cert_issuer_dn 11xauthn_change_password() 11, 26xauthn_existing_cred 11xauthn_identity_t 11, 15, 33xauthn_initialize() 10, 23xauthn_ipaddr 11xauthn_new_password 11xauthn_password 11xauthn_qop 11xauthn_shutdown() 10, 24xauthn_su_method 11xauthn_token 11xauthn_username 11xauthn_util_entry_to_creds() 29xauthn.c 9xnvlist_get() 11, 30xnvlist_item_t 34xnvlist_t 11, 35xnvlist.h 9


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

GC23-4683-00

webseal developerâ€™s reference - ibm - united states

Documents