SetLDAPAuthentication

Description

Sets a user for LDAP authentication. More specifically, this method sets the user account AuthenticationMode to LDAP_AUTHENTICATION, which authenticates against an LDAP server.

Optionally, configures the HCL Compass to LDAP mapping correlation. The schema repository must be configured with an LDAP server location. Depending on the LDAP configuration status of the database set and whether the LDAP login name is supplied the method also copies the LDAP mapping attribute into the HCL Compass mapping field.

All user databases in a HCL Compass database set must be updated from the master schema repository before a user can log in to a user database using LDAP authentication (for user updates use the UpgradeInfo method of the User Object, or alternately, for all subscribed users, use the UpgradeMasterUserInfo method of the Database Object). See Upgrading user information from a schema repository to a user database for more information.

The method fails if the mapping field value is not unique across enabled LDAP users already in the database. It also fails if an LDAP error occurs while attempting to copy over the LDAP mapping attribute into the HCL Compass mapping field.

Setting the AuthenticationMode for a user to LDAP_AUTHENTICATION sets the HCL Compass user account password in the HCL Compass database to a special value which indicates that the user is configured for LDAP authentication. This prevents earlier HCL Compass clients from being able to login using HCL Compass authentication, rather than the desired LDAP authentication.

Marking a user as having an AuthenticationMode of LDAP_AUTHENTICATION is not enough to enable a user to be able to login using their LDAP account name and password. The HCL Compass user record must also be adjusted so that the user's LDAP mapping attribute value is stored in the HCL Compass user mapping field (see the installutil setcqldapmap command). The SetLDAPAuthentication method copies over the user's LDAP mapping attribute value, if the following conditions are met:

the database set is fully configured for LDAP authentication using the installutil LDAP subcommands and the LDAP connection is working
the setcqldapmap configuration does not use the %login% shortcut
the SetLDAPAuthentication method is supplied with a non-null ldap_login_name string

If these conditions are met, then the SetLDAPAuthentication method copies over the LDAP mapping attribute value and stores it in the user's HCL Compass mapping field. The user is then fully configured for LDAP_AUTHENTICATION and is able to log in to the desired HCL Compass user database once the Administrator updates the user database from the master schema repository.

If one or more of the above conditions is not met, then the SetLDAPAuthentication method does not copy the LDAP mapping attribute into the HCL Compass mapping field. This is not an error condition. In particular, you can use the SetLDAPAuthentication method with the ldap_login_name argument set to a null string value (""). This allows an administrator to set HCL Compass users to be LDAP authenticated users without requiring the administrator to supply the user LDAP login names. The LDAP mapping attribute will not be copied into the HCL Compass mapping field in this case. This requires an Administrator to manually store the correct LDAP mapping attribute into the HCL Compass mapping field (for example, user's e-mail). The user login will fail until the correct HCL Compass field is updated with the required mapping information.

Using the SetLDAPAuthentication method without a valid LDAP login name requires a user to have the correct HCL Compass LDAP mapping attribute set (for example, user's e-mail). The user login will fail until the correct HCL Compass field is updated with the required mapping information.

Note: The caller of this method must have Administrator privileges (that is, the UserPrivilegeMaskType value, USER_ADMIN) to set this value. HCL Compass prevents USER_ADMIN privileged users from setting their own AuthenticationMode.

Note: This method became available in version 2003.06.14.

Syntax

VBScript

user.SetLDAPAuthentication(LDAP_login_name)

Perl

user->SetLDAPAuthentication(LDAP_login_name);

Identifier: Description
user: A User object.
LDAP_login_name: A String containing the LDAP user login name (for example, myUniqueName@hcl.com.)
Return value: None on success, else an exception (for example, if the LDAP_login_name value is not found in the LDAP server.

Examples

VBScript

'set the user authentication mode to ldap:
   Dim cquser2 ' a user object 
   Dim ldap_login   
   Dim mode ' the user authentication mode
   ldap_login = "yourusername@us.hcl.com"
   StdOut "Setting ldap authentication for " & cquser2.name & vbCrLf
   cquser2.SetLDAPAuthentication (ldap_login)
   ' verify the user authentication mode:  
   StdOut "Getting authentication mode for user " & cquser2.name & vbCrLf
   mode = cquser2.GetAuthenticationMode
   StdOut "user mode: " & CStr(mode) & vbCrLf

Perl

# Check the user's authentication mode. 
# If it's not LDAP authentication, change it to be such
sub Enforce_LDAP_Authentication_On_User
{
	my($user, $LDAP_login) = @_;
	$authentication = $user->GetAuthenticationMode();
	if ($authentication == $CQPerlExt::CQ_LDAP_AUTHENTICATION)
	{
		$auth_s = "LDAP Authenticated";
		print "User's authentication mode is $auth_s. No Changes needed.\n";
		return 0;
	}		
	else 
	{
		$auth_s = "CQ Authenticated";
		eval{$user->SetLDAPAuthentication($LDAP_login);};
		if ($@)
		{
			print "Couldnt run User->SetLDAPAuthentication.  Error: $@\n";
			die;
		}
		print "LDAP Authentication set.\n";
		return 1;
	}
}