The Aspire LDAP Group Expansion component provides external components with methods to allow them to bind, authenticate, and search over an LDAP server. The component can also be used as a pipeline stage, adding group information for a given user from the LDAP server to the pipeline job.
This component supports the AspireLdap.java interface to allow other components to access LDAP services, and handles all of the communication with the customer's LDAP server using Java API.
If the LDAP server is Microsoft's Active directory, this component can be configured to use native code calls to perform group expansion. This option only works if the Aspire server is running a Windows operating system (32 or 64 bit). In certain cases, generic LDAP calls seem to fail after a certain period of time, and native calls may be more reliable.
This component is based on the Simple Group Expander
LDAP Group Expansion | |
---|---|
Factory Name | com.searchtechnologies.aspire:aspire-ldap |
subType | default |
Inputs | A Job containing a group expansion request |
Outputs | A Job containing a group expansion result |
Configuration
Element | Type | Default | Description |
---|---|---|---|
server | string | LDAP server host address. Example: ldap//10.10.44.82:389. NOTE: if you're using the native AD group expansion, the host address protocol must be in upper case - LDAP://10.10.44.82:389 | |
protocol | string | LDAP server protocol. | |
contextFactory | string | com.sun.jndi.ldap.LdapCtxFactory | The java class to use as the context factory when connecting. |
authentication | string | anonymous | Authentication type used for any LDAP request. Options are 'none', 'simple' and 'DIGEST-MD5'. |
user | string | N/A | Username used to authenticate against the given LDAP server. If 'none' authentication type was selected, you can ignore this. |
password | string | N/A | Password used to authenticate against the given LDAP server. If 'none' authentication type was selected, you can ignore this. |
searchBase | string | dc=search,dc=local | Base for directory searches. Normally this is the domain of the LDAP server. |
pageSize (2.0.3 Release) | int | 1000 | The page size of the search query (max 1000) |
nativeADExpansion | boolean | false | For AD servers, invoke native code to perform group expansion. This may provide more reliable operation when expanding groups from AD servers. This option will be ignored if the Aspire server is not running a Windows operating system. NOTE: if you're using the native AD group expansion, the host address protocol must be in upper case - LDAP://10.10.44.82:389 |
groupFilter | string | (&(objectClass=group)(member=%s)) | The LDAP query to get the groups a user belongs to. |
userFilter | string | (|(cn=%s)(samaccountname=%s)) | The LDAP query filter used to find users when a distinguished name is not available. The default filter is for Active Directory. |
referral | string | follow | LDAP search referral type. |
groupNameAttribute | string | cn | The LDAP attribute that holds the group name to be returned. |
lowerCase | boolean | false | Tells if group names retrieved from LDAP should be changed to lower case. |
readTimeout | int | 5000 (=5s) | Read timeout in ms. |
connectTimeout | int | 5000 (=5s) | Connection timeout in ms. |
connectionPool | boolean | true | Indicates if a connection pool to the LDAP server should be used. |
cacheTimeout | long | 30000 (30 min) | Max time in milliseconds group expansion information is kept in the cache. |
maxUserCacheSize | int | 2000 | Max size of user cache. If this size is ever reached, a number of elements are dropped from the cache to make room for new users. The user cache stores {username, userDN} pairs only. No group information. |
specialGroups | XML | List of group expansion special groups that need to be added to the LDAP group list (e.g. NT AUTHORITY\Authenticated Users). |
Group Expansion
When used as a pipeline stage, this component receives a group expansion request via the AspireObject attached to a pipeline Job. The component extracts the username from the request and uses this to query the LDAP server using the query string given in the groupFilter configuration tag. Group names will be extracted from the attribute given in the groupNameAttribute configuration tag. These will then be added to the group expansion response, with the source marked as ldap.
LDAP Services to other Components
This component can provide other components with access to common LDAP functions. It achieves this by implementing the AspireLdap.java interface which provides methods to bind, lookUp, search and determine if an item hasEntry in the server.
Components wishing to access this functionality should main a service tracker to this component, get an instance an then call the appropriate method. See here for further details
Example Configurations
<component name="LdapGroupExpander" subType="groupExpander" factoryName="aspire-ldap"> <server>ldap://10.10.44.82:389</server> <authentication>simple</authentication> <user>contoso\carolt</user> <password>pass@word1</password> <searchBase>dc=contoso, dc=com</searchBase> <pageSize>1000</pageSize> <specialGroups> <group>NT AUTHORITY\Authenticated Users</group> </specialGroups> </component>