Copy Validation List To Directory (QGLDCPYVL) API
Required Parameter Group:
1 | Qualified validation list name | Input | Char(20) |
2 | Bind distinguished name | Input | Char(*) |
3 | Length of bind distinguished name | Input | Binary(4) |
4 | Bind password | Input | Char(*) |
5 | Length of bind password | Input | Binary(4) |
6 | Parent distinguished name | Input | Char(*) |
7 | Length of parent distinguished name | Input | Binary(4) |
8 | Additional objectclass name | Input | Char(*) |
9 | Length of additional objectclass name | Input | Binary(4) |
10 | Error code | Input/Output | Char(*) |
Optional Parameter Group 1:
11 | Alternate CCSID | Input | Binary(4) |
12 | Entry Exists Action | Input | Char(1) |
Optional Parameter Group 2:
Default Public Authority: *USE
Threadsafe: Yes
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:
- 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.
- 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.
- 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:
13 | Server Instance | Input | Char(8) |
Attribute | Value |
relative distinguished name | uid=<user name> |
objectclass | additional objectclass specified on API call plus inetOrgPerson, organizationalPerson, person, top |
uid | <user name> |
cn | <user name> |
sn | <user name> |
description | <comments> |
userpassword | {VLDL}<one way encrypted password data from validation list entry> |
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
orcn=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.
The following special value may be specified:
*CURLIB | The job's current library |
*LIBL | The library list |
Bind distinguished name Specifies the distinguished name used to authenticate to the directory server. This parameter is specified in the default job CCSID. The following special value may be specified:
*CURUSR | Authenticate to the server using the current user profile. *CURUSR must also be specified for the bind password. |
Length of bind distinguished name
The length, in bytes, of the bind distinguished name
parameter.
The following special value may be specified:
0 | The bind distinguished name is a null-terminated string. |
Bind password Specifies the password for bind distinguished name. This parameter is specified in the default job CCSID. The following special value may be specified:
*CURUSR | Authenticate to the server using the current user profile. *CURUSR must also be specified for the bind distinguished name. |
Length of bind password
The length, in bytes, of the bind password
parameter.
The following special value may be specified:
0 | The bind password is a null-terminated string. |
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:
0 | The parent distinguished name is a null-terminated string. |
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:
0 | The additional objectclass name is a null-terminated string. |
Error code The structure in which to return error information. For the format of the structure, see Error code parameter.
Optional Parameter Group
Alternate CCSIDSpecifies 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'.
Server Instance Specifies the name of the directory server instance to which validation list entries are to be copied.
If this parameter is not specified, the default value is the 'QUSRDIR' server instance.
Error Messages
The following messages may be sent from this function:
Message ID | Error Message Text |
---|---|
GLD0215 | Directory server not configured. |
GLD0237 | Directory Server is not started. |
GLD0238 | Bind distinguished name or password is not correct. |
GLD0239 | Parent object does not exist. |
GLD023A | Not authorized to directory object. |
GLD023C | Schema violation for entry '&1'. |
GLD023F | Error &1 returned by API &2. |
GLD0240 | LDAP error code &1 returned by API &2. |
GLD0241 | Errors occurred adding entries. |
GLD0242 | Error with &1 value in validation list entry. |
GLD0502 | Error &1 returned by API &2. |
CPF3CF1 | Error code parameter not valid. |
CPF3CF2 | Error(s) occurred during running of &1 API. |
CPF3C36 | Number of parameters, &1, entered for this parameter was not valid. |
CPF3C3A | Value for parameter &2 for API &1 not valid. |
CPF9801 | Object &1 in &2 type &3 not found. |
CPF9802 | Not authorized to object &1 in &2 type &3. |
Object &1 in &2 type &3 damaged. | |
CPFB617 | CCSID not valid. |
Examples
Note: By using the code examples, you agree to the terms of the Code license and disclaimer information.
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')
API introduced: V5R4
[ Back to top | LDAP APIs | APIs by category ]