Copy Validation List To Directory (QGLDCPYVL) API

The Copy Validation List To Directory API copies internet users defined in a validation list to the local IBM Directory Server. The API creates inetOrgPerson directory entries with passwords based on the original validation list entry. This API is intended to be used with validation list entries created for use with the HTTP Server.

The API can copy only those validation list entries which do not correspond to existing directory entries, or the API can be used to also update the userpassword attribute of existing entries from the validation list, keeping the directory entry passwords synchronized with the validation list.

Once the validation list entries have been copied into directory entries there is no link between the two. Validation list entries and directory entries can be added, changed, and deleted without affecting the other.

All entries in the validation list are copied to the directory server. If only a subset of entries is wanted, a copy of the original validation list can be used, containing only the entries of interest. The API can be run multiple times copying the same validation list to the directory server.

Notes:

1. When copying a validation list for which a corresponding directory entry already exists, informational message GLD023B, Object for user &1 already exists, may be logged. Additionally, the directory server job log may contain message GLD0401, Entry already exists.
2. Directory server password policy applies to the newly created entries with the exception that the new entries will not be created with the password marked as reset.
3. Validation lists may contain entries with CCSID values that are not valid even though the corresponding user names and passwords appear to work correctly in other applications. These incorrect CCSIDs result in a diagnostic message, GLD023E - Error with &1 value in validation list entry. If this error occurs, this API can be used to copy these entries if the Alternate CCSID parameter is specified. This parameter provides a CCSID to be used when validation list entries have CCSID values that are not valid. The CCSID to use is typically the job CCSID of the application that uses the validation list.

This API can be used as follows:

• The API can be called as one-time process to add a static set of internet users to the IBM Directory Server. Once added to the directory, these users can authenticate both to applications that use the validation list and to applications using LDAP authentication. Because data is copied from the validation list to the directory server, subsequent changes to either set of users do not affect the other.
• The API can be called periodically to add new internet users to the IBM Directory Server. The API checks for existing entries and adds entries for users that are not currently defined in the directory server. Passwords for existing directory entries are optionally updated. Deletion of users from the validation list is not detected; the corresponding directory entries will remain.
• After copying the directory entries, the original applications can be changed to use LDAP authentication, and the original validation list deleted, or the validation list can be left on the system for continued use by other applications.

Mapping of Validation List Entries to Directory Entries

The validation list entries must be of the format used by HTTP Server internet users:

• The entry id contains the user name, tagged with a CCSID.
• The entry data contains the comments.
• The encrypted data contains the user password, tagged with a CCSID and one-way encrypted.

This information is mapped to a directory entry as follows:

For example, using the parent DN cn=http users,o=my company and an internet user defined in the validation list MYLIB/HTTPVLDL:

   user name:  jsmith (CCSID 37)
   comments:   John Smith, dept ABC
   password:   ****** (CCSID 37)

   dn: uid=jsmith,cn=http users,o=my company
   objectclass: top
   objectclass: person
   objectclass: organizationalPerson
   objectclass: inetOrgPerson
   uid: jsmith
   cn: jsmith
   sn: jsmith
   description: John Smith, dept ABC
   userpassword: {VLDL}<password data>

The additional objectclass name parameter is used when you want to create directory entries that use an objectclass other than the default inetOrgPerson class. For example, you may have defined your own structural or auxiliary objectclass that includes additional attributes you want to be able to use with these entries. This API imposes the following restrictions on the additional objectclass name:

• The objectclass must be a structural objectclass that inherits from inetorgperson, or an auxiliary class.
• The objectclass cannot have any required attributes other than those used by this API: cn, sn, and uid.

The newly created directory entry may be modified with the following restrictions:

• The uid attribute must not be changed.

Other attributes can be changed. For example, the cn and sn attributes can be changed to contain the user's full name and last name respectively, and other attributes, such as telephonenumber, can be added to the entry.

If the validation list users are to coexist with other users defined in the directory server, consider creating a separate directory subtree to contain validation list users. If multiple validation lists are being copied to the directory server, you may want to use a separate subtree for each validation list. If the validation list is being copied to initially populate the directory, there is no reason to put the validation list users in a separate subtree.

In either case, copy the validation list users to a location where they can be used by the proper applications. For example, if you have existing applications using LDAP authentication with users located in the subtree cn=users,o=my company, you may want to create a subtree named cn=http users,cn=users,o=my company. Alternatively, you could create a subtree named cn=http users,o=my company, and reconfigure your applications to look under o=my company, which will include users located in both cn=http users,o=my company and cn=users,o=my company. Other configurations are possible as well.

Placing validation list users in a separate subtree(s) has the following benefits:

• If different validation lists are used by different applications, the same sets of users are easily carried over to LDAP authentication by configuring the applications to use the appropriate directory subtree, for example: cn=application 1 users,o=my company or cn=application 2 users,o=my company. You may be able to configure the application to use groups for access control and define dynamic groups (groupOfUrls) with a group member URL that contains only entries from a specific subtree:

     memberUrl: ldap:///cn=application%201%20users,o=my%20company
  

  Where %20 represents the space character (ASCII 0x20) in a URL.
  
  
• Use of different subtrees makes it easier to manage conflicts between users from different validation lists and between users from validation lists and existing LDAP users that have the same uid value. LDAP authentication typically requires that exactly one entry match a given user name. Placing entries in different subtrees makes it easier to determine where the conflicting entries came from and to delete the proper entry if necessary.

See Examples for examples of calling this API from the command line.

Authorities and Locks

Validation List Object

*CHG

Validation List Object Library

*EXECUTE

Directory server authorities

The bind distinguished name must have authority to add entries beneath the parent distinguished name.

Required Parameter Group

Qualified validation list name The name of the validation list and the library in which it resides. The first 10 characters specify the validation list name and the second 10 characters specify the library.

Bind distinguished name Specifies the distinguished name used to authenticate to the directory server. This parameter is specified in the default job CCSID.

Length of bind distinguished name The length, in bytes, of the bind distinguished name parameter. The following special value may be specified:

Bind password Specifies the password for bind distinguished name. This parameter is specified in the default job CCSID.

Length of bind password The length, in bytes, of the bind password parameter. The following special value may be specified:

Parent distinguished name Specifies the parent distinguished name of the LDAP objects to be created. This parameter is specified in the default job CCSID.

Length of parent distinguished name The length, in bytes, of the parent distinguished name parameter. The following special value may be specified:

Additional objectclass name Specifies the name of an objectclass to be used when creating new directory entries. Created entries will use this objectclass as well as inetorgperson, organizationalPerson, person, and top. To use only the default objectclass, inetorgperson, specify a single null byte for this parameter and a length of 0. This parameter is specified in the default job CCSID.

Length of additional objectclass name The length, in bytes, of the additional objectclass name parameter. The following special value may be specified:

Error code The structure in which to return error information. For the format of the structure, see Error Code Parameter.

Optional Parameter Group

Alternate CCSID Specifies the CCSID to be used for validation list entries which do not have a valid CCSID value. The following values may be used:

-1	Report an error for validation list entries that do not have a valid CCSID value and continue with the next entry
0	Use the default job CCSID for entries that do not have a valid CCSID value
CCSID	Use the specified CCSID for entries that do not have a valid CCSID value

If this parameter is not specified, the default value is -1.

Entry Exists Action Specifies the action to take when a directory entry corresponding to a validation list entry already exists. The following values may be used:

'M'	Put a message in the job log identifying each entry that already exists in the directory. The existing directory entry will be left unchanged
'U'	Update existing entries to replace the 'userpassword' value with the password from the validation list entry
'I'	Skip the validation list entry and continue processing. No message will be put in the job log and the existing directory entry will be left unchanged

If this parameter is not specified, the default value is 'M'.

Error Messages

The following messages may be sent from this function:

Examples

See Code disclaimer information for information pertaining to code examples.

Basic example

Copy the validation list MYLIB/MYVLDL, authenticating to the directory server as cn=administrator with a password of secret. LDAP objects will be created under cn=http users,o=my company using the default inetorgperson objectclass. The API is called with null-terminated strings.

CALL PGM(QSYS/QGLDCPYVL) PARM('MYVLDL    MYLIB     ' 'cn=administrator' X'00000000'
     'secret' X'00000000' 'cn=http users,o=my company,c=us' X'00000000' '' X'00000000' X'00000000')

Example specifying an alternate CCSID

This example is similar to the first example, except that the Alternate CCSID parameter is used to specify that CCSID 278 be used for validation list entries that do not have valid CCSIDs. The CCSID is specified as a hexadecimal value, where decimal 278 is hexadecimal 116.

CALL PGM(QSYS/QGLDCPYVL) PARM('MYVLDL    MYLIB     ' 'cn=administrator' X'00000000'
     'secret' X'00000000' 'cn=http users,o=my company,c=us' X'00000000' '' X'00000000'
     X'00000000' X'00000116')

Example to update passwords from the validation list

This example is similar to the first example, except that Entry Exists Action parameter is used to specify that the password for existing entries be updated from the validation list. The Alternate CCSID parameter is set to use the job CCSID.

CALL PGM(QSYS/QGLDCPYVL) PARM('MYVLDL    MYLIB     ' 'cn=administrator' X'00000000'
     'secret' X'00000000' 'cn=http users,o=my company,c=us' X'00000000' '' X'00000000'
     X'00000000' X'00000000' 'U')