Configuring LDAP Based Security

Configuring the LDAP login module. 1

Configuring LDAP properties 1

Configuring the Logon Exit 3

Windows Domain userid formats 3

Configuring Authorization. 3

Configuring Designer Authentication Separately. 4

Configuring User Attributes 4

Set up the LDAP attributes file. 4

Accessing LDAP attributes from a form. 5

Overview

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. See User Authentication. Once a user has been authenticated, the system attempts to extract roles for the user, which will then be used to evaluate any subsequent authorization requests.

Optionally, for runtime users, the system 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.

Configuring Authentication

Configuring the LDAP login module

This is configured using a JAAS login configuration file ebaselogin.config which is distributed in <userdata>/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

Configuring LDAP properties

The following server properties are configured using the Server Administration Application – Security Properties:

Parameter	Description	Default
ldap.protocol	This can be either ldap - clear text and not secure. This is not recommended when communicating between different servers ldaps – uses SSL and TLS communication. All data will be encrypted	ldap
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. 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 the system 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, the system 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 name of the user attribute used 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 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 the system 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

User Login Name

The userKeyAttributeName should be set to an attribute which contains a unique ID of a person object.

The value of this attribute will represent the user’s login id and will also be set to $USER once authenticated.

The uid attribute of the inetorgperson object class is the LDAP standard attribute most suitable for this. The inetorgpeson class is defined in RFC 2798 is used in most directory services to derive the user.

Active Directory for Windows has an attribute specifically for user login names, the SAMAccountName. You may choose to use this instead of the uid.

The LDAPLoginModule2 will work with any attribute set as the userKeyAttributeName property.

ldap.userKeyAttributeName=sAMAccountName

or

ldap.userKeyAttributeName=uid

The value of the user id is returned by the LDAP Assignment Handler when performing searches and user assignment.

An example uid could be the first name and the first two letters of the surname:

uid=joebl

When logging on, the user would only need to enter the uid joebl.

Configuring the Logon Exit

A logon exit is responsible for obtaining a userid and password from the end user. The 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.

Windows Domain userid formats

When signing on to a Windows domain, the system 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 system (and available via the $USER system variable) is just the userid portion e.g. paulsmith.

Configuring Authorization

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 internal security system. To use this option, users must be defined in both the LDAP Registry and the internal security system. The LDAP Registry is used to perform a password check, then the internal 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 Server 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

Internal Security System

Create security roles BUSINESS_USER and FINANCE.

Configuring User Attributes

This is an optional additional facility that supports the configuration of user-level registry attributes that are automatically read by the system. Each registry attribute is associated with a special 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.

The system 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 the system 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 a logon exit nor a login module are required, the Verj.io server simply accepts the userid provided by the application server.

Set up the LDAP attributes file

This is an xml file that maps user attributes from the LDAP registry system to special user fields $USER_xxx. Any number of attributes can be specified. The system 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)

-->

<user-attributes>

<name>$USER_EMAIL</name>

<directory-attribute-name>mail</directory-attribute-name>

<directory-attribute-type>String</directory-attribute-type>

</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

(see descriptions earlier)

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.

Accessing LDAP attributes from a form

The $USER_ fields are automatically available so long as the end user has been authenticated. These fields can be treated as normal Verj.io 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();

}