TIBCO EBX® uses a directory system to manage user authentication and role definitions. A main directory is required and is the default source for authentication and authorization.
When Single Sign-On (SSO) is enabled, EBX® can use a synchronized directory in addition to the main directory. The synchronized directory enables management of external users authenticated via an identity provider. With this setup:
Use the main directory for technical users.
Use the synchronized directory for users managed by the external system.
The following list outlines the general procedure for configuring a directory to handle user authentication and authorization:
Choose the main directory implementation: Default, built-in LDAP, or Custom directory.
If needed, enable SSO using one protocol: OIDC or SAML2.
If needed, enable the synchronized directory using one of the built-in implementations: LDAP, SCIM or On Login.
Configure the selected directories and protocols.
Do not use the Default directory in production. Instead, use your own custom Directory with a more secure password system or a built-in directory option to protect sensitive information.
If both main and synchronized directories are used, usernames must be unique across directories. If a username exists in both, the system merges roles from both directories. However, the user's information (e.g., name, email, etc.) is taken only from the synchronized directory. This can lead to inconsistencies or unintended overrides, so unique usernames across directories are strongly advised.
In TIBCO EBX®, a user can be a member of one or more roles, and multiple users can share the same role. Additionally, a role can include other roles. The documentation uses the generic term profile to describe either a user or a role. Information related to profiles is primarily defined in the directory.
In addition to roles you define in a directory, TIBCO EBX® provides the following built-in roles:
| Role | Definition |
|---|---|
Profile.ADMINISTRATOR | Grants full access for administrative tasks. |
Profile.READ_ONLY | Allows users to view content only. No repository modifications are allowed. |
Profile.OWNER | A dynamic role that is only active when the user is (or is included in) the profile defined as the owner of the current element. |
Profile.EVERYONE | All users are included in this role. |
Associations between users and the built-in roles OWNER and EVERYONE are managed automatically by TIBCO EBX®, and must not be modified through the directory.
User permissions are managed separately from the directory. See Permissions for more information.
The Directory > Policy table allows you to configure whether users can manage specific aspects of their own profiles. For example, policies can specify whether:
users can update their own account information.
password reminder options are also available.
The main directory is required and handles login authorization using a username and password. EBX® supports the following directory types: default directory, LDAP directory, or a custom directory implementation.
The default directory and related tables is located in the Administration > Users, roles and preferences > Directory dataset. This dataset includes tables to create and store: user policies, mailing lists, users and roles. You cannot delete or duplicate the default directory.
Depending on the defined policy, users can modify information related to their own accounts, regardless of the permissions defined on the directory dataset.
If a role inclusion cycle is detected, the role inclusion is ignored during permission resolution. To detect such cycles, refresh and check the directory validation report.
The Users roles and Roles inclusions and salutations tables are hidden by default .
In the default directory, passwords are encrypted (using SHA256-like algorithm by default), and stored in this state. As a result, lost passwords cannot be retrieved. A new password must be generated and sent to the user.
There are two options for this procedure:
A notification email is sent to the administrator, the administrator manually changes the password and sends the new password to the user. This is the default option.
A procedure automatically generates a new password and sends it to the user. To activate this option, set the following property in the TIBCO EBX® main configuration file: ebx.password.remind.auto=true.
For security reasons, the above password recovery procedure is not available for administrator profiles. Use the administrator recovery procedure instead.
If all administrator credentials are lost, use the following special recovery process to use a directory class to redefine a temporary administrative account with admin/admin as the login and password:
Specify the following property in the TIBCO EBX® main configuration file:
ebx.directory.factory= com.orchestranetworks.service.directory.DirectoryDefaultRecoverFactory
Start TIBCO EBX® and wait until the procedure completes.
Reset the 'ebx.directory.factory' property.
Restart TIBCO EBX® and connect using the 'admin' account.
While the 'ebx.directory.factory' property is set for the recovery procedure, all other user authentications are disabled.
EBX® supports LDAP (Lightweight Directory Access Protocol) as either a main directory or a synchronized directory. See Synchronized LDAP directory for instructions on using it as a synchronized directory. To use LDAP as a main directory: Set the directory factory to the built-in LDAP directory factory in Configuring the user and roles directory.
A custom directory is an alternative to using the EBX® built-in directories. You can integrate a specific company directory contained in a relational database, or a specific directory data model instantiated in TIBCO EBX®. You can also set the default login page to a specific company page. See the following links for the corresponding documentation resources.
The Synchronized directory is represented by the dataset ebx-synchronized-directory, available in the Administration area after configuration. It is an integrated directory used to authenticate and authorize external users. EBX® manages permissions using internal roles only. External roles must be mapped to internal roles.
A synchronized directory should be used in combination with SSO in EBX®:
The directory is used to manage users and roles with automatic provisioning to ensure up-to-date access control.
The SSO handles user authentication.
This approach provides centralized user management and ensures consistent access control across systems.
The synchronized directory and its role mapper are configured through the main EBX® configuration file. See Configuring the synchronized directory for instructions.
TIBCO EBX® built-in support for LDAP (Lightweight Directory Access Protocol) was designed as main and synchronized directory implementations, which allows you to integrate an existing LDAP directory with TIBCO EBX®. This ensures a streamlined and efficient directory management experience through secure and consistent access control that is tailored to your organization's LDAP infrastructure needs.
Role synchronization is done by scheduling the task: com.orchestranetworks.service.directory.scim.SchedulerLdapSynchronization
The following four types of configuration parameters are available:
Connection parameters are needed to establish and handle a connection to the LDAP server. They are also used to tune the connection for optimal performance and security.
For LDAPS uses, a root certificate must be imported if it is not available in the JDK TrustStore (see Installing a Root Certificate in the TrustStore for more information).
Mapping parameters are used to map certain built-in roles and users to LDAP directory attributes.
Display of users and roles using expressions derived from LDAP attributes.
Search request templates generate LDAP requests, allowing precise and efficient information retrieval from the LDAP directory.
An LDAP search query consists of the following three key elements:
Base DN (Distinguished Name): sets the initial point in the directory tree.
Search filter: defines attributes and values to locate.
Search scope: dictates the search depth within the directory tree (from the base to several levels deep).
It is important to note that queries are paginated to enhance efficiency and manageability. Additionally, each request template can use caching to optimize performance. Use the available parameters to fine-tune page retrieval and cache implementation. Caching is recommended, even if for short durations with a small size. It can significantly improve overall system performance by reducing redundant data fetching.
Search templates support placeholders that adapt to each specific type of query. There are four mandatory templates that:
Find an individual user.
Identify a user's groups.
Find users in a group.
Retrieve all groups.
Additionally, there is an optional template to find all users. While not required, it is crucial for broader user accessibility. If it is not configured when assigning permissions, selections are limited to groups. Individual users cannot be selected.
When using LDAP as a synchronized directory in EBX®, the following restrictions apply:
Only one LDAP server can be configured at a time. Multiple simultaneous connections to LDAP servers are not supported within the same instance.
There is no support for role inclusion or the addition of specific roles on the EBX® side. Consequently, the structure and nested relationships of groups within LDAP are not considered in the calculation of permissions. This limitation highlights a straightforward, group-based access control approach without the complexities of LDAP's hierarchical group dynamics.
Only simple and anonymous authentication methods are allowed. More complex or secure authentication protocols used within LDAP are not supported.
Roles and usernames display is not locale dependent and is limited to one format defined by display expressions in the configuration file. Locale is only considered when the display expressions can not be applied.
SCIM (System for Cross-domain Identity Management) is a standard protocol designed to automate the exchange of user identity information between IT systems. It simplifies user provisioning and management across multiple platforms by using a common schema and RESTful API.
The schema version used is: urn:ietf:params:scim:schemas:core:2.0.
Role synchronization is managed by the scheduled task: com.orchestranetworks.service.directory.scim.SchedulerScimSynchronization
A SCIM server should be activated on the IdP (Identity Provider) side.
The On Login directory is a persistent directory that synchronizes users and roles on login, based on information from SSO protocols. As a consequent, the list of users is not complete. Users that have never logged in will are not included.
A role mapper can be configured in the main EBX® configuration file to map between an external user’s roles and his internal roles.
To ensure the migration of LDAP and SCIM directories from a version prior to 6.2.2, enable roles import on the scheduled task options of each directory. This ensures the consistency of already persisted permissions with external roles.