Package 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 Description
    LdapServices()  

  • Method Summary

    Modifier and Type Method 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 Details

    • LdapServices

      public LdapServices()

  • Method Details

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