New V5R2 Enhancements

Copy Validation List To Directory (QGLDCPYVL) API

 What does the QGLDCPYVL API do?

If you are currently using HTTP server or have used it in the past, you may have created validation lists to store internet users and their passwords. As you move to WebSphere Application Server, Portal Server, and other applications that support LDAP authentication, you may want to continue using these existing internet users and their passwords. This can be done using the callable program, QGLDCPYVL.

QGLDCPYVL will read entries from a validation list and create corresponding LDAP objects in the local directory server. The objects will be skeletal inetOrgPerson entries with a userPassword attribute that contains a copy of the password information from the validation list entry. You can decide how and when this API is called. You might use it as a one time operation for a validation list that will not be changing, or as a scheduled job to update the directory server to reflect new validation list entries.

Once copied to the directory server, the users can be used for LDAP authentication, and if you no longer need the validation list, the validation list can be deleted. The API creates inetorgperson entries in the local servers as follows:

• The internet user name is copied into the uid, cn, and sn attributes.
• The user comments are copied into the description attribute.
• The one-way encrypted password data is copied into the userpassword attribute.

Once the directory entry has been created, you can edit the cn and sn attribute values as well as any of the other attributes allowed by the inetorgperson object class.

In addition to being used with HTTP applications, the QGLDCPYVL API can be used to assist you in migrating any application that uses validation lists for user authentication to use LDAP authentication.

 How do I get the QGLDCPYVL API?

The QGLDCPYVL API is available in V5R3 as new function PTF 5722SS1-SI16586. The PTF includes both the new API and directory server enhancements required to support using the userpassword data copied from the valadation list.

The PTF includes new English upper case message descriptions. Translated messages are provided in requisite MRI PTFs that are distributed with this PTF.

To install the new PTF, order and install PTF SI16586. Then restart the directory server.

PTF SI18216 provides support for an additional parameter, Alternate CCSID. Refer to the QGLDCPYVL API documentation for further information.

 QGLDCPYVL API documentation

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 copies only those validation list entries which do not correspond to existing directory server entries and does not modify any directory server entries that correspond to validation list entries.

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. The API copies only those validation list entries which do not correspond to existing directory server objects.

Notes:

1. When copying a validation list for which a corresponding directory entry already exists, informational message GLD023B, Object for user &1 already exists, is 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. Existing directory entries are not 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)

a directory entry would be created that looks like:

   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

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

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

  STRTRC SSNID(COPYVLDL) JOBTRCTYPE(*TRCTYPE) TRCTYPE((*DIRSRV *ERROR))
  CALL QGLDCPYVL PARM(...)
  ENDTRC SSNID(COPYVLDL) DTALIB(QTEMP) PRTTRC(*YES)