Configuring LDAP Based
Security
Configuring the LDAP login module
Configuring Designer Authentication
Separately
Set up the LDAP attributes file
Accessing LDAP attributes from a form
See also: Ebase Security Authentication
!! The techniques described
in this document are deprecated. Instead use Xi Logon Exit to connect to an LDAP
Registry and extract any user attributes.
This document describes the options available to connect to an LDAP user registry such as Microsoft Active Directory, Oracle Internet Directory etc, and describes how these options are configured. Authentication (user signon) can be directed to an LDAP registry and this authentication can be applied to either runtime users or designer users or both of these. See Configuring Authentication. Once a user has been authenticated, the system attempts to extract the names of Ebase security roles for the user, which will then be used to evaluate any subsequent authorization requests.
Optionally, for runtime users, Ebase Xi provides an additional facility to extract any user-level attributes from the LDAP user registry e.g. user name, email, phone number, manager etc, and use these attributes as part of form processing. See Configuring User Attributes.
This is configured using a JAAS login configuration file ebaselogin.config which for Tomcat systems is distributed in UfsServer/conf. Please note that this file may have been relocated as part of the installation process.
There are two LDAP login modules:
1. LDAPLoginModule
The LDAPLoginModule performs
authentication directly on the user id and password supplied by the user. In a
standard LDAP set up without any additional security layer such as SASL
mechanisms that provide identity management so that user ids can be mapped to DNs, LDAP would require the full DN of the object to
authenticate. Therefore, using this login module, the user will be required to
log on using their full DN.
2. LDAPLoginModule2
The LDAPLoginModule2 removes the need for the user to
supply a full DN by first binding against an administrator user (configured in server LDAP
properties), performing a lookup in the directory against the supplied user
id to retrieve the full DN of the user. If a DN exists, a bind is performed
with the supplied password. If this is successful, the user will be
authenticated.
To use LDAP authentication, change the ebaselogin.config file, for example to use the LDAPLoginModule2 login module:
Ebase
{
com.ebasetech.ufs.security.authentication.LDAPLoginModule2
REQUIRED debug=true userManagerRoles=false;
};
debug can be true or false. When true, additional messages are written to the system log.
UserManagerRoles can be true or false. This option is discussed in more detail in configuring authorization.
· true: take security role names from the LDAP registry
· false: take security role names from the configured UserManager component
Click here for LDAP login module implementation details.
The following server properties are configured using the Server
Administration Application – Security Properties:
|
Parameter |
Description |
Default |
|
ldap.registryHost |
Hostname or IP address of the LDAP registry system. This
is a required parameter for all LDAP options. |
None |
|
ldap.registryPort |
Port used by the LDAP registry system |
389 |
|
ldap.baseDistinguishedName |
The DN suffix to be applied to all LDAP attribute searches. This will be one or more key=value pairs separated by commas which should be specified in reverse order of the LDAP hierarchy tree, i.e. tree root appears last. This parameter should specify the lowest point in the directory tree which is common for all userid searches e.g. if your registry contains a number of paths containing userid definitions, this parameter should specify a point in the directory that is common for all paths. Ebase attribute searches use subtree scope for directory searches, so the root directory could be specified if necessary. This parameter is not required to perform an LDAP
authentication but is required to read any user-related attributes
including security role names. |
If not specified, no suffix will be used. |
|
ldap.bindDistinguishedName |
The full DN used by Ebase to bind to the repository. This parameter supplies the “userid” for connections to the LDAP Registry. This parameter is not normally required to perform an LDAP authentication (userid/password check) but is usually required to read any user-related attributes including security role names. |
If not specified, Ebase will bind as 'Anonymous'. Note
that anonymous binding is only supported by LDAP V3 systems. |
|
ldap.bindPassword |
The password to be used with ldap.bindDistinguishedName |
None |
|
ldap.userKeyAttributeName |
The user attribute Ebase uses to search the registry for user
data. This attribute should uniquely identify the user. This parameter
is not required to perform an LDAP authentication but is
required to read any user-related attributes including security role names. |
cn |
|
ldap.userRoleAttributeName |
The attribute that contains a comma delimited list of
Ebase security roles to be associated with the user (Note: this parameter is
only applicable to when UserManagerRoles is
specified as false in the LDAP login module)
|
None |
|
ldap.debug |
Set this to true to obtain additional debugging information. It is recommended to do this while initially configuring LDAP. |
false |
|
Ufs.ldapAttributesFileName |
The full path to the LDAP attributes file. This parameter is
only applicable when LDAP attributes have been configured. |
None |
|
ldap.cacheRefreshPeriod |
The number of minutes before Ebase treats cached user
attribute data as stale and performs a refresh from the LDAP registry system.
This parameter is only applicable when LDAP attributes have been configured. |
0 (no refresh takes place) |
Examples:
General (authentication only):
ldap.registryHost=ebt999
General – all LDAP features
ldap.registryHost=ebt103
ldap.baseDistinguishedName=ou=development,o=ebase
ldap.userKeyAttributeName=cn
ldap.userRolettributeName=ebaseRoles
ldap.bindDistinguishedName=xxxxxxxxx
ldap.bindPassword=xxxxx
Ufs.ldapAttributesFileName=../webapps/ufs/preferences/ldap_attributes.xml
ldap.cacheRefreshPeriod=60
ldap.debug=true
Active Directory Example (authentication only):
ldap.registryHost=ebt104
Active Directory Example (security role names maintained in Active
Directory):
ldap.registryHost=ebt999
ldap.baseDistinguishedName=cn=users,dc=ebasetech,dc=com
ldap.userKeyAttributeName=sAMAccountName
ldap.userRolettributeName=ebaseRoles
ldap.bindDistinguishedName=Admin@ebase
ldap.bindPassword=xxxxx
ldap.debug=true
Active Directory Example (Extraction of registry attributes):
ldap.registryHost=ebt999
ldap.baseDistinguishedName=cn=users,dc=ebasetech,dc=com
ldap.userKeyAttributeName=sAMAccountName
ldap.bindDistinguishedName=Admin@ebase
ldap.bindPassword=xxxxx
Ufs.ldapAttributesFileName=../webapps/ufs/preferences/ldap_attributes.xml
ldap.cacheRefreshPeriod=60
ldap.debug=true
A logon exit is responsible for obtaining a userid and password from the end user. The Ebase supplied logon exit does this by displaying a JSP to the user. The supplied logon exit can be replaced if necessary, and the logon JSP can also be configured. See Security Authentication for further details.
Activate the logon exit by checking server property Enable Authentication Of New Users. Note that this parameter acts as the master switch to activate runtime authentication.
When signing on to a Windows domain, Ebase will accept either of the following formats:
userid@domain e.g. paulsmith@finance
domain\userid e.g. finance\paulsmith
In both cases, the id retained by the Ebase system (and
available via the $USER system variable) is just the userid
portion e.g. paulsmith.
An application can check whether a user is authorized to perform a certain function for checking whether the user has the required role. This can be done with Javascript system.securityManager.hasRole(“XYZ) or the FPL hasrole() function. When using LDAP security, the association between a user and security roles can be made in one of two ways that is controlled by the userManagerRoles parameter in the login module configuration file.
userManagerRoles=true
The system attempts to extract security roles for the user from the Ebase security system. To use this option, users must be defined in both the LDAP Registry and the Ebase Security system. The LDAP Registry is used to perform a password check, then the Ebase security system is used to read the roles.
userManagerRoles=false
The system attempts to extract security roles for the user from the LDAP Registry. In this case, server property User Role Attribute Name contains the name of the attribute in the registry containing the role names – it may be necessary to create a new registry attribute to accommodate this. This parameter must contain a comma delimited list of security role names as shown in the following example.
ldap.registryHost=myhost
ldap.baseDistinguishedName=cn=users,dc=ebasetech,dc=com
ldap.userKeyAttributeName=sAMAccountName
ldap.userRoleAttributeName=ebaseRoles
ldap.bindDistinguishedName=xxxxxxx
ldap.bindPassword=xxxxxxx
Note that most LDAP Registries will require the configuration of ldap.bindDistinguishedName and ldap.bindPassword to extract attribute values.
LDAP Registry
cn=Users
sAMAccountName=fsmith
ebaseRoles=BUSINESS_USER, FINANCE
name=Fred
Smith
Ebase Security System
Create security roles BUSINESS_USER and FINANCE.
This is an optional additional facility that supports the configuration of user-level registry attributes that are automatically read by the Ebase system. Each registry attribute is associated with a special Ebase field name beginning $USER_ and then attribute values from the registry can be read directly by a form. For example, the mail attribute might be mapped to field $USER_EMAIL and then used to direct emails.
Ebase loads all the attributes from the LDAP repository for a particular user when the first reference to a $USER_xxxx field is made by a form. Thereafter, these are cached in memory and subsequent requests for the same user are met from the cache. A cache refresh period can be specified to indicate that Ebase should periodically refresh cached values from the LDAP system.
Use of this feature requires that users have been
authenticated. The authenticated User ID is used to search the LDAP
registry (see server property userKeyAttributeName). Note that although it is likely that this feature
will be used in conjunction with LDAP Registry authentication, this is not
strictly required. For example, the application server might be configured to
accept authenticated Windows domain users – in this case neither an Ebase logon
exit nor a login module are required, the Ebase server simply accepts the userid provided by the application server.
This is an xml file that maps user attributes from the LDAP
registry system to Ebase user fields $USER_xxx. Any
number of attributes can be specified. Ebase is supplied with a default file ldap_attributes.xml which is located in the web
application ebaseConf directory. The sample
file contains two user fields $USER_EMAIL and $USER_EMPLOYEE mapped to registry
user attributes mail and employeenumber
respectively:-
<?xml version="1.0" encoding="ISO-8859-1"?>
<!-- This file contains a list of attributes that are automatically
made available for each
authenticated user. Each attribute must contain tags:
<name> : name of the Ebase field, this must begin with
$USER_
<directory-attribute-name> : name of the attribute in the LDAP Repository
<directory-attribute-type> : type of the attribute in the
LDAP Repository
(String
is the only type currently supported)
-->
<document
type="LDAP_Attributes">
<user-attributes>
<attribute>
<name>$USER_EMAIL</name>
<directory-attribute-name>mail</directory-attribute-name>
<directory-attribute-type>String</directory-attribute-type>
</attribute>
<attribute>
<name>$USER_EMPLOYEE_ID</name>
<directory-attribute-name>employeenumber</directory-attribute-name>
<directory-attribute-type>String</directory-attribute-type>
</attribute>
</user-attributes>
</document>
The following LDAP server properties are typically required to support this feature:
ldap.registryHost
ldap.baseDistinguishedName
ldap.userKeyAttributeName
ldap.bindDistinguishedName
ldap.bindPassword
The system first creates a connection to the LDAP registry
at the host specified by ldap.registryHost and
the port specified by ldap.registryPort and
using the User ID/password from parameters ldap.bindDistinguishedName and ldap.bindPassword, if these are
specified. An LDAP search is then initiated starting from the location
given in parameter ldap.baseDistinguishedName.
This search uses the attribute name specified in ldap.userKeyAttributeName
and a value of the current user’s User ID e.g. for user “Fred” and the default
value of “cn” for ldap.userKeyAttributeName,
an LDAP attribute search of “cn=Fred” will be issued.
The $USER_ fields are automatically available so long as the
end user has been authenticated. These fields can be treated as normal Ebase
form fields in FPL scripts and addressed as system variables from an API based language. Here are some examples of
script commands:
|
FPL: |
API based language (Javascript): |
|
set EMPLOYEE_ID =
$USER_EMPLOYEE_ID; if [$USER_EMAIL !=
null] set
EMAIL = $USER_EMAIL; sendmail CONFIRMATION_MESSAGE; endif
|
fields.EMPLOYEE_ID.value = system.variables.$USER_EMPLOYEE_ID.value; if (system.variables.$USER_EMAIL.value) { fields.EMAIL.value = system.variables.$USER_EMAIL.value; resources.CONFIRMATION_MESSAGE.sendmail(); } |