Overview  Package   Class  Use  Tree  Deprecated  Index  Help 
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.ebasetech.xi.services
Class LdapServices2

java.lang.Object
  extended by com.ebasetech.xi.services.LdapServices2

public class LdapServices2
extends java.lang.Object

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

Constructor Summary
LdapServices2()
           
 
Method Summary
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

LdapServices2

public LdapServices2()
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, 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)
Overview  Package   Class  Use  Tree  Deprecated  Index  Help 
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD