IBM SecurityAccess Manager Version 7

IBM Security Access ManagerVersion 7.0

Web Security Developer Reference

SC23-6517-02

��

IBM Security Access ManagerVersion 7.0

Web Security Developer Reference

SC23-6517-02

��

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

Edition notice

Note: This edition applies to version 7, release 0, modification 0 of IBM Security Access Manager (productnumber 5724-C87) and to all subsequent releases and modifications until otherwise indicated in new editions.

© Copyright IBM Corporation 2002, 2012.US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contractwith IBM Corp.

Contents

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

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

About this publication . . . . . . . . ixIntended audience . . . . . . . . . . . . ixAccess to publications and terminology . . . . . ix

Related publications . . . . . . . . . . xiiAccessibility . . . . . . . . . . . . . . xiiiTechnical training . . . . . . . . . . . . xivSupport information . . . . . . . . . . . xiv

Chapter 1. External authentication C APIconcepts . . . . . . . . . . . . . . 1Application development kit (ADK) overview . . . 1Authentication terminology . . . . . . . . . 2Authentication interfaces . . . . . . . . . . 3

Web security resource manager . . . . . . . 3Security Access Manager runtime . . . . . . 3Security Access Manager authorization API . . . 4External authentication C API . . . . . . . 4External authentication C API modules . . . . 4

Process flows for authentication operations . . . . 5Authentication process flow . . . . . . . . 5Change password process flow . . . . . . . 6Password strength process flow . . . . . . . 6Post password change process flow. . . . . . 7Extended attributes process flow. . . . . . . 8

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

Chapter 3. Authentication modulecustomization. . . . . . . . . . . . 13Task summary for custom module implementation 13External authentication C API requirements . . . 14

External authentication C API softwarerequirements . . . . . . . . . . . . . 14External authentication C API build instructions 14External authentication C API example library. . 14

Configuring WebSEAL to use a customauthentication module . . . . . . . . . . . 15UTF-8 compatibility . . . . . . . . . . . 18

UTF-8 compatibility for custom authenticationmodules . . . . . . . . . . . . . . 18User credential data format . . . . . . . . 18Entitlements service data format . . . . . . 19Conversion library for authentication data . . . 19Configuring the conversion library . . . . . 19

External authentication C API functions . . . . . 20

External authentication C API and utility APIfunctions . . . . . . . . . . . . . . 20Initializing the external authentication C API . . 21

External authentication C API data structures . . . 22Extended attribute information . . . . . . . 22User identity information. . . . . . . . . 22Authentication data . . . . . . . . . . 23

Chapter 4. Writing customauthentication modules . . . . . . . 25Customizing the authentication process . . . . . 25

Obtaining user authentication information . . . 25Authenticating the user . . . . . . . . . 26Returning the user identity . . . . . . . . 26Returning the authentication status . . . . . 26

Customizing user password change . . . . . . 27Customizing password strength checking . . . . 27Processing post password changes. . . . . . . 28Adding extended attributes to the credential . . . 29Modifying the user name in a credential. . . . . 31

Chapter 5. Single sign-oncustomization. . . . . . . . . . . . 33WebSEAL single sign-on concepts . . . . . . . 33

Default token creation for cross-domain singlesign-on . . . . . . . . . . . . . . . 33Default token creation for e-community singlesign-on . . . . . . . . . . . . . . . 34Default token consumption for cross-domainsingle sign-on . . . . . . . . . . . . 34Default token consumption for e-communitysingle sign-on . . . . . . . . . . . . 35

Customizing token create and consume modules . . 35Built-in token create and consume modules. . . 35Example token create and consume modules . . 36The token create module interface . . . . . . 36The token consume module interface . . . . . 37

Customizing identity mapping and attributehandling . . . . . . . . . . . . . . . 38

Cross-domain mapping framework overview . . 38Software requirements for the cross-domainmapping framework API . . . . . . . . . 39Build instructions for the cross-domain mappingframework API . . . . . . . . . . . . 39Customizing the example source file . . . . . 39Providing user attributes:cdmf_get_usr_attributes() . . . . . . . . . 40Providing identity mapping: cdmf_map_usr() . . 40Specifying extended attributes . . . . . . . 41

Example: Cross-domain single sign-on with anon-WebSEAL server . . . . . . . . . . . 41

Sending cross-domain single sign-on requests toa non-WebSEAL server . . . . . . . . . 42Accepting cross-domain single sign-on requestsfrom a non-WebSEAL server. . . . . . . . 43

© Copyright IBM Corp. 2002, 2012 iii

Appendix A. External authentication CAPI reference . . . . . . . . . . . . 45xattr_get() . . . . . . . . . . . . . . . 45xattr_list_item_t . . . . . . . . . . . . . 46xattr_list_t . . . . . . . . . . . . . . . 46xattr_set() . . . . . . . . . . . . . . . 47xauthn_utils_append_extcred_tags() . . . . . . 47xauthn_authenticate() . . . . . . . . . . . 48xauthn_change_password() . . . . . . . . . 49xauthn_identity_t . . . . . . . . . . . . 50xauthn_initialize() . . . . . . . . . . . . 51xauthn_shutdown() . . . . . . . . . . . . 51xauthn_util_entry_to_creds(). . . . . . . . . 52xnvlist_get() . . . . . . . . . . . . . . 53xnvlist_item_t . . . . . . . . . . . . . 54xnvlist_t . . . . . . . . . . . . . . . 54

Appendix B. Cross-domain mappingframework C API reference . . . . . . 55cdmf_add_attr_to_list() . . . . . . . . . . 55cdmf_add_value_to_attr(). . . . . . . . . . 56cdmf_create_usr_attr() . . . . . . . . . . . 56cdmf_create_usr_attr_list() . . . . . . . . . 57cdmf_get_usr_attributes() . . . . . . . . . . 57cdmf_map_usr() . . . . . . . . . . . . . 58

CDSSO_FREE() . . . . . . . . . . . . . 59CDSSO_MALLOC() . . . . . . . . . . . 60CDSSO_REALLOC() . . . . . . . . . . . 60CDSSO_STRDUP() . . . . . . . . . . . . 61

Appendix C. Authentication identifiersreference. . . . . . . . . . . . . . 63Identifiers common to all authentication methods . 63User name and password authentication identifiers 64Certificate authentication identifiers . . . . . . 65Token card authentication identifiers . . . . . . 66HTTP authentication identifiers. . . . . . . . 66Failover authentication identifiers . . . . . . . 67EAI identifiers . . . . . . . . . . . . . 68Token create identifiers . . . . . . . . . . 68Token consume identifiers . . . . . . . . . 69Switch user authentication identifiers . . . . . . 69

Appendix D. External authenticationinterface . . . . . . . . . . . . . . 71

Notices . . . . . . . . . . . . . . 73

Index . . . . . . . . . . . . . . . 77

iv IBM Security Access Manager Version 7.0: Web Security Developer Reference

Figures

1. Security Access Manager Web securityauthentication interfaces. . . . . . . . . 3

© Copyright IBM Corp. 2002, 2012 v

vi IBM Security Access Manager Version 7.0: Web Security Developer Reference

Tables

1. External authentication C API components 92. Cross-domain mapping framework API

components . . . . . . . . . . . . 103. EPAC demonstration application files . . . . 114. EPAC demonstration application credential

attributes . . . . . . . . . . . . . 125. Stanza entries for authentication mechanisms 166. Conversion shared library file names . . . . 207. External authentication C API functions 208. External authentication utility API functions 219. File names for pdxauthn libraries . . . . . 21

10. Members of the extended attribute item datastructure . . . . . . . . . . . . . 22

11. Members of the extended attribute list datastructure . . . . . . . . . . . . . 22

12. Members of the user identity data structure 2313. Members of the data structure for

authentication data . . . . . . . . . . 2314. Members of the data structure for a list of

authentication data items . . . . . . . . 23

15. Authentication status mapping . . . . . . 2616. Built-in token creation and consumption

modules . . . . . . . . . . . . . 3617. Example single sign-on module . . . . . . 3618. Cross-domain mapping framework module

name. . . . . . . . . . . . . . . 4019. Identifiers common to all authentication

methods . . . . . . . . . . . . . 6320. Identifiers used for user name and password

authentication. . . . . . . . . . . . 6521. Identifiers used for certificate authentication 6522. Identifiers used for token card authentication 6623. Identifiers used for HTTP header

authentication. . . . . . . . . . . . 6624. Identifiers used for failover authentication 6725. Identifiers used for EAI authentication . . . 6826. Identifiers used for token creation . . . . . 6827. Identifiers used for token consumption 6928. Identifiers used for switch user authentication 70

© Copyright IBM Corp. 2002, 2012 vii

viii IBM Security Access Manager Version 7.0: Web Security Developer Reference

About this publication

Welcome to the IBM Security Access Manager for Web Web Security DeveloperReference.

IBM Security Access Manager for Web, formerly called IBM Tivoli Access Managerfor e-business, is a user authentication, authorization, and web single sign-onsolution for enforcing security policies over a wide range of web and applicationresources.

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

Intended audienceThis guide is for system administrators responsible for the installation,deployment, and administration of Security Access Manager.

Readers must be familiar with:v Microsoft® Windows® and UNIX® operating systemsv Security managementv Internet protocols, including HTTP, HTTPS, and TCP/IPv Lightweight Directory Access Protocol (LDAP) and directory servicesv Authentication and authorizationv Access Manager security model and its capabilities

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

Access to publications and terminologyThis section provides:v A list of publications in the “IBM Security Access Manager for Web library.”v Links to “Online publications” on page xi.v A link to the “IBM Terminology website” on page xii.

IBM Security Access Manager for Web library

The following documents are in the IBM Security Access Manager for Web library:v IBM Security Access Manager for Web Quick Start Guide, GI11-9333-01

Provides steps that summarize major installation and configuration tasks.v IBM Security Web Gateway Appliance Quick Start Guide – Hardware Offering

© Copyright IBM Corp. 2002, 2012 ix

Guides users through the process of connecting and completing the initialconfiguration of the WebSEAL Hardware Appliance, SC22-5434-00

v IBM Security Web Gateway Appliance Quick Start Guide – Virtual OfferingGuides users through the process of connecting and completing the initialconfiguration of the WebSEAL Virtual Appliance.

v IBM Security Access Manager for Web Installation Guide, GC23-6502-02Explains how to install and configure Security Access Manager.

v IBM Security Access Manager for Web Upgrade Guide, SC23-6503-02Provides information for users to upgrade from version 6.0, or 6.1.x to version7.0.

v IBM Security Access Manager for Web Administration Guide, SC23-6504-02Describes the concepts and procedures for using Security Access Manager.Provides instructions for performing tasks from the Web Portal Managerinterface and by using the pdadmin utility.

v IBM Security Access Manager for Web WebSEAL Administration Guide, SC23-6505-02Provides background material, administrative procedures, and referenceinformation for using WebSEAL to manage the resources of your secure Webdomain.

v IBM Security Access Manager for Web Plug-in for Web Servers Administration Guide,SC23-6507-02Provides procedures and reference information for securing your Web domainby using a Web server plug-in.

v IBM Security Access Manager for Web Shared Session Management AdministrationGuide, SC23-6509-02Provides administrative considerations and operational instructions for thesession management server.

v IBM Security Access Manager for Web Shared Session Management Deployment Guide,SC22-5431-00Provides deployment considerations for the session management server.

v IBM Security Web Gateway Appliance Administration Guide, SC22-5432-00Provides administrative procedures and technical reference information for theWebSEAL Appliance.

v IBM Security Web Gateway Appliance Configuration Guide for Web Reverse Proxy,SC22-5433-00Provides configuration procedures and technical reference information for theWebSEAL Appliance.

v IBM Security Web Gateway Appliance Web Reverse Proxy Stanza Reference,SC27-4442-00Provides a complete stanza reference for the IBM® Security Web GatewayAppliance Web Reverse Proxy.

v IBM Security Access Manager for Web WebSEAL Configuration Stanza Reference,SC27-4443-00Provides a complete stanza reference for WebSEAL.

v IBM Global Security Kit: CapiCmd Users Guide, SC22-5459-00Provides instructions on creating key databases, public-private key pairs, andcertificate requests.

v IBM Security Access Manager for Web Auditing Guide, SC23-6511-02Provides information about configuring and managing audit events by using thenative Security Access Manager approach and the Common Auditing and

x IBM Security Access Manager Version 7.0: Web Security Developer Reference

Reporting Service. You can also find information about installing andconfiguring the Common Auditing and Reporting Service. Use this service forgenerating and viewing operational reports.

v IBM Security Access Manager for Web Command Reference, SC23-6512-02Provides reference information about the commands, utilities, and scripts thatare provided with Security Access Manager.

v IBM Security Access Manager for Web Administration C API Developer Reference,SC23-6513-02Provides reference information about using the C language implementation ofthe administration API to enable an application to perform Security AccessManager administration tasks.

v IBM Security Access Manager for Web Administration Java Classes DeveloperReference, SC23-6514-02Provides reference information about using the Java™ language implementationof the administration API to enable an application to perform Security AccessManager administration tasks.

v IBM Security Access Manager for Web Authorization C API Developer Reference,SC23-6515-02Provides reference information about using the C language implementation ofthe authorization API to enable an application to use Security Access Managersecurity.

v IBM Security Access Manager for Web Authorization Java Classes Developer Reference,SC23-6516-02Provides reference information about using the Java language implementation ofthe authorization API to enable an application to use Security Access Managersecurity.

v IBM Security Access Manager for Web Web Security Developer Reference,SC23-6517-02Provides programming and reference information for developing authenticationmodules.

v IBM Security Access Manager for Web Error Message Reference, GI11-8157-02Provides explanations and corrective actions for the messages and return code.

v IBM Security Access Manager for Web Troubleshooting Guide, GC27-2717-01Provides problem determination information.

v IBM Security Access Manager for Web Performance Tuning Guide, SC23-6518-02Provides performance tuning information for an environment that consists ofSecurity Access Manager with the IBM Tivoli Directory Server as the userregistry.

Online publications

IBM posts product publications when the product is released and when thepublications are updated at the following locations:

IBM Security Access Manager for Web Information CenterThe http://pic.dhe.ibm.com/infocenter/tivihelp/v2r1/topic/com.ibm.isam.doc_70/welcome.html site displays the information centerwelcome page for this product.

About this publication xi

http://pic.dhe.ibm.com/infocenter/tivihelp/v2r1/topic/com.ibm.isam.doc_70/welcome.html

http://pic.dhe.ibm.com/infocenter/tivihelp/v2r1/topic/com.ibm.isam.doc_70/welcome.html

IBM Publications CenterThe http://www-05.ibm.com/e-business/linkweb/publications/servlet/pbi.wss site offers customized search functions to help you find all the IBMpublications that you need.

IBM Terminology website

The IBM Terminology website consolidates terminology for product libraries in onelocation. You can access the Terminology website at http://www.ibm.com/software/globalization/terminology.

Related publicationsThis section lists the IBM products that are related to and included with theSecurity Access Manager solution.

Note: The following middleware products are not packaged with IBM SecurityWeb Gateway Appliance.

IBM Global Security Kit

Security Access Manager provides data encryption by using Global Security Kit(GSKit) version 8.0.x. GSKit is included on the IBM Security Access Manager for WebVersion 7.0 product image or DVD for your particular platform.

GSKit version 8 includes the command-line tool for key management,GSKCapiCmd (gsk8capicmd_64).

GSKit version 8 no longer includes the key management utility, iKeyman(gskikm.jar). iKeyman is packaged with IBM Java version 6 or later and is now apure Java application with no dependency on the native GSKit runtime. Do notmove or remove the bundled java/jre/lib/gskikm.jar library.

The IBM Developer Kit and Runtime Environment, Java Technology Edition, Version 6and 7, iKeyman User's Guide for version 8.0 is available on the Security AccessManager Information Center. You can also find this document directly at:

http://download.boulder.ibm.com/ibmdl/pub/software/dw/jdk/security/60/iKeyman.8.User.Guide.pdf

Note:

GSKit version 8 includes important changes made to the implementation ofTransport Layer Security required to remediate security issues.

The GSKit version 8 changes comply with the Internet Engineering Task Force(IETF) Request for Comments (RFC) requirements. However, it is not compatiblewith earlier versions of GSKit. Any component that communicates with SecurityAccess Manager that uses GSKit must be upgraded to use GSKit version 7.0.4.42,or 8.0.14.26 or later. Otherwise, communication problems might occur.

IBM Tivoli Directory Server

IBM Tivoli Directory Server version 6.3 FP17 (6.3.0.17-ISS-ITDS-FP0017) is includedon the IBM Security Access Manager for Web Version 7.0 product image or DVD foryour particular platform.

xii IBM Security Access Manager Version 7.0: Web Security Developer Reference

http://www-05.ibm.com/e-business/linkweb/publications/servlet/pbi.wss

http://www-05.ibm.com/e-business/linkweb/publications/servlet/pbi.wss

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

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



You can find more information about Tivoli Directory Server at:

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

IBM Tivoli Directory Integrator

IBM Tivoli Directory Integrator version 7.1.1 is included on the IBM Tivoli DirectoryIntegrator Identity Edition V 7.1.1 for Multiplatform product image or DVD for yourparticular platform.

You can find more information about IBM Tivoli Directory Integrator at:

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

IBM DB2 Universal Database™

IBM DB2 Universal Database Enterprise Server Edition, version 9.7 FP4 is providedon the IBM Security Access Manager for Web Version 7.0 product image or DVD foryour particular platform. You can install DB2® with the Tivoli Directory Serversoftware, or as a stand-alone product. DB2 is required when you use TivoliDirectory Server or z/OS® LDAP servers as the user registry for Security AccessManager. For z/OS LDAP servers, you must separately purchase DB2.

You can find more information about DB2 at:

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

IBM WebSphere® products

The installation packages for WebSphere Application Server Network Deployment,version 8.0, and WebSphere eXtreme Scale, version 8.5.0.1, are included withSecurity Access Manager version 7.0. WebSphere eXtreme Scale is required onlywhen you use the Session Management Server (SMS) component.

WebSphere Application Server enables the support of the following applications:v Web Portal Manager interface, which administers Security Access Manager.v Web Administration Tool, which administers Tivoli Directory Server.v Common Auditing and Reporting Service, which processes and reports on audit

events.v Session Management Server, which manages shared session in a Web security

server environment.v Attribute Retrieval Service.

You can find more information about WebSphere Application Server at:

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

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

About this publication xiii

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

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

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

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

Visit the IBM Accessibility Center for more information about IBM's commitmentto accessibility.

Technical trainingFor technical training information, see the following IBM Education website athttp://www.ibm.com/software/tivoli/education.

Support informationIBM Support provides assistance with code-related problems and routine, shortduration installation or usage questions. You can directly access the IBM SoftwareSupport site at http://www.ibm.com/software/support/probsub.html.

The IBM Security Access Manager for Web Troubleshooting Guide provides detailsabout:v What information to collect before you contact IBM Support.v The various methods for contacting IBM Support.v How to use IBM Support Assistant.v Instructions and problem-determination resources to isolate and fix the problem

yourself.

Note: The Community and Support tab on the product information center canprovide more support resources.

xiv IBM Security Access Manager Version 7.0: Web Security Developer Reference

http://www-03.ibm.com/able/

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

http://www.ibm.com/software/support/probsub.html

Chapter 1. External authentication C API concepts

You can customize and extend the functionality of the authentication modules builtinto WebSEAL.

The following topics provide an overview of the external authentication API:v “Application development kit (ADK) overview”v “Authentication terminology” on page 2v “Authentication interfaces” on page 3v “Process flows for authentication operations” on page 5

Application development kit (ADK) overviewThe Security Access Manager Web security application development kit (ADK)contains programming resources that allow you to customize and extend thefunctionality of the authentication modules built into WebSEAL.

The ADK provides programming interfaces that enable you to:v Add functionality to the built-in authentication modulesv Write replacement authentication modules

The ADK also provides an example program that demonstrates how to use theSecurity Access Manager authorization API to extract user credential attributes.This program is included because it is helpful in testing the results ofauthentication operations.

The Security Access Manager Web security application development kit can beused with either Security Access Manager WebSEAL or Security Access Managerplug in for Web Servers. Both components provide the server processing thathandles authentication requests. You can use the interfaces provided by theSecurity Access Manager Web security application development kit to writecustomized authentication modules for use by either of the Security AccessManager Web security components.

This developer reference uses the term Web security resource manager. The termresource manager is used by Security Access Manager to describe an application orprocess that handles requests from clients and then engages with the SecurityAccess Manager authorization service. The authorization service determineswhether a client must be allowed to perform the requested action on the requestedprotected resource. Security Access Manager WebSEAL and the Security AccessManager plug in for Web servers are both examples of a Web security resourcemanager.

The plug-in for Web servers runs in the same process as an external Web server,such as Microsoft IIS. In this developer reference, the term Web security resourcemanager can refer not only to the WebSEAL server, but also can refer to a serverprocess that includes the external Web server plus the security functions providedby the Security Access Manager plug in for Web servers.

For more information about the Security Access Manager Web securitycomponents, see:

© Copyright IBM Corp. 2002, 2012 1

v IBM Security Access Manager for Web: WebSEAL Administration Guide

v IBM Security Access Manager for Web: Plugin for Web Servers Administration Guide

The external authentication interface is an alternate method for customizing theauthentication process. Complete information about using the externalauthentication interface is located in the IBM Security Access Manager for Web:WebSEAL Administration Guide.

Authentication terminologyThis document provides terminology to describe authentication.v method

An authentication method describes the overall process and strategy of anauthentication type. Examples of authentication methods include, but are notlimited to:– Username/password– Token– CertificateTypically, but not always, authentication methods have a one-to-one relationshipwith a particular type of data used to prove a user identity.

v mechanism

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

v module

An authentication module describes where an authentication method isperformed and specifically refers to the shared library file (such aslibsslauthn.so) that performs the authentication and returns the client identity toWebSEAL, if successful.There is a one-to-one mapping between an authentication method and anauthentication module. For example, if a user provides authentication data usingthe password authentication method, the same module is used to bothauthenticate that user and to change the user password.The authentication modules are dynamic and are written as plug-ins. They canbe replaced with new versions, and when the Web security resource manager isrestarted, it uses the new authentication module to handle the operationsassociated with a particular authentication method. Both standard built-in andcustom authentication modules load directly into the Web security resourcemanager memory and run as part of the server process.

v operations

An authentication operation describes any action that supports theauthentication method. For example:– Performing an LDAP lookup during user name and password authentication.– Changing a user password.– Verifying that a new password meets certain criteria.– Adding attributes to an authenticated identity.A given authentication method can have more than one authentication operationassociated with it. For example, the token authentication method includes theoperations of authenticating, creating a new PIN number, and prompting a userto enter a new PIN. Some methods might not perform an actual authentication

2 IBM Security Access Manager Version 7.0: Web Security Developer Reference

at all. An example is the credential attribute entitlement service, whose solefunction is to add new attributes to an authenticated identity before a credentialis constructed.

Authentication interfacesSecurity Access Manager uses a flexible framework that allows the functions thathandle authentication operations to be easily modified or replaced.

This diagram shows the main components used in processing authenticationoperations.

The following sections describe the purpose of each components.

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

The resource manager:v Extracts authentication data from user requests and provides it to the Security

Access Manager runtime.v Receives the results of authentication operations from the runtime. The results

can be statuses or, in the case of actual authentication, user credentials thatrepresent authenticated accounts.

Security Access Manager runtimeThe Security Access Manager runtime is the set of libraries provided in theSecurity Access Manager runtime installation package.

These Security Access Manager libraries are separate from the authenticationmodules. They provide core Security Access Manager security managementfunctions for use by various resource managers, including some that are unrelatedto Web security. The Web security resource managers require these libraries as aprerequisite. The libraries are not customizable.

The Security Access Manager runtime libraries perform the following tasks:v Pass authentication data to the external authentication (xauthn) C API.v Receive statuses or, when authentication occurs, identity structures back from

the external authentication C API.

Client

Web SecurityResource Manager

Security AccessManager Runtime

xauthn interface

Authn

module

1

Authn

module

2

Authn

module

3

Security AccessManager

Authorization API

Figure 1. Security Access Manager Web security authentication interfaces

Chapter 1. External authentication C API concepts 3

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

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

v Determine if an identity was received from the external authentication C API. Ifyes, the runtime passes the identity to the Security Access Managerauthorization API to build a credential.

v Receive statuses, or credentials, or both back from the authorization API andpass them to the Web security resource manager.

Security Access Manager authorization APIThe authorization API is a Security Access Manager component.

It performs authorization tasks, including the following:v Receives an identity structure from the runtime.v Extracts the user name contained in the identity structure.v Attempts to find the user name in the Security Access Manager user registry.v When successful, constructs a user credential.v Returns the credential to the runtime.

External authentication C APIThe external authentication C API processes authentication data.

Note: In previous releases, custom authentication modules were built using theSecurity Access Manager cross-domain authentication services or CDAS. This term isno longer used because the scope of the term CDAS is no longer wide enough tocover all the functions performed by Web security resource manager authenticationmodules. The replacement term is external authentication C API. The new termreflects only a change in terminology.

The external authentication C API interface performs the following tasks:v Receives authentication data from the runtime.v Organizes the data into a standard format.v Passes the data to the authentication modules.v Receives statuses, identity structures, or both back from the authentication

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

External authentication C API modulesYou can use the external authentication C API to author custom authenticationmodules.

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

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


In summary, the four functions of the external authentication C API include:v xauthn_initialize()

Initializes a specified authentication module shared library.v xauthn_authenticate()

Performs the authentication module authentication tasks.v xauthn_change_password()

Performs a password change.v xauthn_shutdown()

Shuts down a specified authentication module shared library.

Process flows for authentication operationsThis section describes how authentication methods, and the authenticationoperations they contain, are implemented in the Web security resource managerauthentication framework.

The following authentication methods are supported:v Basic authenticationv Forms authenticationv Token authenticationv Certificate authenticationv HTTP header authenticationv IP address authenticationv Failover cookie authenticationv Switch-user authenticationv SPNEGO (Kerberos) authenticationv Cross-domain single sign-on (token)v e-community single sign-onv External authentication interface (EAI)

The process flow for authentication operations are described in the followingsections:v “Authentication process flow”v “Change password process flow” on page 6v “Password strength process flow” on page 6v “Post password change process flow” on page 7v “Extended attributes process flow” on page 8

Authentication process flowThe sequence of events in an authentication process flow can vary, depending onthe authentication module.

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

information.For example, the request includes a user name and password.2. The Web security resource manager extracts the authentication information

from the request.


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

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

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

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

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

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

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

Change password process flowA series of events can change the password process flow.

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

information. In this example, an old password and a new password.2. The Web security resource manager extracts the authentication information

from the request.3. The Web security resource manager passes the authentication information to

the runtime.4. The runtime passes the authentication information to the external

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

to an authentication module that implements the xauthn_change_password()function.

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

7. The external authentication C API returns the status to the runtime.8. The runtime returns the status to the Web security resource manager.9. The Web security resource manager then communicates either success or failure

to the user.

Password strength process flowThe password strength authentication module was implemented in previousversions of Security Access Manager with the password strength API. This API hasbeen deprecated. The password strength module now uses the externalauthentication C API.

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

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

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


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



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

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

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

8. The external authentication C API returns the status to the runtime.9. The runtime returns the status to the Web security resource manager.

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

Post password change process flowThis authentication module is chained. Rather than calling directly through theinterface from the Web security resource manager, it is always called (whenconfigured) after the completion of a change password operation performed byanother authentication module using the xauthn_change_password() function.


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




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

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

7. The external authentication C API returns the status to the runtime.8. The runtime recognizes that a post password change module has been

configured.9. The runtime then passes the authentication information to the post password

change module.10. The module performs some operation, such as synchronizing the password

with an external registry, and then returns a status to the externalauthentication C API.

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


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


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




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

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

7. The external authentication C API then passes the identity to the runtime.8. The runtime recognizes that an extended attribute module has been

configured and passes the identity structure back through the externalauthentication C API to the extended attributes authentication module.

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

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

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

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


Chapter 2. Application development kit components

The Web Security application development kit provides two authentication APIs, apassword strength module (deprecated), and a demonstration application.v “External authentication C API”v “Cross-domain mapping framework API” on page 10v “Password strength API (deprecated)” on page 11v “EPAC demonstration application” on page 11

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

The external authentication C API can be found in the Web Security ADK package(PDWebADK) and includes the following components:v External authentication C API header filesv External authentication C API libraryv Source filev Example pre-built authentication module (for demonstration only)v Makefiles for building custom libraries

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

The API components are contained in the following subdirectories:

Table 1. External authentication C API components

Directory Contents

include Contains C header files:

v pdxauthn.h

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

v xnvlist.h

User authentication data structure utility functions

v xattr.h

User extended attributes data structure utility functions

lib Contains the authentication module authentication static library files:

v UNIX or Linux systems: libpdxauthn.a

v Windows systems: pdxauthn.lib

example Contains:

v Source file (xauthn.c) for customization

v Makefile

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


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

The cross-domain mapping framework is used with Security Access Managercross-domain single sign-on solutions.

The cross-domain mapping framework API can be found in the Web Security ADKpackage (PDWebADK) and includes the following components:v Cross-domain mapping framework API libraryv Cross-domain mapping framework API header filev Demonstration cross-domain mapping framework filev Makefiles

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

Table 2. Cross-domain mapping framework API components

Files Description

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

cdmf.c.example Example cdmf.c file.

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

cdmf.h The header file for cdmf.c.

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

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

Windows only:

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

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

UNIX or Linux only:

libcdmfutils. (so, a, sl) The library for the utility functions defined incdmf_utils.h.

v .so for Solaris and Linux

v .a for AIX

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


Password strength API (deprecated)The interface used for the password strength module has changed for version 5.1and later of Security Access Manager.

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

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

EPAC demonstration applicationThe Web Security application development kit contains a CGI program that readsinformation that is stored in the form of an extended privilege attribute certificate(EPAC) and converts it to a Security Access Manager user credential.

The EPAC is obtained from the HTTP_IV_CREDS variable. In addition, theprogram displays the name and value for each credential attribute contained in theEPAC.

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

Table 3. EPAC demonstration application files

File Description

epac The demonstration program.

epac.c Source for the demonstration program.

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

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

The EPAC uses the Security Access Manager authorization API. To use theauthorization API, you must install the Security Access Manager authorizationADK package (PDAuthADK).

You can use the EPAC demonstration binary as distributed, or you can modify thesource to customize it for your deployment. The source uses a number ofauthorization API function calls. You can find more information about thesefunctions in the IBM Security Access Manager for Web: Authorization C API DeveloperReference.

The EPAC source contains a utility function for writing debug output to a log file,and a utility function for formatting the output of the credential attribute list intoan HTML table. You can use these functions as written, or edit them to modify theoutput format.

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

Chapter 2. Application development kit components 11

Table 4. EPAC demonstration application credential attributes

Attribute name Description

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

1

AZN_CRED_AUTH_METHOD The authentication method used. For example:

password

AZN_CRED_AUTHNMECH_INFO Information about the authentication mechanism.For example:

LDAP Registry

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

cn=joeuser,o=ibm,c=us

AZN_CRED_BROWSER_INFO Information identifying the type and version ofbrowser

AZN_CRED_GROUPS Group identifiers, in UUID format

AZN_CRED_GROUPS_NAMES Group names, in user registry format. Forexample:

cn=sales,o=ibm,c=us

AZN_CRED_IP_ADDRESS IP address (hex number)

AZN_CRED_LDAP_DN LDAP DN for the user (principal)

AZN_CRED_MECH_ID User registry mechanism ID. For example:

IV_LDAP_V3.0

AZN_CRED_PRINCIPAL_NAME User name

AZN_CRED_PRINCIPAL_UUID User identity, expressed as a Universal UniqueIdentifier

AZN_CRED_QOP_INFO Quality of protection setting

AZN_CRED_VERSION Credential version (indicates release of SecurityAccess Manager).

To use the EPAC demonstration, complete the following steps:1. Build the EPAC CGI executable.2. Configure the EPAC as an authorization API application.3. Deploy and run the EPAC executable.

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


Chapter 3. Authentication module customization

You can write a custom authentication module for any of the authenticationmechanisms supported by WebSEAL or the Plug-in for Web Servers.

The following topics describe customization tasks and requirements:v “Task summary for custom module implementation”v “External authentication C API requirements” on page 14v “Configuring WebSEAL to use a custom authentication module” on page 15v “UTF-8 compatibility” on page 18v “External authentication C API functions” on page 20v “External authentication C API data structures” on page 22

Task summary for custom module implementationTo implement a custom module, you must identify the type of authenticationmethod and data, build a custom library, and configure the Web security resourcemanager to use the custom library.

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

Instructions for developing authentication modules for each type ofauthentication operation are described in Chapter 3, “Authentication modulecustomization.”The cross-domain single sign-on and e-community single sign-on authenticationmodules require additional instructions, including the optional use of thecross-domain mapping framework API. This is described in Chapter 5, “Singlesign-on customization,” on page 33.

2. Build a custom library using the external authentication C API.For detailed instructions on writing a custom authentication library, seeChapter 4, “Writing custom authentication modules,” on page 25.For an overview of the external authentication C API and the cross-domainmapping framework, see Chapter 2, “Application development kitcomponents,” on page 9.Reference pages for each of the external authentication C API functions areprovided in Appendix A, “External authentication C API reference,” on page45.Reference pages for the cross-domain mapping framework are provided inAppendix B, “Cross-domain mapping framework C API reference,” on page 55.

3. Configure the Web security resource manager to use the custom library forthe specified data.You configure custom authentication modules into the secure Web server bymodifying entries in the secure Web server configuration file. This developerreference provides configuration instructions in Chapter 3, “Authenticationmodule customization” and Chapter 5, “Single sign-on customization,” on page33.When you are ready to configure a new authentication module for WebSEAL,you should also review the detailed authentication configuration information inthe IBM Security Access Manager for Web: WebSEAL Administration Guide.To review detailed configuration information for authentication modules used


by the plug-in for Web servers, see also the IBM Security Access Manager forWeb: Plug-in for Web Servers Administration Guide.

External authentication C API requirementsTo develop and test an authentication module, install the required Security AccessManager components. When you build an authentication module, you might adaptthe example library that implements a generic user name and passwordauthentication module.

This section contains the following topics:v “External authentication C API software requirements”v “External authentication C API build instructions”v “External authentication C API example library”

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

To develop and test an authentication module on a single machine, the followingSecurity Access Manager components must be installed:v Security Access Manager runtime (PDRTE)v Security Access Manager policy server (PDMgr)v Security Access Manager authorization ADK (PDAuthADK)v Security Access Manager WebSEAL (PDWeb) or the Security Access Manager

plug in for Web Serversv Security Access Manager Web Security ADK (PDWebADK)

For instructions regarding installation and configuration of Security AccessManager components, refer to the IBM Security Access Manager for Web: InstallationGuide.

External authentication C API build instructionsYou build an authentication module by using make to compile your source file.

The WebSEAL application development kit provides a sample MakefileMakefile.in under the example directory.

In many cases, you can use the Makefile with minimum changes. The Makefiletemplate is written to compile the example source file xauthn.c. See theMakefile.in template for more information.

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

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

External authentication C API example libraryThe Security Access Manager Web security ADK includes an example(demonstration) library that implements a generic user name and passwordauthentication module.


The sample library is an interactive program that displays all the available clientauthentication data and prompts for a user identity.

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

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

Then, using the sample library, run the Security Access Manager Web securityresource manager (WebSEAL or the plug-in for Web Servers) in the foreground. Forexample, on a Solaris system:WebSEAL# /opt/pdweb/bin/webseald -foreground

Plug-in for Web Servers# /opt/pdwebpi/bin/pdwebpi -foreground

The program user interface for client authentication data for the WebSEAL versionof the application appears as follows:===============================User Authentication Information:===============================xauthn_username:laura (4)xauthn_password:123456 (9)xauthn_ipaddr_ipv6::: (3)xauthn_ipaddr:9.0.0.119 (13)xauthn_qop:SSK: TLSV1: 35 (15)xauthn_browser_info:Mozilla/5.0 (X11; U; Linux i686; en-US; rv:1.7.6)Gecko/20050223 Firefox/1.0.1 (79)xauthn_existing_cred:0Please enter the registry ID number: 1Enter the user identity: laura===============================

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

The program user interface for adding external attribute data appears as follows:===============================User Authentication Information:===============================xauthn_username:laura (4)xauthn_password:123456 (9)xauthn_ipaddr_ipv6::: (3)xauthn_ipaddr:9.0.0.119 (13)xauthn_qop:SSK: TLSV1: 35 (15)xauthn_browser_info:Mozilla/5.0 (X11; U; Linux i686; en-US; rv:1.7.6)Gecko/20050223 Firefox/1.0.1 (79)xauthn_existing_cred:0Enter the test tag: emailEnter the test tag data: [email protected]===============================

Configuring WebSEAL to use a custom authentication moduleSecurity Access Manager supports many configuration options for authenticationmodules.

Chapter 3. Authentication module customization 15

About this task

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

Procedure1. Stop the Web security resource manager, such as WebSEAL.2. Open the configuration file for editing.3. Enter the appropriate authentication identifier parameter, with the full path

name of the library, in the [authentication-mechanisms] stanza.authentication_method_identifier = library_nameThe following stanzaentries specify authentication modules:

Table 5. Stanza entries for authentication mechanisms

Stanza Entries Description

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

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

passwd-uraf Specifies a library that implements basic authentication or formsauthentication using the Security Access Manager URAF interfaceto underlying user registry types.

token-cdas Specifies the library that implements token authentication.

cert-ldapSpecifies the library that implements certificate authentication forinternal Security Access Manager server communication.

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

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

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

sso-consume Specifies the library that implements WebSEAL single sign-on tokenconsumption.

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

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

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

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

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

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


Table 5. Stanza entries for authentication mechanisms (continued)

Stanza Entries Description

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

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

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

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

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

failover-certificate Specifies the library that implements failover cookie authenticationfor certificate authentication.

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

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

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

failover-ext-auth-interface

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

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

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

For example, if you want to externalize LDAP user name and passwordauthentication using a custom module named libxauthn.so (for a Solarissystem), enter the following line:[authentication-mechanisms] passwd-ldap =/opt/pdweb/lib/libxauthn.so

4. If the custom module accepts any arguments during initialization andshutdown, they can be specified in the following format (using thelibxauthn.so library as an example): passwd-ldap = /opt/pdweb/lib/libxauthn.so&arg1 arg2 .... argN

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

5. Ensure that each custom module has both read > execute operating system filepermissions for the ivmgr user.

6. Restart the Web Security resource manager process.


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

This section contains the following topics:v “UTF-8 compatibility for custom authentication modules”v “User credential data format”v “Entitlements service data format” on page 19v “Conversion library for authentication data” on page 19v “Configuring the conversion library” on page 19

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

UTF-8 compatibility for custom authentication modulesAs of version 5.1 and later, WebSEAL and plug-in for Web Servers have beenconverted to use UTF-8 encoded strings when handling data internally. The use ofUTF-8 encoding enables WebSEAL to support multiple languages at a time, knownas multi-locale support.

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

Pre-version 5.1 custom authentication modules have typically operated in singlelanguage environment because each WebSEAL process ran in a single-localeenvironment. These environments use a local code page that is not UTF-8 enabled.

Because Security Access Manager and WebSEAL processes now run in amulti-locale UTF-8 enabled environment, the format of data read into and writtenout of these processes has changed. For some custom authentication modules, thischange in data format might require code changes to the library. For all customauthentication modules, a configuration (deployment) change is required.

User credential data formatMany custom authentication modules access and modify user credentialinformation.

This information is obtained from Security Access Manager by using the SecurityAccess Manager authorization C API. For version 5.1 and later, the authorization CAPI is now initialized to use UTF-8 strings. This means that authorization modulesneed to be initialized to use UTF-8 as the code page of choice. Calls toauthorization API functionality need to use UTF-8 arguments, and all code that isinvoked by authorization modules must expect UTF-8 arguments.

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


Entitlements service data formatSome customized authentication modules also obtain data from customizedentitlements services.

The entitlements services must be called with UTF-8 arguments. Thus, entitlementsservices created to work with versions of Security Access Manager prior to version5.1 might need to be modified.

Conversion library for authentication dataTo maintain compatibility with customized authentication modules that expect datain non-UTF-8 format, WebSEAL provides a conversion shared library forauthentication.

This shared library automatically converts data that passes in and out ofauthentication modules. WebSEAL detects authentication modules that expect anon-UTF-8 local code page, and converts outgoing data to those modules into alocal code page format. Likewise, WebSEAL converts output from theauthentication modules into UTF-8 format before processing the data internally.

Conversion shared library limitations

The authentication conversion shared library does not support all authenticationmechanisms.

The following limitation can affect customized authentication moduleimplementations:v Switch user authentication module

Customized switch user authentication module modules must manipulate usercredential data. The user credential data is now in UTF-8 format, as described inthe earlier discussion regarding authorization API initialization changes.Customized switch user authentication modules must be modified to handlecredential data in UTF-8 format.

The following conversion shared library limitations do not affect customauthentication modules:v HTTP header authentication

WebSEAL does not interpret HTTP Header data, so there is no issue with codepage format.

v Cross-domain single sign-on, e-community single sign-on, and failoverauthenticationThese authentication methods rely on user data that is encoded in tokens. Thetokens can be encoded either using UTF-8 or not using UTF-8. This encoding isdetermined by settings in the WebSEAL or plug-in for Web Servers configurationfile. For more information, see the IBM Security Access Manager for Web:WebSEAL Administration Guide or the IBM Security Access Manager for Web:Plug-in for Web Servers Administration Guide.

v SSL does not supported this because of it being controlled by the GSKitcertificate handle.

Configuring the conversion libraryThe conversion library is called amwauthconv.

The actual library file name is platform-dependent:


Table 6. Conversion shared library file names

Operating system Shared library name

Solaris libamwauthnconv.so

AIX libamwauthnconv.a

Linux libamwauthnconv.so

Windows amwauthconv.dll

Custom authentication modules are invoked by entering a command-line argumentinto the configuration file. For example (WebSEAL):cert-ssl = /usr/lib/libcustomauth.so& argument1 argument2

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

For example, to use the sample library specified in the previous paragraph withthe conversion library, the entry in the WebSEAL configuration file is as follows:cert-ssl = /opt/pdwebrte/lib/libamwauthconv.so&/usr/lib/libcustomauth.so argument1 argument2

The preceding command is entered as a single continuous line.

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

External authentication C API functionsThis section describes the external authentication C API and utility API functions.It also describes the function with which WebSEAL loads and initializes theexternal authentication C API.

This section contains the following topics:v “External authentication C API and utility API functions”v “Initializing the external authentication C API” on page 21

External authentication C API and utility API functionsYou can use the external authentication C API and utility API functions.

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

Table 7. External authentication C API functions

Function Task

“xauthn_initialize()” on page 51 “Initializing the external authentication CAPI” on page 21

“xauthn_authenticate()” on page 48 v “Obtaining user authenticationinformation” on page 25

v “Authenticating the user” on page 26

v “Returning the user identity” on page 26


Table 7. External authentication C API functions (continued)

Function Task

“xauthn_change_password()” on page 49 v “Customizing user password change” onpage 27

v “Customizing password strengthchecking” on page 27

v “Processing post password changes” onpage 28

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

Table 8. External authentication utility API functions

Function Task

“xauthn_util_entry_to_creds()” on page 52 “Converting the credential to string format”on page 26

“xattr_get()” on page 45 “Adding extended attributes to thecredential” on page 29“xattr_set()” on page 47

“xnvlist_get()” on page 53 “Obtaining user authentication information”on page 25

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

Table 9. File names for pdxauthn libraries

Operating system Filename

UNIX libpdxauthn.a

Windows pdxauthn.lib

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

This function contains the argc and argv parameters. These parameters contain thevalues specified in the library definition located in the Web security resourcemanager (WebSEAL or Plug-in for Web Servers) configuration file. The librarydefinition uses the following syntax:authentication_mechanism = library_name[&arg1]...[ argN]

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

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

It is not necessary to shut down the external authentication C API. The APIprovides a shutdown function, xauthn_shutdown(). However, the shutdowninterface is not functional in past and current versions of Security Access Manager.You can successfully complete and use an authentication module implementationwithout it.


External authentication C API data structuresExtended attributes contain information about a user, including identity andauthentication data.

This section contains the following topics:v “Extended attribute information”v “User identity information”v “Authentication data” on page 23

Extended attribute informationExtended attributes contain information about a user.

This information consists of name/value pairs. A series of name/value pairs can beorganized into a list. This list is used by xauthn_authenticate() to pass extendedinformation about a user to the custom authentication module library.

The data structure that holds a single extended attribute is xattr_list_item_t.typedef struct {char *name;char *value;} xattr_list_item_t;

Table 10. Members of the extended attribute item data structure

Member Description

name A string representing the name of the extended attribute.

value A string representing the value of the extended attribute.

The data type xattr_list_t is a list of extended attributes to be added to thecredential.typedef struct {longlength;xattr_list_item_t *items;} xattr_list_t;

Table 11. Members of the extended attribute list data structure

Member Description

length The number of elements in the list.

items An array of xttr_list_item_t structures.

User identity informationThe xauthn_identity_t data structure holds information about the identity of aSecurity Access Manager user.typedef struct {struct {unsigned32 prin_type;union {/* case(s): 0 */char *name;/* case(s): 1 */char *dn;/* case(s): 2 */char *uraf_name;


} data;} prin;char*user_info;char*authnmech_info;xattr_list_t xattrs;} xauthn_identity_t;

Table 12. Members of the user identity data structure

Member Description

prin_type The prin_type indicates the user registry used to generate acredential from the identity.

The only valid value is XAUTHN_PRIN_TYPE_DN (LDAP user registry),where the prin.data.dn contains the distinguished name (DN) of theuser.

name Not valid.

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

uraf_name Not valid

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

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

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

Authentication dataThe xnvlist_item_t data structure holds a single item of authentication data.typedef struct {char *name;char *value;int vlen;} xnvlist_item_t;

Table 13. Members of the data structure for authentication data

Member Description

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

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

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

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

The xnvlist_t data structure holds a list of xnvlist_item_t authentication datastructures.typedef struct {longlength;xnvlist_item_t *items;} xnvlist_t;

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

Member Description

length The number of elements in the items array.


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

Member Description

items An array of xnvlist_item_t.


Chapter 4. Writing custom authentication modules

You can write a custom authentication module. For example, you might modifypassword and credential data.

The following topics describe tasks and requirements for writing customauthentication modules:v “Customizing the authentication process”v “Customizing user password change” on page 27v “Customizing password strength checking” on page 27v “Processing post password changes” on page 28v “Adding extended attributes to the credential” on page 29v “Modifying the user name in a credential” on page 31

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

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

This section describes how to complete the following steps:1. “Obtaining user authentication information”2. “Authenticating the user” on page 263. “Returning the user identity” on page 264. “Returning the authentication status” on page 26

Obtaining user authentication informationAfter you configure the authentication module library, the Security Access ManagerWeb security resource manager can pass the client request to the library throughthe xauthn_authenticate() interface.

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

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

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


Authenticating the userAuthenticate the user against the registry.

For example, authentication might grant additional access privileges to the user.

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

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

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

Returning the user identityThe authentication module library returns the resulting client identity back toWebSEAL or the plug-in for Web Servers.

The client identity is defined by the xauthn_identity_t data structure. Thisstructure is returned by xauthn_authenticate().

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

Returning the authentication statusThe authentication module library is required to return the authentication statusback to WebSEAL or the plug-in for Web Servers.

The authentication status is defined by the error_status_t data type. Thisstructure is returned by xauthn_authenticate().

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

Table 15. Authentication status mapping

Status returned from module Status returned to browser

XAUTHN_S_COMPLETE error_status_ok

XAUTHN_S_FAILURE ivauthn_authentication_failure

XAUTHN_S_OUT_OF_MEMORY ivauthn_out_of_memory

XAUTHN_S_BAD_AUTHENTICATION_INFO ivauthn_bad_authentication_info

XAUTHN_S_INVALID_USERNAME ivauthn_invalid_username

XAUTHN_S_RETRY_LIMIT_REACHED ivauthn_retry_limit_reached

XAUTHN_S_PASSWORD_EXPIRED ivauthn_password_expired

XAUTHN_S_ACCOUNT_EXPIRED ivauthn_account_expired


Table 15. Authentication status mapping (continued)

Status returned from module Status returned to browser

XAUTHN_S_LOGIN_POLICY_VIOLATION ivauthn_login_policy_violation

XAUTHN_S_NEW_PIN ivauthn_new_pin

XAUTHN_S_ACCOUNT_DISABLED ivauthn_account_disabled

XAUTHN_S_NEXT_TOKEN ivauthn_next_token

XAUTHN_S_MAPPING_FAILED ivauthn_mapping_failed

XAUTHN_S_CERTIFICATE_AUTH_FAILURE ivauthn_certificate_auth_failure

XAUTHN_S_HTTP_HEADER_AUTH_FAILURE ivauthn_http_header_auth_failure

XAUTHN_S_IP_ADDR_AUTH_FAILED ivauthn_ip_addr_auth_failed

XAUTHN_S_SU_INVALID_USERNAME ivauthn_su_invalid_username

XAUTHN_S_SU_NO_PERMS ivauthn_su_no_perms

XAUTHN_S_PASSWD_POLICY_VIOLATION ivauthn_passwd_policy_violation

XAUTHN_S_PASSWD_TOO_SHORT ivauthn_passwd_too_short

XAUTHN_S_PASSWD_HAS_SPACES ivauthn_passwd_has_spaces

XAUTHN_S_PASSWD_TOO_MANY_REPEATED ivauthn_passwd_too_many_repeated

XAUTHN_S_PASSWD_TOO_FEW_ALPHAS ivauthn_passwd_too_few_alphas

XAUTHN_S_PASSWD_TOO_FEW_NONALPHAS ivauthn_passwd_too_few_nonalphas

XAUTHN_S_PASSWD_ACCT_LOCKEDOUT ivauthn_passwd_acct_lockedout

XAUTHN_S_POST_PWDCHG_FAILED ivauthn_post_pwdchg_failed

All other statuses are mapped to ivauthn_unknown_error.

Customizing user password changeThe xauthn_change_password() function allows the user to change the accountpassword that is stored in the third-party user registry.

This step is optional.

The user name and password, and token authentication methods support thisfunction. If the custom authentication module that you are going to implementdoes not support password changes, this function must return:XAUTHN_S_UNSUPPORTED_AUTHN_METHOD

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

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

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

Customizing password strength checkingThe xauthn_change_password() function can be used to change a user password.

Chapter 4. Writing custom authentication modules 27

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

The password strength module is specified by the passwd-strength stanza entry inthe [authentication-mechanisms] stanza of the WebSEAL configuration file. Forexample:[authentication-mechanisms]passwd-strength = /opt/pdweb/example/libxauthn.so

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

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

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

The authentication information identifiers for each authentication method,including those specific to xauthn_change_password() are described in “Obtaininguser authentication information” on page 25.

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

Processing post password changesPost password change processing is supported by both WebSEAL and the plug-infor Web Servers.

This section refers to both of these components as the Security Access ManagerWeb security resource manager.

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

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

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


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

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

v xauthn_change_password()

The xauthn_change_password() function is called with an xnvlist_t structure as aninput parameter. The xnvlist_t contains the following data:v Name of the user who needs the password to be changedv Current password of the userv New password of the user

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

The post password change processing module returns status to the Web securityresource manager. The Web security resource manager audits the return status butdoes not act based on it. Any errors from the module are not returned to the client.The implementer of the authentication module must handle any error conditionsthat arise.

Adding extended attributes to the credentialThe xauthn_authenticate() function 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 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.

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

For more information about calling the built-in entitlements services, see the IBMSecurity Access Manager for Web: Authorization C API Developer Reference. Anexample usage of the credentials attribute entitlements service is provided in thecredential processing chapter of the IBM Security Access Manager for Web: WebSEALAdministration Guide.

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

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


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

The secondary custom authentication module is specified by the cred-ext-attrsstanza entry in the [authentication-mechanisms] stanza of the WebSEALconfiguration file. For example (Solaris):[authentication-mechanisms]cred-ext-attrs = /opt/pdweb/lib/libcustom.so

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

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

For WebSEAL to recognize the extended attribute as tag/value data, the tag nameis prefixed with the macro XAUTHN_TAG_VALUE_PREFIX, which is defined as"tagvalue_".

The following section of the xauthn.c demonstration program illustrates thisaction:char *tag = (char *) malloc(1024+XAUTHN_TAG_VALUE_KEY_PREFIX_LEN+1);char *tag_data = (char *) malloc(1024);

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

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

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

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

The following example illustrates a method of calling xattr_set to supplytag/value data (business entitlements) in a custom authentication module:char *name = strdup("tagvalue_ldap_employee_number");char *value = strdup("12345678");

if (name && value) {xattr_set (&ident->xattrs,name,value);}else {/* handle strdup failures here */}

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


xattr_set (&ident->xattrs,name,value);}else {/* handle strdup failures here */}

Modifying the user name in a credentialYou can use the Security Access Manager external authentication interface tomodify the user name provided by another authentication module.

For example, the previous authentication module might authenticate the useragainst a different user registry than the Security Access Manager user registry. Inthis case, you can use a custom module to change the user ID to a valid SecurityAccess Manager user ID.

When modifying the user identity returned by a previous authentication, theauthor of the custom module must observe the following conditions:v The custom module must deallocate the old user identity.v The custom module must use the standard C library allocation functions to

allocate the new user identity.v The format of the old user identity depends on the previous authentication

module in the chain. Some authentication modules return distinguished names;other modules return user identities in their short forms.

The following example code demonstrates appending @domain.com to the identityreturned by the previous authentication module. This code makes the followingassumptions:v The Security Access Manager registry is an LDAP server.v The previous authentication module returned a user identity and not a

distinguished name (DN).

Note: The code for Active Directory user registries uses ident->prin.data.uraf_name instead of ident->prin.data.dn.xauthn_status_txauthn_authenticate(xnvlist_t*authnInfo,xauthn_identity_t *ident){char *oldprin = NULL;char *newprin = NULL;

/* Validate the provided identity */if (authnInfo == NULL || ident == NULL) {printf("Invalid previous authentication\n");return XAUTHN_S_AUTHENTICATION_FAILURE;}oldprin = ident->prin.data.dn;if (oldprin == NULL) {printf("Invalid previous authentication\n");return XAUTHN_S_AUTHENTICATION_FAILURE;}

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


printf("Allocation failure\n");return XAUTHN_S_OUT_OF_MEMORY;}sprintf(newprin, "%[email protected]", oldprin);

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

If you want to modify the user identity returned by a previous authentication, youmust configure WebSEAL to use a custom authentication module. Use thecred-ext-attrs entry in the [authentication-mechanisms] stanza in the WebSEALconfiguration file to specify the authentication module. For example (Solaris):[authentication-mechanisms]cred-ext-attrs = /opt/pdweb/lib/libcustom.so


Chapter 5. Single sign-on customization

You can customize cross-domain single sign-on authentication and e-communitysingle sign-on authentication.

The following topics describe how to customize cross-domain single sign-onauthentication and e-community single sign-on authentication.v “WebSEAL single sign-on concepts”v “Customizing token create and consume modules” on page 35v “Customizing identity mapping and attribute handling” on page 38v “Example: Cross-domain single sign-on with a non-WebSEAL server” on page 41

WebSEAL single sign-on conceptsSecurity Access Manager Web security resource managers support cross-domainsingle sign-on and e-community single sign-on solutions.

Both single sign-on solutions employ authentication tokens that describe or "vouchfor" the user identity to the destination server. The construction of these tokens bythe initial server is called "token creation." The decoding and use of the token bythe destination server is called "token consumption."

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

The following sections explain how token creation and consumption occurs for thedefault cross-domain single sign-on and e-community single sign-on functionalitybetween two WebSEAL servers. The same concepts apply to the plug-in for WebServers.

Default token creation for cross-domain single sign-onCross-domain single sign-on token creation occurs when an authenticated user onwebsealA requests a resource from websealB.

The request is made through a special management page called pkmscdsso thattriggers the token create module (ssocreate). The request also contains thedestination URL where the resource is located.

The following example illustrates the construction of this special link to the remoteresource:http://websealA.ibm.com/pkmscdsso?http://websealB/resource.html

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


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

The following example illustrates the format of a redirect response:http://websealB/resource.html?PD-ID=encoded_authentication_token

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

Default token creation for e-community single sign-onThe "vouch for" request in e-community single sign-on is triggered when a userrequests a resource from a target server configured for e-community that containsno credential information for that user.

The server sends a redirect to the "vouch for" server for the pkmsvouchformanagement page. The "vouch for" server is either the master authentication serveror a delegated "vouch for" server identified in an e-community cookie.

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

Example request sent to the "vouch for" server:http://MAS.ibm.com/pkmsvouchfor?e-community-name&http://websealB/resource.html

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

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

The following example illustrates the format of a redirect response:http://websealB/resource.html?PD-VF=encoded_authentication_token

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

Default token consumption for cross-domain single sign-onCross-domain single sign-on token consumption occurs when the websealB serverreceives a request containing a query string argument specified by thecdsso-argument stanza entry in the [cdsso] stanza of the WebSEAL configurationfile.


The triggering string ("PD-ID" in this example) is also defined for websealB by thecdsso-argument stanza entry.

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

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

Default token consumption for e-community single sign-onE-community single sign-on token consumption occurs when the websealB serverreceives a request containing a query string argument with a name specified by thevf-argument stanza entry in the [e-community-sso] stanza of the WebSEALconfiguration file.

The triggering string ("PD-VF" in this example) is also defined for websealB by thevf-argument stanza entry.

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

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

Customizing token create and consume modulesYou can create custom token create/consume modules by modifying the examplexauthn.c source file included with the external authentication C API.

The xauthn.c source file is located in the example subdirectory of the main ADKdirectory (pdxauthn_adk).

This section contains the following topics:v “Built-in token create and consume modules”v “Example token create and consume modules” on page 36v “The token create module interface” on page 36v “The token consume module interface” on page 37

Built-in token create and consume modulesToken create and token consume functionality can be contained in one module, orseparated into two individual modules.

WebSEAL and the Plug-in for Web Servers uses two distinct built-in modules tohandle the token creation and token consumption tasks:

Chapter 5. Single sign-on customization 35

Table 16. Built-in token creation and consumption modules

Operating system Module

Solaris, Linux libssocreate.solibssoconsume.so

AIX libssocreate.alibssoconsume.a

Windows ssocreate.dllssoconsume.dll

Example token create and consume modulesThe Web Security ADK provides a pre-built platform-specific sample module thatdemonstrates single sign-on functionality like the functionality provided by thebuilt-in default modules.

The sample module performs both token creation and token consumption tasksand was built from the xauthn.c source file. You use the xauthn.c source file as thestarting point for building your own custom module.

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

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

Table 17. Example single sign-on module

Operating system Module

Solaris, Linux libxauthn.so

AIX libxauthn.a

Windows xauthn.dll

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

The token create module interfaceThe Web security resource manager passes client authentication information to thetoken create module.

The information is passed using a name/value list format, where the name is anidentifier that specifies the value type.


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

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

The XAUTHN_SSO_TYPE identifier is set to SSO_CREATE_TYPE. TheXAUTHN_INPUT_URL identifier is set to the destination URL where the resourceis located.

For example, if websealA was sent the following request:http://websealA.ibm.com/pkmscdsso?http://websealB.ibm.com/resource.html

The value of the XAUTHN_INPUT_URL identifier would behttp://websealB.ibm.com/resource.html

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

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

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

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

The value for the cdsso-redirect-url attribute appears like the following example:http://websealB.ibm.com/resource.html?TOKEN=encoded_authentication_data

The above redirect URL string is constructed using the destination URL from thepkmscdsso request, plus the user credential information passed in from thexauthn_existing_cred authentication identifier created for the authenticated userby the original Web security resource manager.

The token consume module interfaceThe label identifying the encoded token argument string (configured in thecdsso-argument or vf-argument stanza entries) allows the receiving server torecognize the incoming request as a request with an authentication token and toinvoke the token consume module.

The token consume module is passed specific user authentication data, provided asan xnvlist_t data structure. For details on these identifiers, see “Token consumeidentifiers” on page 69.


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

For example, if websealA was sent the following request:http://websealB.ibm.com/resource.html?TOKEN=encoded-data

then the value of the XAUTHN_QUERY_STRING identifier would be?TOKEN=encoded_data

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

Customizing identity mapping and attribute handlingYou can customize identity mapping for your community needs and also useextended attributes.

This section contains the following topics:v “Cross-domain mapping framework overview”v “Software requirements for the cross-domain mapping framework API” on page

39v “Build instructions for the cross-domain mapping framework API” on page 39v “Customizing the example source file” on page 39v “Providing user attributes: cdmf_get_usr_attributes()” on page 40v “Providing identity mapping: cdmf_map_usr()” on page 40

Cross-domain mapping framework overviewThe cross-domain mapping framework API is a programming interface you canuse to build custom modules that enhance the built-in token create and consumemodules.

Enhancements to the built-in modules include providing user identity mappingservices and transferring extended user attributes.

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

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

The specific operation of a customized cross-domain mapping framework moduleis determined by the developer. Use the cross-domain mapping framework APIfunctions and utilities to implement the necessary cross domain identity mappingand extended user attribute handling.


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

The second module, written as a partner to the first and located on the destinationserver, performs the following operations:v Expects possible extended attributes.v Maps the remote user identity to a local user identity.

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

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

Software requirements for the cross-domain mappingframework API

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

To use a cross-domain mapping framework module, you must have at least twoSecurity Access Manager secure domains installed, each containing a Web securityresource manager. The cross-domain mapping framework modules are called bythe built-in token create and token consume modules.

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

Build instructions for the cross-domain mapping frameworkAPI

Use these build instructions for the cross-domain mapping framework API.

Windows-specific macros

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

Customizing the example source fileYou can customize the example source file. For example, you might enable changesin the required user mapping and user attribute handling.

Procedure1. Edit the cdmf.c.skeleton source file and modify the cdmf_map_usr() and

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

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


3. For UNIX and Linux platforms, edit Makefile.cdmf.in and modify as requiredto build the module for the appropriate development platform. Instructions areincluded in the comments at the top of the file.For Windows platforms, Makefile.win32 requires no modification.

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

Table 18. Cross-domain mapping framework module name

Operating system Module name

Solaris, Linux libcdmf.so

AIX libcdmf.a

Windows cdmf.dll

Note: If you build the cross-domain mapping framework module on a Solarissystem using C++ and Sun Workshop 5 or greater, the module must be builtwith the "–compat=4" flag.

5. Stop the server process (webseald or pdwebpi).6. Replace the original cross-domain mapping framework module that was

included with the Security Access Manager product with the customizedversion.

7. Start webseald or pdwebpi server process.

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

The cdmf_get_usr_attributes() functionis called by the token creation module(ssocreate).

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

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

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

Providing identity mapping: cdmf_map_usr()The cdmf_map_usr() function is called by WebSEAL or the Plug-in for Web Serversto perform the mapping from the remote user to a local user identity.

The cdmf_map_usr() function can be used when the local and remote servers usedifferent user registries. For example:v When a cross-domain single sign-on request originating in domain A is received

by the domain B Web security resource manager, the identity of the local usermust be determined. The cdmf_map_usr() function is called to map the remoteuser (who initiated the single sign-on request) to a local user identity.

v When a request with a "vouch for" token is received by a WebSEAL or Plug-infor Web Servers server (which is the target of the request) from a master


authentication server, that WebSEAL or Plug-in for Web Servers server might berequired to map the identity of the requesting user to a local user identity.

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

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

Because the extended attribute list of the credential supports only one value, onlythe first value for each attribute becomes a part of the user credential. The domainfield is ignored.

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

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

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

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

These utility functions perform the following operations:v Create a cross-domain single sign-on user attribute listv Create a cross-domain single sign-on user attributev Add a value to a cross-domain single sign-on user attributev Add a cross-domain single sign-on user attribute to the user attribute list

For detailed information, consult the following reference pages:v cdmf_create_usr_attr_list()

v cdmf_create_usr_attr()

v cdmf_add_value_to_attr()

v cdmf_add_attr_to_list()

Example: Cross-domain single sign-on with a non-WebSEAL serverYou can create a cross-domain single sign-on with a non-WebSEAL server.


Sending cross-domain single sign-on requests to anon-WebSEAL server

Cross-domain single sign-on is a functionality that provides a single sign-onsolution between two Security Access Manager Web security resource managers.

About this task

This section describes how to set up a Security Access Manager Web securityresource manager to send a single sign-on request to a non-Security AccessManager destination server.

Procedure1. Create a custom token create module based on the xauthn.c example source

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

2. In the server configuration file, set the sso-create authentication mechanismparameter to the full path name of the token create module. For example, onSolaris:[authentication-mechanisms]sso-create = /opt/pdwebrte/lib/libxauthn.so

Specify a full path name to this module.3. Enable the Web security resource manager to generate single sign-on requests

by communication type:WebSEAL:

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

Plug-in for Web Servers:[common-modules]pre-authzn = cdsso

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

Results

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

When the cross-domain single sign-on link is activated by an authenticated user,the token create module constructs a redirect request made up of the destinationURL and encoded identity information describing the user. The format andcontents of the redirected request URL, constructed by the custom module, mustbe compatible with how the destination server is configured to accept and readthis request.


Accepting cross-domain single sign-on requests from anon-WebSEAL server

You can set up a Security Access Manager Web security resource manager to accepta single sign-on request from a Web Security resource manager on a non-SecurityAccess Manager server.

Procedure1. Create a custom token consume module based on the xauthn.c example source

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

2. In the Security Access Manager Web server configuration file, set thesso-consume authentication mechanism parameter to the full path name of thetoken create module file. For example, on Solaris:[authentication-mechanisms]sso-consume = /opt/pdwebrte/lib/libxauthn.so

You must specify a full path name to this module.3. Enable the Web security resource manager to process single sign-on requests by

communication type:WebSEAL:[cdsso]cdsso-auth = {http | https | both}

Plug-in for Web Servers:[common-modules]authentication = cdsso

4. Set the cdsso-argument label to the appropriate value that matches what theserver that is not protected by Security Access Manager sends in its request andthat uniquely identifies the request as a single sign-on request to be handled bythe Security Access Manager Web security resource manager cross-domainsingle sign-on functionality:[cdsso]cdsso-argument = token_argument_ID

Results

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

The token consume module is called. The module parses and decodes the querystring of the request. The resulting user identity is passed to the Web securityresource manager which uses it to authenticate the user and continue processingthe request.

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

If authentication is not successful, the Security Access Manager Web securityresource manager presents the user with a login prompt.



Appendix A. External authentication C API reference

This reference describes data structures, external authentication C API functions,and utility API functions.

Note:

1. The following index is organized by function and data structure categories. Thereference pages are organized alphabetically.

2. The external authentication C API contains certain internal functions that arenot intended for use by customers. These functions are not supported and maybe deprecated. Such functions are wrapped in #if defined C preprocessordirectives to prevent their accidental use.v Functions in the xnvlist.h file wrapped with

#if defined (XNVLIST_PRIVATE)

are not supported.v Functions in the xattr.h file wrapped with

#if defined (XATTR_DEPRECATED)

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

Data structures:

v “xattr_list_item_t” on page 46v “xattr_list_t” on page 46v “xauthn_identity_t” on page 50v “xnvlist_item_t” on page 54v “xnvlist_t” on page 54

External authentication C API functions:

v “xauthn_authenticate()” on page 48v “xauthn_change_password()” on page 49v “xauthn_initialize()” on page 51v “xauthn_shutdown()” on page 51v “xauthn_utils_append_extcred_tags()” on page 47

Utility API functions:

v “xattr_get()”v “xattr_set()” on page 47v “xauthn_util_entry_to_creds()” on page 52v “xnvlist_get()” on page 53

xattr_get()

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


Syntaxintxattr_get(xattr_list_t *list,char *name,char **value);

Description

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

Parameters

Input

listA pointer to the name and 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 must not free the value returned.

Return Values

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

xattr_list_item_t

Holds a single extended attribute.

Definition

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

Values

nameA string representing the name of the extended attribute.

valueA string representing the value of the extended attribute.

xattr_list_t

Lists extended attributes to be added to the credential.


Definition

typedef struct {longlength;xattr_list_item_t *items;} xattr_list_t;

Values

lengthThe number of elements in the list.

itemsAn array of xttr_list_item_t structures.

xattr_set()

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

Syntaxintxattr_set(xattr_list_t *list,char *name,char *value);

Description

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

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

Parameters

Input


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

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

Return Values


xauthn_utils_append_extcred_tags()

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

Appendix A. External authentication C API reference 47

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

Parameters

Input

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

Output

xattrsThe extended attributes list to be added to.

stXAUTHN error status.

Return Values

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

xauthn_authenticate()

Performs the authentication module authentication tasks.

Syntaxxauthn_status_txauthn_authenticate(xnvlist_t *authnInfo,xauthn_identity_t *ident);

Description

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

See “Obtaining user authentication information” on page 25 for the list ofauthentication data that authnInfo can contain.

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

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

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


Parameters

Input

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

Input/Output

identThe ident parameter contains the authenticated user information.

Return Values

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

xauthn_change_password()

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

Syntaxxauthn_status_txauthn_change_password(xnvlist_t *authnInfo);

Description

The authentication dispatcher calls this interface to implement a custom passwordchange mechanism. This interface is supported only for username/password andtoken authentication mechanisms. Client password change information is passedby the dispatcher through the input argument authnInfo.

Alternatively, a module implementing this interface can provide a passwordstrength operation. Instead of actually updating a client password,xauthn_change_password() verifies whether the new password of the client satisfiesthe custom conditions of the module. The same password change information isincluded in authnInfo for both uses of the interface.

Refer to “Obtaining user authentication information” on page 25 for the list ofauthentication data that authnInfo can contain.

Parameters

Input

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

Return Values

If successful, the function returns XAUTHN_S_COMPLETE.


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

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

xauthn_identity_t

Holds information about a user Security Access Manager identity.

Definition

typedef struct {struct {unsigned32 prin_type;union {/* case(s): 0 */char *name;/* case(s): 1 */char *dn;/* case(s): 2 */char *uraf_name;} data;} prin;char*user_info;char*authnmech_info;xattr_list_t xattrs;} xauthn_identity_t;

Values

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

nameNot valid.

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

uraf_nameNot valid.

user_infoInformation added to the credential as an extended attribute calledazn_cred_user_info.

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

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


xauthn_initialize()

Initializes the specified authentication module.

Syntaxxauthn_status_txauthn_initialize(int argc,const char **argv);

Description

Use this initialization function to initialize an authentication module. The inputparameters argc and argv are built from parameters specified in the[authentication-mechanisms] stanza of the secure Web server configuration file.The following example definition uses the sample module:passwd-ldap = libxauthn.so& -dbms sys.db

In the preceding example, xauthn_initialize() is called with an argc value of 2.The argv array contains the following values:argv[0] = "-dbms"argv[1] = "sys.db"

Input parameters should not be modified.

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

Parameters

Input

argcThe number of arguments contained in the argv array.

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

Return Values


xauthn_shutdown()

Shuts down the specified authentication module.

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


Syntaxxauthn_status_txauthn_shutdown(int argc,const char **argv);

Description

During the normal shutdown, the WebSEAL authentication dispatcher calls thisinterface to perform any shut down processes that might be required by thecustom environment. The input parameters argc and argv are built from theparameters specified in the [authentication-mechanisms] stanza of the secure Webserver configuration file. The following example definition uses the samplemodule:passwd-ldap = libxauthn.so& -dbms sys.db

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

Input parameters should not be modified.

Parameters

Input

argcThe number of arguments contained in the argv array.

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

Return Values


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

Description

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


The caller does not need to free the returned azn_creds_h_t.

Parameters

Input

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

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

Return Values

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

xnvlist_get()

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

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

Description

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

Parameters

Input


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.

Return Values



xnvlist_item_t

Holds a single item of authentication data.

Definition

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

Values

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

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

vlenAn integer value representing the length of the value array.

Description

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

xnvlist_t

Holds a list of xnvlist_item_t authentication data structures.

Definition

typedef struct {longlength;xnvlist_item_t *items;} xnvlist_t;

Values

lengthThe number of elements in the "items" array.

itemsAn array of xnvlist_item_t.


Appendix B. Cross-domain mapping framework C APIreference

This reference describes utility API functions, cross-domain mapping frameworkAPI functions, and memory management macros.

Note: The following index is organized by function and data structure categories.The reference pages are organized alphabetically.

Utility API functions:

v “cdmf_add_attr_to_list()”v “cdmf_add_value_to_attr()” on page 56v “cdmf_create_usr_attr()” on page 56v “cdmf_create_usr_attr_list()” on page 57

Cross-domain mapping framework API functions:

v “cdmf_get_usr_attributes()” on page 57v “cdmf_map_usr()” on page 58

Memory management macros:

v “CDSSO_FREE()” on page 59v “CDSSO_MALLOC()” on page 60v “CDSSO_REALLOC()” on page 60v “CDSSO_STRDUP()” on page 61

cdmf_add_attr_to_list()

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

Syntaxintcdmf_add_attr_to_list(cdsso_usr_attr_t *new_attr,cdsso_attrlist_t *list);

Description

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

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

Parameters

Input

new_attrNew attribute to be added to the list.


Output

listUpdated list.

Return Values

If successful, the function returns TRUE.

Otherwise, the function returns FALSE.

cdmf_add_value_to_attr()

Adds a new value to a user attribute.

Syntaxintcdmf_add_value_to_attr(char *new_value,cdsso_usr_attr_t *attr);

Description

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

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

Parameters

Input

new_valueNew value to be added to the attribute.

Output

attrUpdated user attribute object.

Return Values

If successful, the function returns TRUE.

Otherwise, the function returns FALSE.

cdmf_create_usr_attr()

Creates a new user attribute.

Syntaxcdsso_usr_attr_t *cdmf_create_usr_attr(char *attr_name);


Description

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

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

Parameters

Input

attr_nameName of the new attribute.

Return Values

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

Otherwise, the function returns NULL.

cdmf_create_usr_attr_list()

Creates an empty attribute list.

Syntaxcdsso_attrlist_t *cdmf_create_usr_attr_list(void);

Description

Creates an empty attribute list.

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

Parameters

None.

Return Values

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

Otherwise, the function returns NULL.

cdmf_get_usr_attributes()

Retrieves the extended attributes for the specified user.

Syntaxintcdmf_get_usr_attributes(char *usr,cdsso_attrlist_t **attr_list);

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

Description

WebSEAL and plug-in for Web Servers call this interface:v When a cross-domain single sign-on request is initiated by a user accessing the

/pkmscdsso page on the local WebSEAL or plug-in for Web Servers server.v When an e-community "vouch for" server generates a "vouch for" reply token for

another WebSEAL or plug-in for Web Servers server in the e-community.

In a cross-domain single sign-on operation, the extended attribute list returned bythis function is sent to the remote WebSEAL or plug-in for Web Servers server (thetarget of the request) inside the authentication token.

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

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

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

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

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

Parameters

Input

usrUser name.

Output

attr_listExtended attributes for input user.

Return Values

If successful, the function returns CDMF_SUCCESS.

Upon failure, the function returns CDMF_FAILURE.

cdmf_map_usr()

Maps a remote user into a local user.

Syntaxintcdmf_map_usr(cdsso_user_info_t *remote_usr,cdsso_user_info_t *local_usr);


Description

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

The remote user information is received in a cdsso_usr_info_t structure. Thisinformation includes the remote user name, the remote domain name, and possiblyan extended attribute list. This information should be used to determine theidentity of the local user.

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

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

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

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

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

Parameters

Input

remote_usrOut of domain user.

Input/Output

local_usrUser mapped to in this domain.

Return Values

If successful, the function returns CDMF_SUCCESS.

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

Upon failure, the function returns CDMF_FAILURE.

CDSSO_FREE()

Deallocate the specified memory.


SyntaxvoidCDSSO_FREE(void *ptr,);

Description

Deallocate the specified memory.

Parameters

ptrA pointer to the memory to be deallocated.

Return Values

Success: none.

Error: none

CDSSO_MALLOC()

Allocates a portion of memory of the specified size.

Syntaxvoid *CDSSO_MALLOC(size_t size,);

Description

Allocates a portion of memory of the specified size.

The caller is responsible for freeing the allocated memory.

Parameters

sizeSize in bytes of memory to allocate.

Return Values

Returns a pointer to newly allocated memory.

Returns NULL if the call fails.

CDSSO_REALLOC()

Reallocates a memory block.

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


Description

Reallocates a memory block.

The caller is responsible for freeing the allocated memory.

Parameters

curr_ptrPointer to the existing memory to be deallocated.

new_sizeSize in bytes of the new portion of memory.

Return Values

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

Returns NULL is any memory errors are encountered.

CDSSO_STRDUP()

Duplicates the specified string.

Syntaxvoid*CDSSO_STRDUP(char *dest,char *src);

Description

Duplicates the specified string.

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

Parameters

destDestination string.

srcSource string.

Return Values

When successful, returns a pointer to the new memory.

Returns NULL if the call fails.



Appendix C. Authentication identifiers reference

This reference describes identifiers used by authentication modules.

The following sections list the identifiers that contain authentication information:v “Identifiers common to all authentication methods”v “User name and password authentication identifiers” on page 64v “Certificate authentication identifiers” on page 65v “Token card authentication identifiers” on page 66v “HTTP authentication identifiers” on page 66v “Failover authentication identifiers” on page 67v “EAI identifiers” on page 68v “Token create identifiers” on page 68v “Token consume identifiers” on page 69v “Switch user authentication identifiers” on page 69

The auto-refresh option for certificate authentication calculates the life time valueof the certificate and verifies every time an action using SSLSocket/SSLServerSocket. A SSLSocket/SSLServerSocket is created based on the PDContext.

While a newPDContext is created, a thread calculates the life span of the certificate.The certificate will be refreshed only if its lifetime is less than the certificatehalf-life period. One thread refreshes the context and another thread reloads therefreshed certificate. A new SSLContext is established with the new certificate, andthe server request is processed.

Identifiers common to all authentication methodsAll Security Access Manager authentication methods use a common set ofidentifiers.

Combine the identifiers in the following set with the identifiers that are specific tothe authentication method for your authentication module. The identifiers used forspecific authentication methods are described in separate sections that follow thisone.

Table 19. Identifiers common to all authentication methods

Name Description

XAUTHN_BROWSER_INFO Browser information.

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

Example:

"Mozilla/4.0 (Compatible; MSIE 6.0;Windows NT 5.0)"


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

Name Description

XAUTHN_EXISTING_CRED Used only for re-authentication and step-upauthentication. This contains the existing credential ofthe user as a string. In a switch-user operation, theidentity is the credential of the "switched-to" user.

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

Example: 0123456

XAUTHN_IPADDR User IPv4 address.


Example: 11.22.33.44

XAUTHN_IPADDR_IPV6 User IPv6 address.


Example: 9::8:7:6

XAUTHN_QOP Quality of protection. The format is:

authentication_method:version:cipher_used


Examples:

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

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

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

User name and password authentication identifiersUser name and password authentication use the set of identifiers common to allauthentication methods and a set of identifiers that are specific to user name andpassword.

See Table 19 on page 63. The following table lists the specific identifiers:


Table 20. Identifiers used for user name and password authentication

Name Description

XAUTHN_USERNAME User name.

Example: testuser

XAUTHN_PASSWORD User password.

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

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

token-cardpassword

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

Certificate authentication identifiersCertificate authentication uses the set of identifiers common to all authenticationmethods and a set of identifiers that are specific to certificate authentication.

Ssee Table 19 on page 63. The following table lists the specific identifiers:

Table 21. Identifiers used for certificate authentication

Name Description

XAUTHN_CERT The certificate body, in DER format.

Example: binary-data

XAUTHN_CERT_DN The DN of the certificate.

Example:

cn=testuser,o=tivoli,c=us

XAUTHN_CERT_ISSUER_DN The DN of the issuer certificate authority.

Example:

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

XAUTHN_CERT_SERIAL_NUMBER The client certificate serial number.

Example:

04-67-F3-02

Appendix C. Authentication identifiers reference 65

Token card authentication identifiersToken card authentication uses the set of identifiers common to all authenticationmethods and a set of identifiers that are specific to token card authentication.


Table 22. Identifiers used for token card authentication

Name Description

XAUTHN_USERNAME User name.

Example: testuser

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

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

Example: 0123

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

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

HTTP authentication identifiersHTTP authentication uses the set of identifiers common to all authenticationmethods and a set of identifiers that are specific to HTTP authentication.


Table 23. Identifiers used for HTTP header authentication

Name Description

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

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

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

For example (entered as one line):

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

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


Table 23. Identifiers used for HTTP header authentication (continued)

Name Description

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

Example HTTP Referer header (entered as one line):

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

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

Failover authentication identifiersFailover authentication uses the set of identifiers common to all authenticationmethods and a set of identifiers that are specific to failover authentication.


Table 24. Identifiers used for failover authentication

Name Value

XAUTHN_ATTR Any extended attributes are passed in the xnvlist_t*pointer with XAUTHN_ATTR (xauthn_attr_) prefixed tothem.

For example, if you add an attribute calledcreditcard=123412341234, it would show up in thexnvlist as xauthn_attr_creditcard with a value of123412341234. There can be several entries prefixed withXAUTHN_ATTR.

XAUTHN_FAILOVER_METHOD Value is one of the following:

v failover-password

v failover-certificate

v failover-token-card

v failover-http-request

v failover-cdsso

v failover-kerberosv5

v su-failover-ext-auth-interface

v failover-sso-create

v failover-sso-consume

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

XAUTHN_USERNAME Contains the user name.

For example:

test-user


EAI identifiersThe external authentication interface (EAI) uses the set of identifiers common to allauthentication methods and and a set of identifiers that are specific to the EAI.


Table 25. Identifiers used for EAI authentication

Name Value

XAUTHN_ATTR Any extended attributes are passed in the xnvlist_t*pointer with XAUTHN_ATTR (xauthn_attr_) prefixed tothem.

For example, if you add an attribute calledcreditcard=123412341234, it would show up in thexnvlist as xauthn_attr_creditcard with a value of123412341234. There can be several entries prefixed withXAUTHN_ATTR.

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

XAUTHN_USERNAME Contains the user name.

For example:

test-user

Token create identifiersThe token create module, used for CDSSO and ECSSO, uses the set of identifierscommon to all authentication methods and a set of identifiers that are specific totoken creation.


Table 26. Identifiers used for token creation

Identifier Description

XAUTHN_HOSTNAME Contains the source machine name.

XAUTHN_INPUT_URL Destination URL. For example:

http://example.com/request.htm

XAUTHN_SSO_TYPE A string that is created and freed by WebSEAL.

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

Values can be SSO_CREATE_TYPE or SSO_CONSUME_TYPE.


Table 26. Identifiers used for token creation (continued)


XAUTHN_TOKEN_TYPE This identifier contains an integer representing thetoken type used to determine whether the modulewas called to generate an e-community single sign-onvouch-for token or a CDSSO authentication token.

Valid values for this are the integer 2 for CDSSO andthe integer 3 for e-community single sign-on. Forexample:

XAUTHN_TOKEN_TYPE = 3

XAUTHN_VFT_STATUS This identifier contains the success or failure status ofthe authentication performed at an e-communitysingle sign-on "vouch-for" server.

For example:

XAUTHN_VFT_STATUS = 320938186

This value is the error status code number.

Token consume identifiersThe token consume module, used for CDSSO and ECSSO, uses the set ofidentifiers common to all authentication methods and a set of identifiers that arespecific to token consumption.


Table 27. Identifiers used for token consumption


XAUTHN_SSO_TYPE This is a string created and released by WebSEAL.

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

Values can be SSO_CREATE_TYPE or SSO_CONSUME_TYPE.

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

Switch user authentication identifiersAn existing authentication module often returns additional information about theuser that is incorporated into the credential of the user.

If you are using the switch user feature in such an environment, you must write aspecial switch user authentication module that emulates the behavior of yourexisting authentication module while supporting the requirement of returning acredential without requiring the user password for input. Switch user functiondoes not support External Authentication Interface (EAI).


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

Security Access Manager supports switch-user authentication for password, tokencard, certificate, HTTP request, and single sign-on token authentication methods.For more information about switch user authentication, including configurationinstructions, see the IBM Security Access Manager for Web: WebSEAL AdministrationGuide.

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

Table 28. Identifiers used for switch user authentication

Name Value

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

v su-password

Username and password authentication

v su-token-card

Token authentication

v su-certificate

X.509 certificate authentication

v su-http-request

HTTP header authentication

v su-cdsso

Cross-domain single sign-on authentication.

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

sec_master

XAUTHN_ADMIN_CRED The credential of the administrator attempting to switchuser, as a string.

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

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

test-user


Appendix D. External authentication interface

Security Access Manager provides an external authentication interface that enablesyou to extend the functionality of the WebSEAL and the plug-in for Web Serversauthentication process.

The external authentication interface allows a remote service to handle theauthentication process for WebSEAL and the plug-in for Web Servers. The identityinformation returned by the external authentication interface service is used togenerate user credentials.

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

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

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

For complete information about configuring and using the external authenticationinterface, see the following guides:v IBM Security Access Manager for Web: WebSEAL Administration Guide

v IBM Security Access Manager for Web: Plug-in for Web Servers Administration Guide



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-1785 U.S.A.

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

Intellectual Property LicensingLegal and Intellectual Property LawIBM Japan, Ltd.19-21, Nihonbashi-Hakozakicho, Chuo-kuTokyo 103-8510, Japan

The following paragraph does not apply to the United Kingdom or any othercountry where such provisions are inconsistent with local law :

INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THISPUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHEREXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIEDWARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESSFOR A PARTICULAR PURPOSE.

Some states do not allow disclaimer of express or implied warranties in certaintransactions, therefore, this statement might not apply to you.

This information could include technical inaccuracies or typographical errors.Changes are periodically made to the information herein; these changes will beincorporated in new editions of the publication. IBM may make improvementsand/or changes in the product(s) and/or the program(s) described in thispublication at any time without notice.

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


IBM may use or distribute any of the information you supply in any way 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 78758 U.S.A.

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

The licensed program described in this document and all licensed materialavailable for it are provided by IBM under terms of the IBM Customer Agreement,IBM International Program License Agreement or any equivalent 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.

All IBM prices shown are IBM's suggested retail prices, are current and are subjectto change without notice. Dealer prices may vary.

This information is for planning purposes only. The information herein is subject tochange before the products described become available.

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

COPYRIGHT LICENSE:

This information contains sample application programs in source language, whichillustrate programming techniques on various operating platforms. You may copy,modify, and distribute these sample programs in any form without payment to


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

If you are viewing this information in softcopy form, the photographs and colorillustrations might not be displayed.

Trademarks

IBM, the IBM logo, and ibm.com® are trademarks or registered trademarks ofInternational Business Machines Corp., registered in many jurisdictions worldwide.Other product and service names might be trademarks of IBM or other companies.A current list of IBM trademarks is available on the Web at "Copyright andtrademark information" at www.ibm.com/legal/copytrade.shtml.

Adobe, Acrobat, PostScript and all Adobe-based trademarks are either registeredtrademarks or trademarks of Adobe Systems Incorporated in the United States,other countries, or both.

IT Infrastructure Library is a registered trademark of the Central Computer andTelecommunications Agency which is now part of the Office of GovernmentCommerce.

Intel, Intel logo, Intel Inside, Intel Inside logo, Intel Centrino, Intel Centrino logo,Celeron, Intel Xeon, Intel SpeedStep, Itanium, and Pentium are trademarks orregistered trademarks of Intel Corporation or its subsidiaries in the United Statesand other countries.

Linux is a trademark of Linus Torvalds in the United States, other countries, orboth.

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

ITIL is a registered trademark, and a registered community trademark of the Officeof Government Commerce, and is registered in the U.S. Patent and TrademarkOffice.

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

Cell Broadband Engine and Cell/B.E. are trademarks of Sony ComputerEntertainment, Inc., in the United States, other countries, or both and is used underlicense therefrom.

Notices 75

Java and all Java-based trademarks and logos are trademarks or registeredtrademarks of Oracle and/or its affiliates.


Index

Aaccessibility xiiiADK (application development kit)

components 9cross-domain mapping framework

API 10EPAC demonstration

application 11external authentication C API 9password strength API 11

overview 1amwauthconv 19API

external authentication reference 45application development kit (ADK)

components 9cross-domain mapping framework

API 10EPAC demonstration

application 11external authentication C API 9password strength API 11

overview 1authentication

external authentication interface 71authentication data structure 23authentication identifiers

reference 63authentication interfaces 3

external authentication C API 4external authentication C API

modules 4Security Access Manager

authorization API 4Security Access Manager runtime 3Web security resource manager 3

authentication mechanismsstanza entries 16

authentication moduleadding extended attributes to the

credential 29build instructions 14customizing password strength

checking 28customizing the authentication

process 25customizing user password

change 27example library 15modifying the user name in a

credential 31processing post password

changes 28software requirements 14task summary 13UTF-8 compatibility 18WebSEAL configuration 16writing custom modules 25

authentication module examplelibrary 15

authentication process flows 5

authentication process flows (continued)authentication 5change password 6extended attributes 8password strength 6post password change 7

authentication stanza entry 43authentication terminology

mechanism 2method 2module 2operations 2

authnmech_info 23

Ccdmf module 40cdmf_add_attr_to_list() 55cdmf_add_value_to_attr() 56cdmf_adk directory 10cdmf_create_usr_attr_list() 57cdmf_create_usr_attr() 56cdmf_get_usr_attributes() 39, 40, 57cdmf_map_usr() 39, 40, 58cdmf_utils.h header file 10cdmf_utils.lib library file 10cdmf.c.example source file 10cdmf.c.skeleton source file 10, 39cdmf.h header file 10cdsso_attrlist_t 41CDSSO_FREE() 60CDSSO_MALLOC() 60CDSSO_REALLOC() 60CDSSO_STRDUP() 61cdsso_usr_info_t 41cdsso-argument 34cdsso-argument stanza entry 43cdsso-auth stanza entry 43cdsso-redirect-url attribute 37cdssotypes.h header file 10conversion library 19

configuration 19cred-ext-attrs stanza entry 30, 32credential

UTF-8 data format 18credential attributes

AUTHENTICATION_LEVEL 12AZN_CRED_AUTH_METHOD 12AZN_CRED_AUTHNMECH_

INFO 12AZN_CRED_AUTHZN_ID 12AZN_CRED_BROWSER_INFO 12AZN_CRED_GROUPS 12AZN_CRED_GROUPS_NAMES 12AZN_CRED_IP_ADDRESS 12AZN_CRED_LDAP_DN 12AZN_CRED_MECH_ID 12AZN_CRED_PRINCIPAL_NAME 12AZN_CRED_PRINCIPAL_UUID 12AZN_CRED_QOP_INFO 12AZN_CRED_VERSION 12

credential attributes (continued)table of 12

cross-domain mapping framework APIaccepting requests from a

non-WebSEAL server 43build instructions 39customizing the example source

file 39overview 38providing identity mapping 40providing user attributes 40sending single sign-on with a

non-WebSEAL server 42single sign-on with a non-WebSEAL

server 42software requirements 39specifying extended attributes 41understanding functions and

macros 10cross-domain mapping framework API

description 10cross-domain single sign-on

token consumption 35token creation 33

custom modulesadding extended attributes to the

credential 29customizing password strength

checking 28customizing the authentication

process 25customizing user password

change 27modifying the user name in a

credential 31processing post password

changes 28writing custom modules 25

customizingattribute handling 38identity mapping 38

customizingmodules 35

Ddata structures 22

authentication data 23extended attributes 22user identity information 22xattr_list_item_t 46xattr_list_t 47xauthn_identity_t 50xnvlist_item_t 54xnvlist_t 54

DB2 xiideprecated APIs

password strength 11displaying credential attributes 12


Ee-community single sign-on

token consumption 35token creation 34

education xivEPAC 11

displaying credential attributes 12epac demonstration program 11EPAC example application 11epac.c source file 11extended attribute data structure 22extended attributes 30, 41extended privilege attribute

certificate 11external authentication

API 45interface 71

external authentication C APIbuild instructions 14data structures 22example library 15functions 20initializing 21software requirements 14writing custom modules 25

external authentication C APIdescription 9

Ffunctions 20

cdmf_add_attr_to_list() 55cdmf_add_value_to_attr() 56cdmf_create_usr_attr_list() 57cdmf_create_usr_attr() 56cdmf_get_usr_attributes() 57cdmf_map_usr() 58xattr_get() 21, 46xattr_set() 21, 47xauthn_authenticate() 20, 48xauthn_change_password() 21, 49xauthn_initialize() 20, 51xauthn_shutdown() 21, 51xauthn_util_entry_to_creds() 21, 52xauthn_utils_append_extcred_

tags() 48xnvlist_get() 21, 53

Ggskcapicmd xiigskikm.jar xiiGSKit

documentation xii

Hheader_name 66HTTP_IV_CREDS

in EPAC example 11

IIBM

Software Support xiv

IBM (continued)Support Assistant xiv

identifier types (authentication)certificate 65common 63EAI 68failover 67HTTP 66switch user 69token card 66token consume 69token create 68username and password 64

identifiers (authentication)header_name 66Request_URI 66XAUTHN_ADMIN_CRED 69XAUTHN_ADMIN_NAME 69XAUTHN_ATTR 67, 68XAUTHN_BROWSER_INFO 63XAUTHN_CERT 65XAUTHN_CERT_DN 65XAUTHN_CERT_ISSUER_DN 65XAUTHN_CONFIG 63XAUTHN_EXISTING_CRED 63XAUTHN_FAILOVER_ METHOD 67XAUTHN_HOSTNAME 68XAUTHN_INPUT_URL 68XAUTHN_IPADDR 63XAUTHN_IPADDR_IPV6 63XAUTHN_METHOD 64, 66XAUTHN_NEW_ PASSWORD 64XAUTHN_NEW_PASSWORD 66XAUTHN_NUM_ATTRS 67, 68XAUTHN_PASSWORD 64, 66XAUTHN_QOP 63XAUTHN_QUERY_STRING 66, 69XAUTHN_REFERER 66XAUTHN_SSO_TYPE 68, 69XAUTHN_SU_METHOD 69XAUTHN_TOKEN 66XAUTHN_TOKEN_TYPE 68XAUTHN_USERNAME 64, 66, 67,

68, 69XAUTHN_VFT_STATUS 68

iKeyman xiiinterfaces (authentication) 3

external authentication C API 4external authentication C API

modules 4Security Access Manager

authorization API 4Security Access Manager runtime 3Web security resource manager 3

Kkey xii

LLDAP server

on z/OS xiilibamwauthnconv 19libcdmf module 40libcdmfutils. (so, a, sl) library file 10

libpdxauthn.a library file 9libssoconsume module 35libssocreate module 35libxauthn module 36

MMakefile.cdmf.in makefile 10Makefile.in makefile 11Makefile.win32 makefile 10memory management macros

CDSSO_FREE() 60CDSSO_MALLOC() 60CDSSO_REALLOC() 60CDSSO_STRDUP() 61

module interface 37

Oonline

publications ixterminology ix

Ppasswd-strength stanza entry 28password strength 11password strength API description 11pdxauthn libraries 21pdxauthn_adk directory 9pdxauthn.h header file 9pdxauthn.lib library file 9pkmscdsso page 33pkmsvouchfor 34pkmsvouchfor page 34post password change processing 28post-pwdchg-process stanza entry 29pre-authzn stanza entry 42problem-determination xivprocess flows 5

authentication 5change password 6extended attributes 8password strength 6post password change 7

publicationsaccessing online ixlist of for this product ix

RRequest_URI 66resource manager 1

Ssample code 30single sign-on

cross-domain single sign-on 33customization 33e-community single sign-on 33

single sign-on customizationaccepting requests from a

non-WebSEAL server 43


single sign-on customization (continued)built-in token create and consume

modules 35cross-domain mapping framework

overview 38example token create and consume

modules 36providing identity mapping 40providing user attributes 40single sign-on with a non-WebSEAL

server 42specifying extended attributes 41token consumption

cross-domain single sign-on 35e-community single sign-on 35

token creationcross-domain single sign-on 33e-community single sign-on 34

single signon customizationcross-domain mapping framework

build instructions 39cross-domain mapping framework

example source file 39cross-domain mapping framework

software requirements 39customizing identity mapping and

attribute handling 38token consume module interface 37token create module interface 36

source filexauthn.c 9

sso-consume stanza entry 36, 43sso-create stanza entry 36, 42ssoconsume module 35ssocreate module 33, 34, 35switch user authentication 69

Tterminology ixterminology (authentication)

mechanism 2method 2module 2operations 2

Tivoli Directory Integrator xiiTivoli Directory Server xiitoken consume 37token consumption

ssoconsume module 35token create

module interface 36token creation

ssocreate module 33, 34training xivtroubleshooting xiv

Uuser identity data structure 22UTF-8 19

compatibility 18conversion library 19entitlements service data format 19user credential data format 18

WWeb security resource manager 1WebSEAL

configuration for custom modules 16WebSphere Application Server Network

Deployment xiiWebSphere eXtreme Scale xii

Xxattr_get() 21, 46xattr_list_item_t 22, 46xattr_list_t 22, 47xattr_set() 21, 47xattr.h header file 9xauthn module 36XAUTHN_ADMIN_CRED 69XAUTHN_ADMIN_NAME 69XAUTHN_ATTR 67, 68xauthn_authenticate() 5, 20, 25, 29, 48XAUTHN_BROWSER_INFO 63XAUTHN_CERT 65XAUTHN_CERT_DN 65XAUTHN_CERT_ISSUER_DN 65xauthn_change_password() 5, 21, 27, 49XAUTHN_CONFIG 63XAUTHN_EXISTING_CRED 63XAUTHN_FAILOVER_METHOD 67XAUTHN_HOSTNAME 68xauthn_identity_t 22, 26, 50xauthn_initialize() 5, 20, 21, 28, 51XAUTHN_INPUT_URL 68XAUTHN_IPADDR 63XAUTHN_IPADDR_IPV6 63XAUTHN_METHOD 64, 66XAUTHN_NEW_ PASSWORD 64XAUTHN_NEW_PASSWORD 66XAUTHN_NUM_ATTRS 67, 68XAUTHN_PASSWORD 64, 66XAUTHN_QOP 63XAUTHN_QUERY_STRING 66, 69XAUTHN_REFERER 66xauthn_shutdown() 5, 21, 28, 51XAUTHN_SSO_TYPE 68, 69XAUTHN_SU_METHOD 69XAUTHN_TOKEN 66XAUTHN_TOKEN_TYPE 68XAUTHN_USERNAME 64, 66, 67, 68,

69xauthn_util_entry_to_creds() 21, 52xauthn_utils_append_extcred_tags() 48XAUTHN_VFT_STATUS 68xauthn.c source file 9xnvlist_get() 21, 36, 53xnvlist_item_t 23, 54xnvlist_t 23, 36, 54xnvlist.h header file 9

Index 79


��

Printed in USA

SC23-6517-02

Documents

IBM SecurityAccess Manager Version 7