- Overview
- Getting Started
- Component Functionalities
- Scheduled Task Configuration
- EventListeners to Interact with LDAP Add-on Events
- Appendix A. Application Properties
- Release notes
The LDAP integration CUBA component provides readily available instruments to enhance any CUBA-based application with the features of a directory server, e.g. Active Directory. The component is available for CUBA applications of any complexity and does not require any additional third-party frameworks or libraries.
The component provides the following functionality:
- Using LDAP credentials to log in to CUBA applications
- Configuring rules of role and user access group assignment
- Populating user details from the LDAP server automatically
- Logging LDAP synchronization details.
The following sample application can be used to test the component functionality.
Before enabling the add-on, configure your directory server.
The add-on can be added to your project in one of the ways described below. Installation from the Marketplace is the simplest way. The last version of the add-on compatible with the used version of the platform will be installed. Also, you can install the add-on by coordinates choosing the required version of the add-on from the table.
In case you want to install the add-on by manual editing or by building from sources see the complete add-ons installation guide in CUBA Platform documentation.
- Open your application in CUBA Studio. Check the latest version of CUBA Studio on the CUBA Platform site.
- Go to CUBA -> Marketplace in the main menu.
- Find the LDAP add-on there.
- Click Install and apply the changes. The add-on corresponding to the used platform version will be installed.
- Open your application in CUBA Studio. Check the latest version of CUBA Studio on the CUBA Platform site.
- Go to CUBA -> Marketplace in the main menu.
- Click the icon in the upper-right corner.
- Paste the add-on coordinates in the corresponding field as follows:
com.haulmont.addon.ldap:ldap-global:<add-on version>
where <add-on version> is compatible with the used version of the CUBA platform.
| Platform Version | Add-on Version |
|---|---|
| 7.2.x | 1.5.2 |
| 7.1.x | 1.4.0 |
| 7.0.x | 1.3.2 |
| 6.10.x | 1.2.0 |
| 6.9.x | 1.1.1 |
| 6.8.x | 1.0.1 |
- Click Install and apply the changes. The add-on will be installed to your project.
Before using the add-on as a part of your application, configure initial values for connecting to the LDAP server and set up basic attribute names of the LDAP user in the app.properties file.
An example of how to set up these properties is given below. Learn more about the application properties in Aappendix A.
ldap.contextSourceUrl = ldap://localhost:10389
ldap.contextSourceBase = dc=example,dc=com
ldap.contextSourceUserName = uid=admin,ou=system
ldap.contextSourcePassword = secret
ldap.referral = follow
ldap.sessionExpiringPeriodSec = 120
ldap.userSynchronizationBatchSize = 100
ldap.userSynchronizationOnlyActiveProperty = true
ldap.cubaGroupForSynchronization = Company
ldap.cubaGroupForSynchronizationInverse = false
ldap.synchronizeCommonInfoFromLdap = true
cuba.web.standardAuthenticationUsers = admin,anonymous
Then, specify the following properties in the web-app.properties file:
cuba.web.standardAuthenticationUsers = admin,anonymous
ldap.expiringSessionNotificationCron = */10 * * * * *
ldap.addonEnabled = true
ldap.expiringSessionsEnable = trueNote: If the component is enabled, users cannot log in to the application using CUBA credentials. However, you can permit particular users (e.g. system administrators) to log in using CUBA credentials by specifying their usernames as values of the cuba.web.standardAuthenticationUsers property.
If you want to use the component functionality in several CUBA applications, you have to enable it for each of them separately.
- LDAP Admin role - LDAP configuration role.
- Default LDAP role - default LDAP role, allows user to login with LDAP credentials.
After installation, check that all configured property values are displayed properly on the LDAP Config screen (Menu: LDAP Component → LDAP Config).
The screen comprises three sections: Connection settings, Attribute Settings and Schema Settings. The description of each section is given below.
The Connection settings section allows you to preview and test LDAP connection properties from the application UI.
Clicking the Test Connection button at the bottom of the screen launches connection testing. If the connection is successfully established, the corresponding message is displayed.
When a user logs in using LDAP credentials for the first time, your CUBA application creates a new User entity.
The LDAP server passes all user details to the application. Make sure you provide user information when configuring your LDAP server.
The Attribute Settings section enables you to match LDAP attributes and the fields of the User entity.
The Schema Settings section allows you to define what can be stored as LDAP directory entries.
Using the table, you can set up conditions of matching rule application.
Clicking the Refresh LDAP Attributes button uploads all attributes of the specified LDAP user object class. You can add attributes manually by using the Create button.
LDAP matching rules are special rules to configure access rights for new application users (those created after logging in via LDAP). There are four rule types intended for this purpose:
- Custom
- Default
- Simple
- Scripting. You can create and manage LDAP matching rules using the LDAP Matching Rule screen (Menu: LDAP Component → LDAP Matching Rules).
The screen comprises the table of matching rules and testing section. Using the table, you can enable/disable certain rules using checkboxes in the Active column. The testing section allows you to check how the existing matching rules are applied to a particular user (see Testing LDAP Matching Rules).
Matching rules have order numbers defining the sequence of their application.
The LDAP component provides the means to process programmatically defined custom rules. You can create custom rules by
adding new classes to the classpath of your application. They have to be implemented as Spring beans and
provided with the @LdapMatchingRule annotation.
Custom rules can be viewed from the application UI. However, you cannot configure or edit them there.
The advantage of custom rules is that they allow you to specify conditions not related to LDAP attributes or schema. The example of a custom rule is provided below.
@Component
@LdapMatchingRule(name = "Custom Rule 1", condition = "Test Rule")
public class TestCustomRule implements CustomLdapMatchingRule {
@Inject
private CubaUserDao cubaUserDao;
@Inject
private RolesService rolesService;
@Override
public boolean applyCustomMatchingRule(LdapMatchingRuleContext ldapMatchingRuleContext) {
if (ldapMatchingRuleContext.getLdapUser().getLogin().equalsIgnoreCase("barts")) {
User admin = cubaUserDao.getOrCreateCubaUser("admin");
Role role = rolesService.getRoleDefinitionAndTransformToRole(admin.getUserRoles().get(0).getRoleName());
ldapMatchingRuleContext.getRoles().add(role);
ldapMatchingRuleContext.setGroup(admin.getGroup());
}
return true;
}
}When you launch your application for the first time after component installation, the system automatically creates the default rule.
It is used if none of other rules were applied, i.e. conditions for applying the existing rules were not met. The system always applies the default rule the last. That is why it contains the LAST value in the Order field.
You can edit the default rule by clicking the Edit button. All fields and settings present in Default Matching Rule Editor are described in the section below.
- Description: a short description of the default rule.
- Terminal rule: if checked, then rules coming after the current one (according to the rule order) are not applied.
- Access group: an access group to be assigned to the user, if the default rule is applied.
- Override existing access group: if checked, then the system removes the previously assigned access group and uses the one specified in the Access group field.
- Override existing roles: if checked, then the system removes all previously assigned roles and uses the ones specified in the 'Roles' section.
The Roles table allows you to create a set of roles to be assigned to a user, if the default rule is used.
Simple rules grant access rights (by assigning an access group and roles) to users, if the specified conditions are met. To create a simple rule, select the Create Simple Rule option from the menu of the Create Matching Rule button.
Simple Matching Rule Editor comprises settings and tables to configure simple matching rules:
- General details and settings. The fields are similar to the ones described in Default Matching Rule Editor.
- Conditions. The section enables you to add conditions to be met for successful rule application. Click the Create button to open Simple Rule Condition Editor.
The editor contains the following fields:
- Attribute: an LDAP attribute to be checked before applying the current simple rule.
Note: Before creating conditions it is required to add them to the existing LDAP Schema (for more details, refer to LDAP Schema).
- Attribute Value: a value of the selected attribute. The system applies the rule to those user entities having the specified value of the selected attribute.
- Roles. In this section, you can add user roles to be assigned to the user in case of successful rule application.
You can provide a Groovy script with a set of conditions to be met to grant a user access rights. To create a new scripting rule, select the Create Scripting Rule option from the Create matching rule button menu.
Scripting Matching Rule Editor contains a set of general fields (these fields are similar to the ones described in Default Matching Rule Editor), a section for specifying and testing Groovy scripts and a table of roles.
The component uses the specified condition to evaluate the matching rule context. Note that the {ldapContext} placeholder has to
be used as an alias for the LDAP matching rule context. The {ldapContext} provides the following fields:
- ldapUser: main LDAP person properties (login, cn, sn, email, memberOf, accessGroups, isDisabled, position, language, ou)
- appliedRules: matching rules that were applied to the context
- roles: previously assigned user roles
- group: an access group that the user currently belongs to
- cubaUser: a CUBA user to whom a current matching rule is applied.
- isTerminalRuleApply: if checked, a current rule is a terminal one, i.e. once it is used, no other rules are applied.
After creating all required matching rules, you can test them right from the LDAP Matching Rule screen. For this purpose, enter a user login in the corresponding field and click Test Rules.
After that, the applied matching rules, access groups and roles are displayed in the corresponding fields and tables. This functionality is useful when you need to check the accuracy of rule application.
You can use the LDAP Log screen to view all activities related to LDAP connection from the application UI. This includes user authentication checks, rule application, user entity updates and errors that occur while using the component features.
In order to view any log entry, just double-click it, or select it in the table and click the View button.
Clicking the Excel button enables you to download details of the selected rows (or all rows if required) to an *.XLS file.
Before setting up scheduled tasks, make sure that application properties are
configured in the web-app.properties and app.properties files.
There are several scheduled tasks that you can configure for the LDAP component:
checkExpiredSessions(): checks if a new access group or role was assigned to the current user, or if they were activated/deactivated.killExpiredSessions(): terminates the current user session, if the user was activated/deactivated, or a new access group/set of roles was assigned to them.synchronizeUsersFromLdap(): synchronizes CUBA user details in accordance with their state in LDAP.
In order to register scheduled tasks in your application, follow the guidelines below.
- Open Menu: Administration → Scheduled Tasks.
- Click the Create button.
- Fill in the required fields as follows:
- Bean Name:
ldap_UserSynchronizationSchedulerService - Method Name:
checkExpiredSessions() - Scheduling Type: Cron
- Cron Expression: specify a required cron expression (see documentation for more details)
- Bean Name:
- Click OK to save the changes.
- Activate the created task by clicking the corresponding button on the Scheduled Tasks screen.
- Open Menu: Administration → Scheduled Tasks.
- Click the Create button.
- Fill in the required fields as follows:
- Bean Name:
ldap_UserSynchronizationSchedulerService - Method Name:
killExpiredSessions() - Scheduling Type: Cron
- Cron Expression: specify a required cron expression (see documentation for more details)
- Bean Name:
- Click OK to save the changes.
- Activate the created task by clicking the corresponding button on the Scheduled Tasks screen.
- Open Menu: Administration → Scheduled Tasks.
- Click the Create button.
- Fill in the required fields as follows:
- Bean Name:
ldap_UserSynchronizationSchedulerService - Method Name:
synchronizeUsersFromLdap() - Scheduling Type: Cron
- Cron Expression: specify a required cron expression (see documentation for more details)
- Bean Name:
- Click OK to save the changes.
- Activate the created task by clicking the corresponding button on the Scheduled Tasks screen.
- Open Menu: Administration → Application Properties.
- Set the value of the cuba.schedulingActive property to
true.
After you have created the scheduled tasks and enabled scheduling, the system will check user sessions once in the specified period of time.
If there are any changes related to access groups, user roles or user status (i.e. activation/deactivation), the system shows the notification that the current session is about to expire and terminates it once the time threshold is passed.
If user details change on the LDAP server side, the component updates CUBA user details as well.
In order to make your application react to the events related to the LDAP component, register the @Component methods
as event listeners using the @EventListener annotation. The example of how to configure an event listener is given below:
import org.springframework.context.event.EventListener;
@Component
public class LdapEventListener {
@EventListener
public void userCreatedFromLdap(UserCreatedFromLdapEvent event) {
// handles user creation event
}
}The application component supports the following LDAP event types:
BeforeUserRolesAndAccessGroupUpdatedFromLdapEvent: defines the state of the CUBA user before matching rule application, i.e. before the system assigns user roles and an access group to them.AfterUserRolesAndAccessGroupUpdatedFromLdapEvent: defines the state of the CUBA user after matching rule application, i.e. after the system assigns user roles and an access group to them.UserCreatedFromLdapEvent: describes the state of the new CUBA user, i.e. after logging in using LDAP credentials.UserActivatedFromLdapEvent: defines the state of the CUBA user that was previously inactive and then activated.UserDeactivatedFromLdapEvent: defines the state of the CUBA user that was previously active and then deactivated.
Before working with the component you need to configure application properties. Specify them in the app.properties and web-app.properties files of your application.
- Description: defines a URL for reaching an LDAP server.
- Default value: ldap://localhost:10389
- Description: defines a base DN. If configured, all LDAP operations on contexts retrieved from this ContextSource relate to this DN. The default value is an empty distinguished name (i.e. all operations relate to the directory root).
- Default value: dc=springframework,dc=org
- Description: indicates a username (principal) used for authentication. This is normally the distinguished name of the admin user.
- Default value: uid=admin,ou=system
- Description: defines a password used for authentication.
- Default value: secret
- Description: defines the strategy to handle referrals, as described in this documentation.
- Default value: follow
- Description: indicates a period in seconds after which the system terminates a user session, if you deactivate the user or assign a new access group / matching rules to them.
- Default value: 30
- Description: defines users that can log in to the system using standard CUBA credentials.
- Default value: admin,anonymous
- Description: defines the number of users that can be synchronized during the execution of the
synchronizeUsersFromLdap()scheduled task. - Default value: 100
- Description: if set to
true, thesynchronizeUsersFromLdap()scheduled task updates only the value of the Active attribute. Otherwise, the system updates all user details. - Default value: true
- Description: defines access groups that are checked when the system executes the
synchronizeUsersFromLdap()scheduled task. - Default value: Company
- Description: if set to
true, then the system checks all groups when executing thesynchronizeUsersFromLdap()scheduled task (except for the ones specified inldap.cubaGroupForSynchronization). - Default value: false
- Description: if set to
true, then thesynchronizeUsersFromLdap()scheduled task updates the values of the following user attributes in accordance with their state on the LDAP server side: Email, Name, First name, Last name, Middle name, Position, Language). - Default value: true
- Description: defines users that can log in to the system using standard CUBA credentials.
- Default value: admin,anonymous
- Description: defines the cron expression for retrieving expired sessions from the middleware layer.
- Default value: */10 * * * * *
- Description: if set to
true, then the LDAP add-on is enabled. - Default value: true
- Description: if set to
true, the system sends notifications to inform the user that their session is about to expire. - Default value: true
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent