Cloud Software Group, Inc. EBX®
Documentation > Administration Guide > Technical administration
Navigation mode Documentation > Administration Guide > Technical administration

# Users and roles directory

## Overview

TIBCO EBX® uses a directory for user authentication and user role definition.

A default directory is provided and integrated into the EBX® repository; the 'Directory' administration section allows defining which users can connect and what their roles are.

It is also possible to integrate another type of enterprise directory.

##### See also

- Configuring the user and roles directory
- Custom directory

## Concepts

In EBX®, a user can be a member of several roles, and a role can be shared by several users. Moreover, a role can be included into another role. The generic term profile is used to describe either a user or a role.

In addition to the directory-defined roles, EBX® provides the following built-in roles:

Role | Definition
--- | ---
Profile.ADMINISTRATOR | Built-in Administrator role. Allows performing general administrative tasks.
Profile.READ_ONLY | Built-in read-only role. A user associated with the read-only role can only view the EBX® repository, and has no right to perform modifications in the repository.
Profile.OWNER | Dynamic built-in owner role. This role is checked dynamically depending on the current element. It is only activated if the user belongs to the profile defined as owner of the current element.
Profile.EVERYONE | All users belong to this role.

Information related to profiles is primarily defined in the directory.

##### Attention

Associations between users and the built-in roles OWNER and EVERYONE are managed automatically by EBX®, and thus must not be modified through the directory.

User permissions are managed separately from the directory. See Permissions.

##### See also

- profile
- role
- user
- administrator
- user and roles directory

### Policy

These properties configure the policies of the user and roles directory, for example, whether or not users can edit their own profiles.

### Users

This table lists all the users defined in the internal directory. New users can be added from there.

### Roles

This table lists all the roles defined in the internal directory. New roles can be created in this table.

## Built-in directories

### Default directory

The default directory is represented by the dataset 'Directory', in the 'Administration' area.

#### Directory content

This dataset contains tables for users and roles, as well as users' roles table, roles' inclusions table and salutations table.

##### Note

If a role inclusion cycle is detected, the role inclusion is ignored at the permission resolution. Refresh and check the directory validation report for cycle detection.

##### Note

Users' roles, roles' inclusions and salutations tables are hidden by default .

Depending on the policies defined, users can modify information related to their own accounts, regardless of the permissions defined on the directory dataset.

##### Note

It is not possible to delete or duplicate the default directory.

#### Password recovery procedure

In the default directory, passwords are encrypted (by default with a SHA256-like algorithm), and stored in this state. Consequently, it is impossible to retrieve lost passwords. A new password must be generated and sent to the user.

There are two options for this procedure:

1. A notification email is sent to the administrator, the administrator manually changes the password and sends the new password to the user.

2. A procedure automatically generates a new password and sends it to the user.

By default, the first option is used. To activate the second option, specify the property `ebx.password.remind.auto=true` in the TIBCO EBX® main configuration file.

##### Note

For security reasons, the password recovery procedure is not available for administrator profiles. If required, use the administrator recovery procedure instead.

#### Administrator recovery procedure

If all the 'login/password' credentials of the administrators are lost, a special procedure must be followed. A specific directory class redefines an administrator user with login 'admin' and password 'admin'.

To activate this procedure:

- Specify the following property in the TIBCO EBX® main configuration file:

  `ebx.directory.factory= com.orchestranetworks.service.directory.DirectoryDefaultRecoverFactory`

- Start EBX® and wait until the procedure completes.

- Reset the '`ebx.directory.factory`' property.

- Restart EBX® and connect using the 'admin' account.

##### Note

While the '`ebx.directory.factory`' property is set for the recovery procedure, authentication of users will be denied.

### LDAP directory

EBX® built-in support for LDAP (Lightweight Directory Access Protocol) was designed as a custom directory implementation, which allows you to integrate an existing LDAP directory with 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.

#### Activation

Activate LDAP using the built-in LDAP directory factory as the directory factory in the EBX® main configuration file (see Configuring the user and roles directory).

#### Configuration

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).

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

##### Search request templates

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 executed in a paginated manner to enhance efficiency and manageability. Additionaly, each request template can be backed by a cache to optimize performance. Use the available parameters to fine-tune page retrieval and cache implementation. Even if for a short duration or with a small size, caching is recommended, as is 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 the groups a user belongs to.

- Find users within a specific 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 this all-users query is not configured, selections in the permission fields are exclusively limited to groups, excluding the possibility of selecting individual users.

##### See also

- Configuring EBX® main configuration properties
- Configuring EBX® Container Edition environment variables

#### Limitations

It is important to note that only one LDAP server can be configured at a time. This means simultaneous connections to multiple 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.

Notice that only simple and anonymous authentication methods are allowed. This means that 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 introduced by display expressions in the configuration file. Locale is only considered when the display expressions can not be applied.

## Custom directory

As an alternative to the built-in directories, it is possible to integrate a specific company directory. For example, a relational database or a specific directory model instantiated into EBX®. The default login page can also be replaced by a specific company page.

##### See also

- Configuring EBX® Container Edition environment variables
- `DirectoryFactory`
- `Directory.getUserAuthenticationURI`

## Enabling the SCIM feature

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.

EBX® uses the `urn:ietf:params:scim:schemas:core:2.0` schema version.

SCIM should be used with SSO in EBX® to automate user provisioning and ensure up-to-date access control, as SCIM manages roles and permissions while SSO handles authentication. This combination enhances security and simplifies the management of user authorization across the system. It works in conjunction with a built-in or custom directory.

The SCIM feature is implemented as a custom directory. The only mapped SCIM fields are `username` to reference a user, `displayName` to reference a group, `display` to reference a `username` in a group and `name/formatted` to display a user.

The selected user email is the primary one.

### Configuration

A SCIM server should be activated on the IdP (Identity Provider) side. To configure the EBX® options for:

- On premises, see Configuring EBX® main configuration properties.

- Container edition, see Configuring EBX® Container Edition environment variables.

Documentation > Administration Guide > Technical administration