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
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. For runtime users, security roles are only required when runtime form security is used e.g. when a security authorization is specified for a form in form properties, or when the isAuthorized() FPL function is used. See Configuring Authorization.
Optionally, for runtime users, Ebase 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
UFSSetup.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.
Configure the following properties in the UFSSetup.properties file.
|
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 specifying the following parameter in UFSSetup.properties:
Ufs.logonExitServlet=LogonExitServlet
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.
Authorizations in the Ebase system are supplied using Security Roles (See Configuring Authorization). These roles are created using the Ebase Designer and stored in the Ebase repository database. As part of the authentication process, the system attempts to extract the names of all roles for a user. When signing on to the Ebase Designer, at least one security role is required, as otherwise the user has no permissions including the permission to connect as a designer. When signing on as a runtime user, roles are only required when runtime form security is used e.g. when a security authorization is specified for a form in form properties, or when the isAuthorized() FPL function is used.
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, parameter ldap.userRoleAttributeName 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.
UFSSetup.properties
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.
When authentication is configured as described above, all userid and password authentication is directed to the LDAP Registry. However, it is possible to specify that runtime users authenticate against the LDAP Registry and designer users authenticate against the supplied Ebase security system. This is specified with UFSSetup.properties parameter:
Ufs.useUserManagerForDesignerAuthentication=true
If runtime security authorizations are not needed, using this parameter removes the need to designate a separate registry attribute to contain the Ebase security role names.
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 parameter ldap.userKeyAttributeName below). 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 preferences directory. The file
path is specified in parameter Ufs.ldapAttributesFileName in UFSSetup.properties. The contents of this 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>
Copy this file to a directory outside the Ebase web
application and modify it for your requirements. Note that Ebase field names
must begin with $USER_ and an error message will be generated for any fields
not following this rule when the file is loaded at Ebase initialization time.
The file should be copied outside the Ebase web application to avoid problems
when upgrading to future versions of Ebase.
The following parameters in UFSSetup.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 Ebase
application must be restarted to pick up the changes.
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(); } |