WebSEAL Developer s Reference

Transcription

1 IBM Tivoli Access Manager WebSEAL Developer s Reference Version 3.9 GC

2

3 IBM Tivoli Access Manager WebSEAL Developer s Reference Version 3.9 GC

4 Note Before using this information and the product it supports, read the information in Notices on page 61. Fifth Edition (April 2002) This edition replaces GC Copyright International Business Machines Corporation 1999, All rights reserved. US Government Users Restricted Rights Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.

5 Contents Preface v Who should read this reference v What this reference contains v Publications v IBM Tivoli Access Manager v Related publications viii Accessing publications online x Ordering publications x Providing feedback about publications x Accessibility xi Contacting customer support xi Conventions used in this book xi Typeface conventions xi Part 1. CDAS API Developer Reference Chapter 1. CDAS API overview Introducing the CDAS API Supported authentication methods Enabling dynamic business entitlements CDAS authentication models The single authentication CDAS model The credential extended attributes CDAS chaining model Chapter 2. Implementing a CDAS shared library CDAS API components Header files Software requirements for implementing a custom CDAS Programming the CDAS shared library Initialization: xauthn_initialize() Shutdown: xauthn_shutdown() Authentication: xauthn_authenticate() Password change: xauthn_change_password() Valid user authentication data Returning the client identity (xauthn_identity_t) Specifying extended attributes Building the custom shared library Writing a CDAS for switch user Chapter 3. Configuring WebSEAL to use a CDAS Configuring and installing the CDAS shared library Additional configuration for an extended attributes CDAS Using the example shared library Chapter 4. Authentication C API reference Summary: CDAS and utility API functions xauthn_initialize() xauthn_shutdown() xauthn_authenticate() xauthn_change_password() xattr_get() xattr_set() xauthn_util_entry_to_creds() xnvlist_get() Copyright IBM Corp. 1999, 2002 iii

6 xattr_list_item_t xattr_list_t xauthn_identity_t xnvlist_item_t xnvlist_t Part 2. CDMF API Developer Reference Chapter 5. Using a CDMF shared library Introducing the Cross-domain Mapping Framework Using CDMF in a CDSSO environment Using CDMF in an e-community environment CDMF API components Software requirements Implementing the CDMF shared library The CDMF library partnership Customizing the CDMF shared library Providing user attributes: cdmf_get_usr_attributes() Providing identity mapping: cdmf_map_usr() Naming the custom shared library Specifying extended attributes Chapter 6. CDMF C API reference Summary: CDMF API functions and macros cdmf_map_usr() cdmf_get_usr_attributes() cdmf_create_usr_attr_list() cdmf_create_usr_attr() cdmf_add_value_to_attr() cdmf_add_attr_to_list() CDSSO_STRDUP() CDSSO_MALLOC() CDSSO_FREE() CDSSO_REALLOC() Part 3. Password Strength Module Reference Chapter 7. Customizing password strength policy Password strength policy overview Introducing the Password Strength Policy Module Building the custom Password Strength Module Appendix. Notices Trademarks Index iv IBM Tivoli Access Manager: WebSEAL Developer s Reference

7 Preface Welcome to the IBM Tivoli Access Manager WebSEAL Developer s Reference. This document provides complete administration and programming information for the Cross-domain Authentication Service (CDAS), the Cross-domain Mapping Framework (CDMF), and the Password Strength Module. This developer s reference contains three sections: v Part 1 CDAS API Developer Reference v Part 2 CDMF API Developer Reference v Part 3 Password Strength Module Developer Reference Who should read this reference What this reference contains Publications This reference is for system administrators responsible for programming and application integration tasks in an Access Manager WebSEAL environment. Readers should be familiar with the following: v PC and UNIX operating systems v Database architecture and concepts v Security management v Internet protocols, including HTTP, TCP/IP, File Transfer Protocol (FTP), and Telnet v Lightweight Directory Access Protocol (LDAP) and directory services v A supported user registry v Authentication and authorization If you are enabling Secure Sockets Layer (SSL) communication, you also should be familiar with SSL protocol, key exchange (public and private), digital signatures, cryptographic algorithms, and certificate authorities. This 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) This section lists publications in the Access Manager library and any other related documents. It also describes how to access Tivoli publications online, how to order Tivoli publications, and how to make comments on Tivoli publications. IBM Tivoli Access Manager The Access Manager library is organized into the following categories: v v Release information Base information Copyright IBM Corp. 1999, 2002 v

8 v v v v WebSEAL information Web security information Developer reference information 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, open the 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, see the following Web sites: Release information v IBM Tivoli Access Manager for e-business Read Me First GI (am39_readme.pdf) Provides information for installing and getting started using Access Manager. v IBM Tivoli Access Manager for e-business Release Notes GI (am39_relnotes.pdf) Provides late-breaking information, such as software limitations, workarounds, and documentation updates. Base information v IBM Tivoli Access Manager Base Installation Guide GC (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 GC (am39_admin.pdf) Describes the concepts and procedures for using Access Manager services. Provides instructions for performing tasks from the Web portal manager interface and by using the pdadmin command. v IBM Tivoli Access Manager Base for Linux on zseries Installation Guide GC (am39_zinstall.pdf) Explains how to install and configure Access Manager Base for Linux on the zseries platform. WebSEAL information v IBM Tivoli Access Manager WebSEAL Installation Guide GC (amweb39_install.pdf) Provides installation, configuration, and removal instructions for the WebSEAL server and the WebSEAL application development kit. v IBM Tivoli Access Manager WebSEAL Administrator s Guide GC (amweb39_admin.pdf) Provides background material, administrative procedures, and technical reference information for using WebSEAL to manage the resources of your secure Web domain. v IBM Tivoli Access Manager WebSEAL Developer s Reference vi IBM Tivoli Access Manager: WebSEAL Developer s Reference

9 v GC (amweb39_devref.pdf) Provides administration and programming information for the Cross-domain Authentication Service (CDAS), the Cross-domain Mapping Framework (CDMF), and the Password Strength Module. IBM Tivoli Access Manager WebSEAL for Linux on zseries Installation Guide GC (amweb39_zinstall.pdf) Provides installation, configuration, and removal instructions for WebSEAL server and the WebSEAL application development kit for Linux on the zseries platform. Web security information v IBM Tivoli Access Manager for WebSphere Application Server User s Guide GC (amwas39_user.pdf) Provides installation, removal, and administration instructions for Access Manager for IBM WebSphere Application Server. v IBM Tivoli Access Manager for WebLogic Server User s Guide GC (amwls39_user.pdf) Provides installation, removal, and administration instructions for Access Manager for BEA WebLogic Server. v IBM Tivoli Access Manager Plug-in for Edge Server User s Guide GC (amedge39_user.pdf) Describes how to install, configure, and administer the plug-in for IBM WebSphere Edge Server. v IBM Tivoli Access Manager Plug-in for Web Servers User s Guide GC (amws39_user.pdf) Provides installation instructions, administration procedures, and technical reference information for securing your Web domain using the plug-in for Web servers application. Developer references v IBM Tivoli Access Manager Authorization C API Developer s Reference GC (am39_authc_devref.pdf) Provides reference material that describes how to use the Access Manager authorization C API and the Access Manager service plug-in interface to add Access Manager security to applications. v IBM Tivoli Access Manager Authorization Java Classes Developer s Reference GC (am39_authj_devref.pdf) Provides reference information for using the Java language implementation of the authorization API to enable an application to use Access Manager security. v IBM Tivoli Access Manager Administration C API Developer s Reference GC (am39_adminc_devref.pdf) Provides reference information about using the administration API to enable an application to perform Access Manager administration tasks. This document describes the C implementation of the administration API. v IBM Tivoli Access Manager Administration Java Classes Developer s Reference SC (am39_adminj_devref.pdf) Provides reference information for using the Java language implementation of the administration API to enable an application to perform Access Manager administration tasks. Preface vii

10 v IBM Tivoli Access Manager WebSEAL Developer s Reference GC (amweb39_devref.pdf) Provides administration and programming information for the Cross-domain Authentication Service (CDAS), the Cross-domain Mapping Framework (CDMF), and the Password Strength Module. Technical supplements v IBM Tivoli Access Manager Performance Tuning Guide GC (am39_perftune.pdf) Provides performance tuning information for an environment consisting of Access Manager with IBM SecureWay Directory defined as the user registry. v IBM Tivoli Access Manager Capacity Planning Guide GC (am39_capplan.pdf) Assists planners in determining the number of WebSEAL, LDAP, and backend Web servers needed to achieve a required workload. v IBM Tivoli Access Manager Error Message Reference SC (am39_error_ref.pdf) Provides explanations and recommended actions for the messages produced by Access Manager. The Tivoli Glossary includes definitions for many of the technical terms related to Tivoli software. The Tivoli Glossary is available, in English only, at the following Web site: Related publications This 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 at the following Web site: IBM Global Security Toolkit Access Manager provides data encryption through the use of IBM Global Security Toolkit (GSKit). GSKit is shipped on the IBM Tivoli Access Manager Base CD for your particular platform. The GSKit package installs the ikeyman key management utility (gsk5ikm), which enables you to create key databases, public-private key pairs, and certificate requests. The following document is available 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 to enable SSL communication in their Access Manager secure domain. IBM SecureWay Directory IBM SecureWay Directory, Version 3.2.2, is shipped on the IBM Tivoli Access Manager Base CD for your particular platform. If you plan to install the IBM viii IBM Tivoli Access Manager: WebSEAL Developer s Reference

11 SecureWay Directory server as your user registry, the following documents are available in the /doc/directory path on the IBM Tivoli Access Manager Base CD for 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 IBM SecureWay 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 documentation and 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 IBM SecureWay Directory documentation had been translated. This file is in English only. v IBM SecureWay Directory Server Readme (server.pdf) Provides a description of the IBM SecureWay Directory Server, Version v IBM SecureWay Directory Client Readme (client.pdf) Provides a description of the IBM SecureWay Directory Client SDK, Version This software development kit (SDK) provides LDAP application development support. v SSL Introduction and ikeyman User s Guide (gskikm5c.pdf) Provides information for network or system security administrators who plan to enable 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 to configure the slapd32.conf file. In IBM SecureWay Directory Version 3.2, the directory 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. Tuning considerations for directory sizes ranging from a few thousand entries to millions of entries are given where applicable. For more information about IBM SecureWay Directory, see the following Web site: IBM WebSphere Application Server IBM WebSphere Application Server, Advanced Single Server Edition, Version 4.0.2, is installed with the Web portal manager interface. For information about IBM WebSphere Application Server, see the following Web site: Preface ix

12 Accessing publications online Publications in the product libraries are included in Portable Document Format (PDF) on the product CD. To access these publications using a Web browser, open the 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 hardcopy publications, they are posted to the Tivoli Information Center. The Tivoli Information Center contains the most recent version of the publications in the product library in PDF or HTML format, or both. Translated documents are also available for some products. You can access the Tivoli Information Center and other sources of technical information from the following Web site: 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 to page check box in the Adobe Acrobat Print dialog (which is available when you click File Print) to ensure that the full dimensions of a letter-sized page are printed on the paper that you are using. Ordering publications You can order many Tivoli publications online at the following Web site: publications/cgibin/pbi.cgi You can also order by telephone by calling one of these numbers: v In the United States: v In Canada: v In other countries, for a list of telephone numbers, see the following Web site: Providing feedback about publications We are very interested in hearing about your experience with Tivoli products and documentation, and we welcome your suggestions for improvements. If you have comments or suggestions about our products and documentation, contact us in one of the following ways: v v Send an to pubs@tivoli.com. Complete our customer feedback survey at the following Web site: x IBM Tivoli Access Manager: WebSEAL Developer s Reference

13 Accessibility Contacting customer support Accessibility features help a user who has a physical disability, such as restricted mobility or limited vision, to use software products successfully. With this product, you can use assistive technologies to hear and navigate the interface. You can also use the keyboard instead of the mouse to operate all features of the graphical user interface. If you have a problem with any Tivoli product, you can contact Tivoli Customer Support. See the Tivoli Customer Support Handbook at the following Web site: The handbook provides information about how to contact Tivoli Customer Support, depending on the severity of your problem, and the following information: v Registration and eligibility v v Conventions used in this book Telephone numbers and addresses, depending on the country in which you are located What information to gather before contacting support This guide uses several conventions for special terms and actions, operating system-dependent commands and paths, and margin graphics. Typeface conventions The following typeface conventions are used in this book: Bold Italic Monospace Command names and options, keywords, and other information that you must use literally appear in bold. Variables, command options, and values you must provide appear in italics. Titles of publications and special words or phrases that are emphasized also appear in italics. Code examples, command lines, screen output, file and directory names, and system messages appear in monospace font. Preface xi

14 xii IBM Tivoli Access Manager: WebSEAL Developer s Reference

15 Part 1. CDAS API Developer Reference Chapter 1. CDAS API overview Introducing the CDAS API Supported authentication methods Enabling dynamic business entitlements CDAS authentication models The single authentication CDAS model The credential extended attributes CDAS chaining model Chapter 2. Implementing a CDAS shared library. 9 CDAS API components Header files Software requirements for implementing a custom CDAS Programming the CDAS shared library Initialization: xauthn_initialize() Shutdown: xauthn_shutdown() Authentication: xauthn_authenticate() Password change: xauthn_change_password().. 11 Valid user authentication data Returning the client identity (xauthn_identity_t).. 15 Specifying extended attributes Building the custom shared library Writing a CDAS for switch user Chapter 3. Configuring WebSEAL to use a CDAS 17 Configuring and installing the CDAS shared library 17 Additional configuration for an extended attributes CDAS Using the example shared library Chapter 4. Authentication C API reference Summary: CDAS and utility API functions xauthn_initialize() xauthn_shutdown() xauthn_authenticate() xauthn_change_password() xattr_get() xattr_set() xauthn_util_entry_to_creds() xnvlist_get() xattr_list_item_t xattr_list_t xauthn_identity_t xnvlist_item_t xnvlist_t Copyright IBM Corp. 1999,

16 2 IBM Tivoli Access Manager: WebSEAL Developer s Reference

17 Chapter 1. CDAS API overview Introducing the CDAS API The IBM Tivoli Access Manager Cross-domain Authentication Service (CDAS) is a shared library mechanism that allows you to substitute the default WebSEAL authentication mechanism with a custom process that ultimately returns an Access Manager identity to WebSEAL. In addition, a secondary ( chained ) CDAS can be called to supply extended attribute data (business entitlements) for inclusion in the user s credential. Topic Index: v Introducing the CDAS API on page 3 v CDAS authentication models on page 5 WebSEAL provides a set of default authentication mechanisms in the form of built-in shared libraries to support clients who access WebSEAL via username and password, client-side certificate, token passcode, IP address, or HTTP header. For authentication to succeed, these clients must be members of the Access Manager LDAP user registry. The Cross-domain Authentication Service (CDAS) allows you to substitute the default built-in WebSEAL authentication mechanism with a highly flexible shared library mechanism that allows custom handling and processing of extended attribute and client authentication information. The CDAS API provides you with the necessary resources to build your own custom CDAS shared library that can handle your extended attribute and authentication requirements. The CDAS can return an Access Manager identity to WebSEAL for authentication against the Access Manager user registry. You can customize the CDAS shared library to handle authentication data and extended attribute data according to your security requirements: v v v The custom CDAS can process authentication data internally and return an Access Manager identity. The custom CDAS can direct authentication data to be processed by an external authentication mechanism and third-party registry. An Access Manager identity is returned to WebSEAL. This method allows you to authenticate clients who are not direct members of the Access Manager secure domain. The custom CDAS can add extended attribute information (known as business entitlements) to the user s Access Manager credential. These business entitlements can be extracted from the credential directly using the authorization API or inserted in the HTTP headers of requests directed across a junction to a back-end application server. The basic steps for implementing a custom CDAS shared library include: 1. Identify the type of authentication method and data that you want to process 2. Build a custom shared library using the CDAS API Copyright IBM Corp. 1999,

18 3. Configure WebSEAL to use the custom shared library for the specified data Both standard built-in and custom shared libraries load directly into WebSEAL memory and run as part of the WebSEAL process. Supported authentication methods You use the [authentication-mechanisms] stanza of the webseald.conf configuration file to configure supported authentication data types and implementation mechanisms. Examples of authentication data types include digital certificates, username and password, and token passcode. Examples of implementation mechanisms include the standard shared libraries included with WebSEAL and custom-built shared libraries. In the webseald.conf configuration file, you represent the supported authentication data with an identifier parameter. You specify the implementation mechanism with the name of the shared library (standard or custom): <authentication-mechanism-parameter> = <shared-library> The following identifiers specify local built-in shared libraries: v passwd-ldap v cert-ssl v token-cdas v http-request v cdsso The following identifiers can be used to specify custom shared libraries for external CDAS servers: v passwd-cdas v cert-cdas v token-cdas v http-request v cred-ext-attrs (used for a chained extended attributes CDAS library) Note: Refer to Chapter 5 of the IBM Tivoli Access Manager WebSEAL Administration Guide for complete details regarding WebSEAL authentication. Enabling dynamic business entitlements Business enterprises and their partners often have the need to share common entitlements such as partner data (in a business-to-business relationship) or customer data (in a business-to-customer relationship). Through an extension of the Cross-domain Authentication Service (CDAS), Access Manager provides a flexible mechanism that allows you to place entiltlement information, in the form of extended attributes, into user credentials at the point of authentication. These business entitlements can be used in any situation where this data is required. For example, entitlement data can be extracted from the credential directly by an application using the authorization API or inserted in the HTTP headers of requests directed across a junction to a back-end application server. 4 IBM Tivoli Access Manager: WebSEAL Developer s Reference

19 CDAS authentication models There are two methods you can use to supply business entitlement data to a user credential: v v A single custom CDAS can be written to perform the authentication operation and, additionally, supply the extended attribute data. The authentication CDAS is specified by an authentication mechanism identifier parameter in the webseald.conf configuration file, as described in the previous section. For more details on configuring an authentication mechanism, refer to the IBM Tivoli Access Manager WebSEAL Administrator s Guide. A second custom CDAS can be written to supply extended attribute data. In this scenario, the authentication operation is performed by a built-in authentication mechanism or a custom CDAS. The second CDAS is then called to supply extended attribute data for inclusion in the user credential (CDAS chaining). This credential extended attributes CDAS is specified by the cred-ext-attrs identifier in the webseald.conf configuration file. See Additional configuration for an extended attributes CDAS on page 18 The custom CDAS shared library must be written by the application developer. In addition, you must configure WebSEAL to recognize the specific type of authentication data being passed to the CDAS mechanism. When WebSEAL receives a client request, it passes the appropriate authentication data to the custom shared library as a list of name/value pairs. For example, if the CDAS library is written to handle username and password authentication, the client authentication data must contain the user s name and the user s password. However, if the shared library is written to handle certificate authentication, 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 model The following diagram illustrates an example of the single authentication CDAS functionality. The individual numbered steps are described below the diagram: WebSEAL 5 User Registry Client authentication information 1 authn info 2 Resource Manager 4 identity External Registry Custom CDAS Shared Library 3 External Authentication Service Figure 1. Example CDAS authentication model 1. The client supplies authentication information to WebSEAL. 2. In this example, WebSEAL is configured to use a custom CDAS shared library to handle this type of authentication data. Chapter 1. CDAS API overview 5

20 The CDAS shared library could authenticate this user internally and pass the resulting Access Manager identity back to WebSEAL (Step 4). For example, the shared 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 external authentication service that performs its own authentication of the client, perhaps using a third-party (legacy) user registry. 4. The CDAS returns to WebSEAL either: a. A successful status code (indicating a successful authentication attempt) and 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 attribute data to WebSEAL (for inclusion in the user credential). 5. Creating the user credential: a. For a successful status code, WebSEAL tries to match the user identity with an entry in the Access Manager user registry (LDAP). If a match is found, WebSEAL treats the client as authenticated. Otherwise, it treats the client as unauthenticated. b. For an unsuccessful status code, WebSEAL automatically treats the client as unauthenticated. A successful authentication results in an Access Manager credential for the user. Any extended attribute data is included in the credential and can be extracted later for appropriate use. The credential allows the user to participate in the Access Manager secure domain. The credential extended attributes CDAS chaining model A second CDAS module can be chained to a built-in or custom CDAS authentication module. The initial authentication module (built-in or custom CDAS) is responsible for creating the Access Manager identity and can optionally (in the case of a custom CDAS) include extended attribute data. The second CDAS in the chain is used only to add extended attribute data. If Access Manager successfully authenticates the identity received from the CDAS chain, a credential is built for the user that includes the identity information and the extended attribute data. The following diagram illustrates an example of the CDAS chain functionality. The individual numbered steps are described below the diagram: 6 IBM Tivoli Access Manager: WebSEAL Developer s Reference

21 WebSEAL External Registry Authentication Module (built-in or CDAS libraries) authn info 4 identity External Authentication Service Client authentication information 5 identity and authn info Resource Manager 6 identity and attributes 7 User Registry build credential Extended Attributes CDAS Figure 2. Example extended attributes CDAS model 1. The client supplies authentication information to WebSEAL. 2. In this example, WebSEAL is configured to use a custom CDAS shared library to handle this type of authentication data. The CDAS shared library could authenticate this user internally and pass the resulting Access Manager identity back to the resource manager (Step 4). For example, the shared 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 external authentication 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) and an Access Manager user identity (plus attributes). b. An unsuccessful status code, indicating a failed authentication attempt. 7. Creating the user credential: a. For a successful status code, WebSEAL tries to match the user identity with an entry in the Access Manager user registry (LDAP). If a match is found, WebSEAL treats the client as authenticated. Otherwise, it treats the client as unauthenticated. b. For an unsuccessful status code, WebSEAL automatically treats the client as unauthenticated. A successful authentication results in an Access Manager credential for the user. The extended attribute data is included in the credential and can be extracted later for appropriate use. The credential allows the user to participate in the Access Manager secure domain. Chapter 1. CDAS API overview 7

22 8 IBM Tivoli Access Manager: WebSEAL Developer s Reference

23 Chapter 2. Implementing a CDAS shared library CDAS API components The specific operation of a customized authentication and mapping service are determined entirely by the CDAS developer. It is the responsibility of the developer to use the resources of the CDAS API to implement the authentication and data handling requirements of a particular application. Topic Index: v CDAS API components on page 9 v Programming the CDAS shared library on page 10 v Valid user authentication data on page 11 v Returning the client identity (xauthn_identity_t) on page 15 v Specifying extended attributes on page 15 v Building the custom shared library on page 16 v Writing a CDAS for switch user on page 16 The CDAS API can be found in the PDWebADK package (part of PDWeb) and consists of the following components: v API library (utility functions) v API header files v Example CDAS shared library file (for demonstration only) v Makefiles The CDAS API is located in a directory named pdxauthn_adk. The API components are contained in the following subdirectories: Directory include lib example Contents This directory contains the C header files. See Header files on page 9. This directory contains the CDAS authentication static library files: - UNIX systems: libpdxauthn.a - Windows systems: pdxauthn.lib The example directory contains: - Source file (xauthn.c) - Makefile - A pre-built platform-specific example shared library to demonstrate a functional CDAS. Header files The following header files are contained in the include directory. Files pdxauthn.h xnvlist.h Contents Definition of function prototypes, client identity, and error codes used for authentication API functions User authentication data structure utility functions Copyright IBM Corp. 1999,

24 Files xattr.h Contents User extended attributes data structure utility functions Software requirements for implementing a custom CDAS The CDAS API provides all the necessary resources for CDAS application development. The minimum installation consists of a single system with the following Access Manager 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 Manager components, please refer to the IBM Tivoli Access Manager Base Installation Guide and the IBM Tivoli Access Manager WebSEAL Installation Guide.) Programming the CDAS shared library A custom CDAS shared library must implement each of the following four CDAS API functions: v Initialization: xauthn_initialize() v Shutdown: xauthn_shutdown() v Authentication: xauthn_authenticate() v Password change: xauthn_change_password() Initialization: xauthn_initialize() WebSEAL loads the CDAS shared library and initializes it by calling xauthn_initialize(). This function contains the argc and argv parameters. These parameters contain the values specified in the shared library definition located in the webseald.conf configuration 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 be initialization parameters. Unlike the C language argv, the argv[0] array entry is the first parameter. For more information, see the reference page for xauthn_initialize(). Shutdown: xauthn_shutdown() During shutdown, WebSEAL calls the xauthn_shutdown() interface to stop the CDAS shared library process. Note: The shutdown interface is not functional in Access Manager 3.9. It exists for future development and implementation. 10 IBM Tivoli Access Manager: WebSEAL Developer s Reference

25 The xauthn_shutdown() interface is called with the same argc and argv parameters that were passed to the xauthn_initialize() interface when the shared library was first 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 to the shared library through the xauthn_authenticate() interface. User authentication information is passed to this interface in a name/value data list (xnvlist_t). The content of the name/value data list can vary and is specific to the configured authentication method. Valid user authentication data on page 11 lists the possible client authentication data handled by the shared library. The xauthn_authenticate() interface performs the application-specific authentication process based on the authentication information found in the data list, and returns the resulting client identity (xauthn_identity_t) to WebSEAL. It is important to note that the client identity returned through this interface can contain additional user information. For more information, see the reference page for xauthn_authenticate(). Password change: xauthn_change_password() This interface allows the user to make changes to the account password that is stored in the third-party user registry. Only the username and password authentication method supports this function. If the external authentication mechanism you are going to implement does not support password changes, this function should return: XAUTHN_S_UNSUPPORTED_AUTHN_METHOD User authentication information is passed to this interface in a name/value data list (xnvlist_t). The data list contains the user s name, the old password, and the new password. Valid user authentication data on page 11 lists the possible parameters passed to this function. Valid user authentication data For more information, see the reference page for xauthn_change_password(). WebSEAL can pass a variety of client authentication information to the shared library. The information is passed using a name/value list format, where the name is an identifier that specifies the value type. The information is stored in the xnvlist_t data type. Values can be accessed by using the utility function xnvlist_get(). For more information on retrieving values from xnvlist_t, see the reference page for xnvlist_get(). The following table lists the possible names and values for each authentication method: Chapter 2. Implementing a CDAS shared library 11

26 Authentication Method Name Value Username/Password xauthn_username xauthn_password xauthn_ipaddr xauthn_qop xauthn_browser_info xauthn_new_password (only for xauthn_change_password interface) xauthn_existing_cred - User name - User password - User IP address - Quality of protection - Browser information - User new password - During reauthentication, the user s existing credential as a string. X.509 Certificate xauthn_cert Token IP Address HTTP Header xauthn_cert_dn xauthn_cert_issuer_dn xauthn_ipaddr xauthn_qop xauthn_browser_info xauthn_existing_cred xauthn_username xauthn_token xauthn_ipaddr xauthn_qop xauthn_browser_info xauthn_existing_cred xauthn_ipaddr xauthn_qop xauthn_browser_info xauthn_existing_cred Request-URI xauthn_ipaddr xauthn_qop xauthn_browser_info <header-name> xauthn_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 credential as a string. - User name - User token (passcode) - User IP address - Quality of protection - Browser information - During reauthentication, the user s existing credential as a string. - User s IP Address - Quality of protection - Browser information - During reauthentication, the user s existing credential as a string. - The request URI. - User s IP Address - Quality of protection - Browser information - HTTP header name - During reauthentication, the user s existing credential as a string. 12 IBM Tivoli Access Manager: WebSEAL Developer s Reference

27 Authentication Method Name Value Switch User - Password xauthn_su_method xauthn_admin_name Switch User - Token Card Switch User - Certificate xauthn_admin_cred xauthn_existing_cred xauthn_username xauthn_ipaddr xauthn_qop xauthn_browser_info xauthn_su_method xauthn_admin_name xauthn_admin_cred xauthn_existing_cred xauthn_username xauthn_ipaddr xauthn_qop xauthn_browser_info xauthn_su_method xauthn_admin_name xauthn_admin_cred xauthn_existing_cred xauthn_username xauthn_ipaddr xauthn_qop xauthn_browser_info - su-password - The user name of the administrator attempting to switch user - The credential of the administrator attempting to switch user, as a string - During reauthentication, the credential of the switched-to user, as a string - The user name of the switched-to user - Administrator IP address - Administrator quality of protection - Administrator browser information - su-token-card - The user name of the administrator attempting to switch user - The credential of the administrator attempting to switch user, as a string - During reauthentication, the credential of the switched-to user, as a string - The user name of the switched-to user - Administrator IP address - Administrator quality of protection - Administrator browser information - su-certificate - The user name of the administrator attempting to switch user - The credential of the administrator attempting to switch user, as a string - During reauthentication, the credential of the switched-to user, as a string - The user name of the switched-to user - Administrator IP address - Administrator quality of protection - Administrator browser information Chapter 2. Implementing a CDAS shared library 13

28 Authentication Method Name Value Switch User - HTTP Request Switch User - CDSSO xauthn_su_method xauthn_admin_name xauthn_admin_cred xauthn_existing_cred xauthn_username xauthn_ipaddr xauthn_qop xauthn_browser_info xauthn_su_method xauthn_admin_name xauthn_admin_cred xauthn_existing_cred xauthn_username xauthn_ipaddr xauthn_qop xauthn_browser_info - su-http-request - The user name of the administrator attempting to switch user - The credential of the administrator attempting to switch user, as a string - During reauthentication, the credential of the switched-to user, as a string - The user name of the switched-to user - Administrator IP address - Administrator quality of protection - Administrator browser information - su-cdsso - The user name of the administrator attempting to switch user - The credential of the administrator attempting to switch user, as a string - During reauthentication, the credential of the switched-to user, as a string - The user name of the switched-to user - Administrator IP address - Administrator quality of protection - Administrator browser information 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 name specified 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_t entries: The xauthn_admin_cred and xauthn_existing_cred entries in the xnvlist_t authentication data structure contain encoded Access Manager credentials. Use the xauthn_util_entry_to_creds() function to access the credential. An example of how to use the function is included in the sample xauthn source code included in the PDWebADK package. 14 IBM Tivoli Access Manager: WebSEAL Developer s Reference

29 Returning the client identity (xauthn_identity_t) The CDAS shared library is required to return the resulting client identity back to WebSEAL. The client identity is defined by the xauthn_identity_t data structure. See the reference page for xauthn_identity_t. Specifying extended attributes The Access Manager CDAS allows you to add extended attribute data (business entitlements) to a user credential. These business entitlements can be used in any situation where this type of data is required. For example, entitlement data can be extracted from the credential directly by an application using the Authorization API or inserted in the HTTP headers of requests directed across a junction to a back-end application server. The structure of the returned client identity (xauthn_identity_t) allows you to specify extended attribute information. This additional information becomes part of the resulting Access Manager credential. You define extended attribute information with the xattr_list_t data structure. Extended attributes must be added to the credential at the time of authentication. The extended attribute list can only be used to pass string values. Binary data cannot be used. Each name/value pair must be added to the identity via a call to the xattr_set() function and can be retrieved using the xattr_get() function. In order for WebSEAL to recognize the extended attribute as tag/value data, the tag name is prefixed with the macro XAUTHN_TAG_VALUE_PREFIX, which is defined as tagvalue_. The following section of the xauthn.c demo program illustrates this action: char *tag = (char *) malloc(1024); 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/value data (business entitlements) in a custom CDAS: xattr_set(&ident->xattrs, strdup( tagvalue_ldap-emplpoyee-number ) strdup( ) ); xattr_set(&ident->xattrs, strdup( tagvalue_ldap-employee-phone ) strdup( ) ); Chapter 2. Implementing a CDAS shared library 15

30 Building the custom shared library When compiling the shared library, make sure you add the include directory of the ADK to the compiler command line. When linking the library, make sure you include the appropriate pdxauthn library (see CDAS API components on page 9). The ADK has provided a generic Makefile template named Makefile.in under the example directory. You can use the Makefile to compile the required library with minimum changes. Details on how to use the Makefile.in template are included inside the template itself. Writing a CDAS for switch user An existing CDAS authentication mechanism often returns additional information about the user that is incorporated into the user s credential. If you are using the switch user feature in such an environment, you must write a special switch user CDAS that emulates the behavior of your existing CDAS while supporting the requirement of returning a credential without requiring the user password for input. The Access Manager CDAS API provides a set of identity components that can be used to pass client authentication information to the shared switch user CDAS library. This information is passed using a name/value list format, where the name is an identifier that specifies the value type. The information is stored in the xnlist_t data type. Values can be accessed by using the utility function xnvlist_get(). Identity components appropriate for a switch user CDAS include: xauthn_su_method xauthn_admin_name xauthn_admin_cred xauthn_existing_cred xauthn_username xauthn_qop xauthn_ipaddr xauthn_browser_info The xauthn_browser_info, xauthn_qop, and xauthn_ipaddr identity components represent those of the administrator, not the switched to user. This data is supplied for any CDAS that must perform additional validations of the administrator s account. Refer to Valid user authentication data on page IBM Tivoli Access Manager: WebSEAL Developer s Reference