com.ebasetech.xi.services

Class LdapServices

java.lang.Object

com.ebasetech.xi.services.LdapServices

All Implemented Interfaces:

java.io.Serializable

public class LdapServices
extends java.lang.Object
implements java.io.Serializable

LdapServices provides static methods that provide authentication and search methods against an Ldap Registry. Most of the methods provided use the connection properties defined in the XIldap.properties file.

Since:

V4.4

See Also:

Serialized Form

Constructor Summary

Constructors

Constructor and Description
LdapServices()

Method Summary

Modifier and Type	Method and Description
static boolean	authenticate(java.lang.String userName, java.lang.String password) Authenticates the supplied user/password combination against the Ldap Registry identified by properties in the XIldap.properties file file using simple authentication (user/password check).
static boolean	authenticate(java.lang.String userName, java.lang.String password, java.lang.String baseDistinguishedName, java.lang.String userKeyAttributeName, boolean removeDomainNameFromUser) Authenticates the supplied user/password combination against the Ldap Registry identified by properties in the XIldap.properties file file using simple authentication (user/password check).
static java.lang.String[]	getADGroups(java.lang.String userName) Returns all Active Directory group names associated with a user including nested groups, using the Active Directory tokenGroups attribute to obtain this information.
static java.lang.String[]	getADGroups(java.lang.String userName, java.lang.String baseDistinguishedName, boolean removeDomainNameFromUser) Returns all Active Directory group names associated with a user including nested groups, using the Active Directory tokenGroups attribute to obtain this information.
static javax.naming.directory.DirContext	getLdapContext() Returns an javax.naming.directory.InitialDirContext object that can be used for Ldap queries.
static javax.naming.directory.DirContext	getLdapContext(java.util.Map props) Returns an javax.naming.directory.InitialDirContext object using the supplied properties.
static java.lang.String[]	getUserAttribute(java.lang.String userName, java.lang.String attributeName) Returns a single attribute associated with a user from the Ldap Registry identified by properties in the XIldap.properties file file.
static java.lang.String[]	getUserAttribute(java.lang.String userName, java.lang.String attributeName, java.lang.String baseDistinguishedName, java.lang.String userKeyAttributeName, boolean removeDomainNameFromUser) Returns a single attribute associated with a user from the Ldap Registry identified by properties in the XIldap.properties file file.
static java.util.Map<java.lang.String,java.lang.String[]>	getUserAttributes(java.lang.String userName) Returns all attributes associated with a user from the Ldap Registry identified by properties in the XIldap.properties file file.
static java.util.Map<java.lang.String,java.lang.String[]>	getUserAttributes(java.lang.String userName, java.lang.String baseDistinguishedName, java.lang.String userKeyAttributeName, boolean removeDomainNameFromUser) Returns all attributes associated with a user from the Ldap Registry identified by properties in the XIldap.properties file file.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

LdapServices

public LdapServices()

Method Detail

authenticate

public static boolean authenticate(java.lang.String userName,
                                   java.lang.String password)
                            throws com.ebasetech.xi.exceptions.FormRuntimeException

Authenticates the supplied user/password combination against the Ldap Registry identified by properties in the XIldap.properties file file using simple authentication (user/password check).

This method works as follows:

1. Connects to the Ldap Registry using the user identified by properties Ldap.BindDistinguishedName and Ldap.BindPassword in XIldap.properties file. If these properties are missing, attempts to bind anonymously.
2. Searches the registry for the user name starting from the location identified by property Ldap.BaseDistinguishedName in XIldap.properties file and obtains the full distinguished name (DN) identifying the user. Parameter userKeyAttributeName in XIldap.properties file is used to build the search string.
3. Connects to the registry using this DN and the supplied password.

Parameters:

userName - the user name. Any domain in the user name is removed prior to authenticating e.g. myuser@domain or domain\myuser are changed to myuser.

password - user's password

Returns:

true if authentication is successful, false if userName or password is missing, the user cannot be found in the registry or the password is incorrect

Throws:

com.ebasetech.xi.exceptions.FormRuntimeException - if any error occurs, most likely caused by incorrect properties in the XIldap.properties file file

Since:

V4.4

See Also:

authenticate(String, String, String, String, boolean)

authenticate

public static boolean authenticate(java.lang.String userName,
                                   java.lang.String password,
                                   java.lang.String baseDistinguishedName,
                                   java.lang.String userKeyAttributeName,
                                   boolean removeDomainNameFromUser)
                            throws com.ebasetech.xi.exceptions.FormRuntimeException

Authenticates the supplied user/password combination against the Ldap Registry identified by properties in the XIldap.properties file file using simple authentication (user/password check).

This method works as follows:

1. Connects to the Ldap Registry using the user identified by properties Ldap.BindDistinguishedName and Ldap.BindPassword in XIldap.properties file. If these properties are missing, attempts to bind anonymously.
2. Searches the registry for the user name starting from the location identified by parameter baseDistinguishedName and obtains the full distinguished name (DN) identifying the user. Parameter userKeyAttributeName is used to build the search string.
3. Connects to the registry using this DN and the supplied password.

Javascript example:

 var root = "OU=Ebase Users and Groups,DC=ebasetech,DC=com";
 var userAttr = "sAMAccountName";
 var logonOk = LdapServices.authenticate(fields.USER.value, fields.PASSWORD.value, root, userAttr, false);
 if (logonOk) 
   event.owner.addWarningMessage("Logon OK");
 else
   event.owner.addErrorMessage("Logon failed");
 

Parameters:

userName - the user name. Any domain in the user name is removed if parameter removeDomainNameFromUser is true.

password - user's password

baseDistinguishedName - the distinguished name (DN) that is used as the search root for the user

userKeyAttributeName - the user attribute used to search the registry for the user data, this should uniquely identify the user

removeDomainNameFromUser - if true, any domain in the user name is removed prior to authenticating e.g. myuser@domain or domain\myuser are changed to myuser prior to authenticating

Returns:

true if authentication is successful, false if userName or password is missing, the user cannot be found in the registry or the password is incorrect

Throws:

com.ebasetech.xi.exceptions.FormRuntimeException - if any error occurs

Since:

V4.4

See Also:

authenticate(String, String)

getLdapContext

public static javax.naming.directory.DirContext getLdapContext()
                                                        throws com.ebasetech.xi.exceptions.FormRuntimeException

Returns an javax.naming.directory.InitialDirContext object that can be used for Ldap queries. Connection properties are contained in the XIldap.properties file file. Note that the context object should be closed after use.

Javascript example:

 var ctx;
 try {
   ctx = LdapServices.getLdapContext();
   ctx.search(...); 
 }
 finally {
  ctx.close();
 }
 

Returns:

javax.naming.directory.InitialDirContext

Throws:

com.ebasetech.xi.exceptions.FormRuntimeException - if any error occurs

Since:

V4.4

getLdapContext

public static javax.naming.directory.DirContext getLdapContext(java.util.Map props)
                                                        throws javax.naming.NamingException

Returns an javax.naming.directory.InitialDirContext object using the supplied properties. Note that the context object should be closed after use.

Javascript example:

 importPackage(javax.naming);
 var props = {};
 props[Context.INITIAL_CONTEXT_FACTORY] = "com.sun.jndi.ldap.LdapCtxFactory";
 props[Context.PROVIDER_URL] = "ldap://192.168.0.33:389";
 props[Context.SECURITY_PRINCIPAL] = "Administrator@ebase";
 props[Context.SECURITY_CREDENTIALS] = "*******";
 props[Context.SECURITY_AUTHENTICATION] = "simple";
 var ctx;
 try {
   ctx = LdapServices.getLdapContext(props);
   ctx.search(...); 
 }
 finally {
   ctx.close();
 }
 

Returns:

directory context

Throws:

com.ebasetech.xi.exceptions.FormRuntimeException - if an authentication error occurs

javax.naming.NamingException - if any other error occurs

Since:

V4.4

getUserAttributes

public static java.util.Map<java.lang.String,java.lang.String[]> getUserAttributes(java.lang.String userName)

Returns all attributes associated with a user from the Ldap Registry identified by properties in the XIldap.properties file file.

The returned Map contains one entry for each unique attribute name where the key is the property name and the value is an array of property values. When a property only occurs once, this array will only contain a single value.

This method works as follows:

1. Connects to the Ldap Registry using the user identified by properties Ldap.BindDistinguishedName and Ldap.BindPassword in XIldap.properties file. If these properties are missing, attempts to bind anonymously.
2. Searches the registry for the user name starting from the location identified by property Ldap.BaseDistinguishedName in XIldap.properties file and obtains the full distinguished name (DN) identifying the user. Parameter userKeyAttributeName in XIldap.properties file is used to build the search string.
3. Returns all attributes for the DN.

Javascript example:

 var attrs = LdapServices.getUserAttributes(fields.USER.value);
 for (var attrid in attrs)
 {
   var attrValues = attrs[attrid];
   log ("Attribute: " + attrid);
   for each (var attrValue in attrValues)
   {
     log(" value: " + attrValue); 
   }
 }
 

Parameters:

userName - the user name. Any domain in the user name is removed prior to searching e.g. myuser@domain or domain\myuser are changed to myuser.

Returns:

a map of all attributes (with Javascript, this will be returned as a Javascript Object).

Throws:

com.ebasetech.xi.exceptions.FormRuntimeException - if any error occurs

Since:

V4.4

See Also:

getUserAttributes(String, String, String, boolean)

getUserAttributes

public static java.util.Map<java.lang.String,java.lang.String[]> getUserAttributes(java.lang.String userName,
                                                                                   java.lang.String baseDistinguishedName,
                                                                                   java.lang.String userKeyAttributeName,
                                                                                   boolean removeDomainNameFromUser)

Returns all attributes associated with a user from the Ldap Registry identified by properties in the XIldap.properties file file.

The returned Map contains one entry for each unique attribute name where the key is the property name and the value is an array of property values. When a property only occurs once, this array will only contain a single value.

This method works as follows:

1. Connects to the Ldap Registry using the user identified by properties Ldap.BindDistinguishedName and Ldap.BindPassword in XIldap.properties file. If these properties are missing, attempts to bind anonymously.
2. Searches the registry for the user name starting from the location identified by parameter baseDistinguishedName and obtains the full distinguished name (DN) identifying the user. Parameter userKeyAttributeName is used to build the search string.
3. Returns all attributes for the DN.

Javascript example:

 var root = "OU=Ebase Users and Groups,DC=ebasetech,DC=com";
 var userAttr = "sAMAccountName";
 var attrs = LdapServices.getUserAttributes(fields.USER.value, root, userAttr, false);
 for (var attrid in attrs)
 {
   var attrValues = attrs[attrid];
   log ("Attribute: " + attrid);
   for each (var attrValue in attrValues)
   {
     log(" value: " + attrValue); 
   }
 }
 

Parameters:

userName - the user name. Any domain in the user name is removed if parameter removeDomainNameFromUser is true.

baseDistinguishedName - the distinguished name (DN) that is used as the search root for the user

userKeyAttributeName - the user attribute used to search the registry for the user data, this should uniquely identify the user

removeDomainNameFromUser - if true, any domain in the user name is removed prior to authenticating e.g. myuser@domain or domain\myuser are changed to myuser prior to the search

Returns:

a map of all attributes (with Javascript, this will be returned as a Javascript Object).

Throws:

com.ebasetech.xi.exceptions.FormRuntimeException - if any error occurs

Since:

V4.4

See Also:

getUserAttributes(String)

getUserAttribute

public static java.lang.String[] getUserAttribute(java.lang.String userName,
                                                  java.lang.String attributeName)

Returns a single attribute associated with a user from the Ldap Registry identified by properties in the XIldap.properties file file.

The returned array contains one value for each occurrence of the property in the registry. When a property only occurs once, this array will only contain a single value.

This method works in the same way as getUserAttributes(String) except that values for only one attribute are returned.

Javascript example:

 var attrs = LdapServices.getUserAttribute(system.securityManager.userName, "mail");
 if (attrs.length > 0)
   var email = attrs[0];
 

Parameters:

userName - the user name. Any domain in the user name is removed prior to searching e.g. myuser@domain or domain\myuser are changed to myuser.

attributeName - name of the attribute

Returns:

an array of values for the attribute

Throws:

com.ebasetech.xi.exceptions.FormRuntimeException - if any error occurs

Since:

V4.4

See Also:

getUserAttribute(String, String, String, String, boolean)

getUserAttribute

public static java.lang.String[] getUserAttribute(java.lang.String userName,
                                                  java.lang.String attributeName,
                                                  java.lang.String baseDistinguishedName,
                                                  java.lang.String userKeyAttributeName,
                                                  boolean removeDomainNameFromUser)

Returns a single attribute associated with a user from the Ldap Registry identified by properties in the XIldap.properties file file.

The returned array contains one value for each occurrence of the property in the registry. When a property only occurs once, this array will only contain a single value.

This method works in the same way as getUserAttributes(String, String, String, boolean) except that values for only one attribute are returned.

Javascript example:

 var root = "OU=Ebase Users and Groups,DC=ebasetech,DC=com";
 var userAttr = "sAMAccountName";
 var attrs = LdapServices.getUserAttribute(system.securityManager.userName, "mail", root, userAttr, false);
 if (attrs.length > 0)
   var email = attrs[0];
 

Parameters:

userName - the user name. Any domain in the user name is removed if parameter removeDomainNameFromUser is true.

attributeName - name of the attribute

baseDistinguishedName - the distinguished name (DN) that is used as the search root for the user

userKeyAttributeName - the user attribute used to search the registry for the user data, this should uniquely identify the user

removeDomainNameFromUser - if true, any domain in the user name is removed prior to authenticating

Returns:

an array of values for the attribute

Throws:

com.ebasetech.xi.exceptions.FormRuntimeException - if any error occurs

Since:

V4.4

See Also:

getUserAttribute(String, String)

getADGroups

public static java.lang.String[] getADGroups(java.lang.String userName)
                                      throws com.ebasetech.xi.exceptions.FormRuntimeException

Returns all Active Directory group names associated with a user including nested groups, using the Active Directory tokenGroups attribute to obtain this information. Connection parameters for the Active Directory system are taken from the XIldap.properties file properties file. In this file, property Ldap.BaseDistinguishedName should be set to a directory location that includes all users and groups.

This method works as follows:

1. Connects to the Ldap Registry using the user identified by properties Ldap.BindDistinguishedName and Ldap.BindPassword in XIldap.properties file. If these properties are missing, attempts to bind anonymously.
2. Searches the registry for the user name starting from the location identified by property Ldap.BaseDistinguishedName in XIldap.properties file and obtains the full distinguished name (DN) identifying the user. Parameter userKeyAttributeName in XIldap.properties file is used to build the search string.
3. Obtains a list of groups for the user by searching for the special Active Directory tokenGroups attribute within the user DN.
4. Searches for each group in turn starting from the location identified by property Ldap.BaseDistinguishedName in XIldap.properties file.

Javascript example:

 var groups = LdapServices.getADGroups(fields.USER.value);
 for each (var group in groups)
 {
   tables.GROUPS.insertRow();
   tables.GROUPS.NAME.value = group;
 }
 

Parameters:

userName - the user name. Any domain in the user name is removed prior to searching e.g. myuser@domain or domain\myuser are changed to myuser.

Returns:

an array of group names for the user

Throws:

com.ebasetech.xi.exceptions.FormRuntimeException - if any error occurs

Since:

V4.4

See Also:

getADGroups(String, String, boolean)

getADGroups

public static java.lang.String[] getADGroups(java.lang.String userName,
                                             java.lang.String baseDistinguishedName,
                                             boolean removeDomainNameFromUser)
                                      throws com.ebasetech.xi.exceptions.FormRuntimeException

Returns all Active Directory group names associated with a user including nested groups, using the Active Directory tokenGroups attribute to obtain this information. Connection parameters for the Active Directory system are taken from the XIldap.properties file properties file.

This method works as follows:

1. Connects to the Ldap Registry using the user identified by properties Ldap.BindDistinguishedName and Ldap.BindPassword in XIldap.properties file. If these properties are missing, attempts to bind anonymously.
2. Searches the registry for the user name starting from the location identified by parameter baseDistinguishedName and obtains the full distinguished name (DN) identifying the user.
3. Obtains a list of groups for the user by searching for the special Active Directory tokenGroups attribute within the user DN.
4. Searches for each group in turn starting from the location identified by parameter baseDistinguishedName.

Javascript example:

 var root = "DC=ebasetech,DC=com";
 var groups = LdapServices.getADGroups(fields.USER.value, root, true);
 for each (var group in groups)
 {
   tables.GROUPS.insertRow();
   tables.GROUPS.NAME.value = group;
 }
 

Parameters:

userName - the user name. Any domain in the user name is removed if parameter removeDomainNameFromUser is true.

baseDistinguishedName - the distinguished name (DN) that is used as the search root for the user and groups

removeDomainNameFromUser - if true, any domain in the user name is removed prior to authenticating

Returns:

an array of group names for the user

Throws:

com.ebasetech.xi.exceptions.FormRuntimeException - if any error occurs

Since:

V4.4

See Also:

getADGroups(String)