IDE Services 2025.5 Help

LDAP

LDAP authentication configuration lets users log in to IDE Services with credentials that are stored in a third-party directory service, such as Microsoft Active Directory or OpenLDAP. You can configure a connection to use the standard LDAP scheme or LDAPS over SSL.

Prerequisites

  • You have a directory service set up for your organization.

  • You have a server configuration file created for your IDE Services instance: application.yaml or values.yaml (for a Kubernetes Helm installation).

  • If you are going to connect to the directory service over SSL, make sure to import the trusted SSL certificate for your LDAPS server before establishing the connection.

    Import the SSL certificate to javax.net.ssl.trustStore which is defined in your environment.

    If there are any intermediate certificates between the server’s SSL certificate and the root CA certificate, upload a file that includes the full certificate chain.

Initial setup

To set up the connection with the directory service, add the following parameters to your IDE Services Server configuration file (application.yaml or values.yaml)

Enable LDAP

tbe: auth: ldap: enabled: true
ides: config: auth: ldap: enabled: true

Specify your LDAP server URL

Example for standard LDAP connection:

tbe: auth: ldap: enabled: true url: 'ldap://localhost:10000'
ides: config: auth: ldap: enabled: true url: 'ldap://localhost:10000'

Example for LDAPS over SSL:

tbe: auth: ldap: enabled: true url: 'ldaps://localhost:10000'
ides: config: auth: ldap: enabled: true url: 'ldaps://localhost:10000'

Specify base DN

base-dn defines the root distinguished name (DN) of the LDAP subtree used as the starting point for all LDAP queries (e.g., user and group lookups).

Set this to the top-level organizational unit or domain where user and group entries are stored. Ensure the specified subtree includes all relevant entries needed for authentication and authorization.

Example:

tbe: auth: ldap: enabled: true base-dn: 'dc=com,dc=test,dc=org'
ides: config: auth: ldap: enabled: true base-dn: 'dc=com,dc=test,dc=org'

Specify initial administrators

tbe: auth: root-admin-emails: - "john.admin@example.com"
ides: config: auth: root-admin-emails: - "john.admin@example.com"

Alternatively, you can import administrators as described in the Group sync and import section.

Internal tokens

IDE Services manages the internal JWT token to support sessions. For this purpose, it is required to generate an RSA key pair.

Generate an RSA key pair

Run the following command:

openssl genrsa -out private_key.pem 4096 openssl rsa -pubout -in private_key.pem -out public_key.pem # Convert the private key to pkcs8 to import it from Java openssl pkcs8 -topk8 -in private_key.pem -inform pem -out private_key_pkcs8.pem -outform pem -nocrypt

Specify internal tokens

Specify the private and public keys you have generated earlier and associated parameters in your IDE Services Server configuration file (application.yaml or values.yaml)

tbe: auth: internal-tokens: token-life: 30m refresh-token-life: 30d private-key: | <private_key_pkcs8.pem> public-key: | <public_key.pem>

Parameter

Description

tbe.auth.internal-tokens.token-life

Specify the duration for which the JWT token, issued after a successful login, remains valid. This token is primarily used for making authenticated calls to IDE Services.

tbe.auth.internal-tokens.refresh-token-life

Specify the duration for which the Refresh JWT token remains valid. The refresh token is used to renew the primary JWT token without requiring re-authentication via LDAP. If the refresh token expires (30 days by default), the user will need to re-authenticate via LDAP.

tbe.auth.internal-tokens.private-key

Provide the content of the private_key_pkcs8.pem file. This is a private key that will be used to sign internal JWT tokens.

tbe.auth.internal-tokens.public-key

Provide the content of the public_key.pem file. This is a public key that will be used to validate internal JWT tokens.

ides: config: auth: internal-tokens: token-life: 30m refresh-token-life: 30d private-key: | <private_key_pkcs8.pem> public-key: | <public_key.pem>

Parameter

Description

ides.config.auth.internal-tokens.token-life

Specify the duration for which the JWT token, issued after a successful login, remains valid. This token is primarily used for making authenticated calls to IDE Services.

ides.config.auth.internal-tokens.refresh-token-life

Specify the duration for which the Refresh JWT token remains valid. The refresh token is used to renew the primary JWT token without requiring re-authentication via LDAP. If the refresh token expires (30 days by default), the user will need to re-authenticate via LDAP.

ides.config.auth.internal-tokens.private-key

Provide the content of the private_key_pkcs8.pem file. This is a private key that will be used to sign internal JWT tokens.

ides.config.auth.internal-tokens.public-key

Provide the content of the public_key.pem file. This is a public key that will be used to validate internal JWT tokens.

Bind account

Authentication is handled using the Search and Bind method which requires you to have a dedicated service account — known as bind account — on the LDAP server with permission to search the directory and read user attributes.

When a user tries to log in, the system first uses the bind account to connect to the directory. It then searches for the user’s LDAP entry using a specific attribute — such as username, email address, or another unique identifier. Once the user is found, the system attempts a second bind using the found DN and the password the user provided. This setup allows users to log in with familiar identifiers (like email or username), without needing to provide their Distinguished Name (DN).

Specify bind account settings

Add the following parameters to your IDE Services Server configuration file (application.yaml or values.yaml)

Example:

tbe: auth: ldap: enabled: true url: 'ldap://localhost:10000' base-dn: 'dc=jbides,dc=test,dc=org' bind-user-login: 'uid=admin,ou=system' bind-user-password: 'secret' user-object-filter: '(objectClass=inetOrgPerson)' user-email-attribute: 'mail' user-login-attribute: 'uid'

Parameter

Description

tbe.auth.ldap.bind-user-login

Distinguished Name (DN) of the service account used by IDE Services to connect and perform LDAP operations (e.g., searching users and groups).

  • Purpose: Authenticates IDE Services to the LDAP server (i.e., LDAP bind).

  • Requirements: Must have read permissions for user and group entries within the defined base-dn.

  • Example: cn=ldap-reader,ou=system,dc=example,dc=com

tbe.auth.ldap.bind-user-password

Password for the service account specified in bind-user-login.

  • Purpose: Used during the bind request to authenticate IDE Services to the LDAP server.

  • Security: Store securely and restrict access to avoid credential leakage.

tbe.auth.ldap.user-object-filter

Specifies a base LDAP filter to identify user entries during search and authentication operations. Applied as-is in all LDAP queries involving user lookup.

  • Purpose: Limits results to valid user objects, avoiding matches with non-user entries (e.g., groups, computers).

  • Usage: Combine with login attributes (e.g., uid, sAMAccountName) to form complete search filters.

  • Best practice:

    • Use objectCategory with Active Directory for better performance.
      Example: (objectCategory=person)

    • Use objectClass with OpenLDAP and other directories.
      Example: (objectClass=inetOrgPerson)

Ensure this filter accurately reflects how user entries are structured in your directory schema.

tbe.auth.ldap.user-login-attribute

Specifies the LDAP attribute used to identify users by their login name.

  • Combined with user-object-filter to locate a unique user entry via LDAP search.

  • Default: uid

  • For Active Directory either sAMAccountName or userPrincipalName are recommended.

Ensure the attribute uniquely identifies user entries within the search scope.

tbe.auth.ldap.user-additional-dn

Optional DN fragment prepended to base-dn when constructing user DNs (used in user searches).

  • Purpose: Narrows search or DN derivation to a specific organizational unit.

  • Example:
    If user-additional-dn = ou=users and base-dn = dc=example,dc=com,
    the search will target: ou=users,dc=example,dc=com

tbe.auth.ldap.user-email-attribute

Specifies the LDAP attribute that contains the user's email address.

  • Purpose: Maps to the application’s internal email field.

  • Default: mail

  • Common alternatives: userPrincipalName, email

Must match the schema used in your LDAP directory.

ides: config: auth: ldap: enabled: true url: 'ldap://localhost:10000' base-dn: 'dc=jbides,dc=test,dc=org' bind-user-login: 'uid=admin,ou=system' bind-user-password: 'secret' user-object-filter: '(objectClass=inetOrgPerson)' user-email-attribute: 'mail' user-login-attribute: 'uid'

Parameter

Description

ides.config.auth.ldap.bind-user-login

Distinguished Name (DN) of the service account used by IDE Services to connect and perform LDAP operations (e.g., searching users and groups).

  • Purpose: Authenticates IDE Services to the LDAP server (i.e., LDAP bind).

  • Requirements: Must have read permissions for user and group entries within the defined base-dn.

  • Example: cn=ldap-reader,ou=system,dc=example,dc=com

ides.config.auth.ldap.bind-user-password

Password for the service account specified in bind-user-login.

  • Purpose: Used during the bind request to authenticate IDE Services to the LDAP server.

  • Security: Store securely and restrict access to avoid credential leakage.

ides.config.auth.ldap.user-object-filter

Specifies a base LDAP filter to identify user entries during search and authentication operations. Applied as-is in all LDAP queries involving user lookup.

  • Purpose: Limits results to valid user objects, avoiding matches with non-user entries (e.g., groups, computers).

  • Usage: Combine with login attributes (e.g., uid, sAMAccountName) to form complete search filters.

  • Best practice:

    • Use objectCategory with Active Directory for better performance.
      Example: (objectCategory=person)

    • Use objectClass with OpenLDAP and other directories.
      Example: (objectClass=inetOrgPerson)

Ensure this filter accurately reflects how user entries are structured in your directory schema.

ides.config.auth.ldap.user-login-attribute

Specifies the LDAP attribute used to identify users by their login name.

  • Combined with user-object-filter to locate a unique user entry via LDAP search.

  • Default: uid

  • For Active Directory either sAMAccountName or userPrincipalName are recommended.

Ensure the attribute uniquely identifies user entries within the search scope.

ides.config.auth.ldap.user-additional-dn

Optional DN fragment prepended to base-dn when constructing user DNs (used in user searches).

  • Purpose: Narrows search or DN derivation to a specific organizational unit.

  • Example:
    If user-additional-dn = ou=users and base-dn = dc=example,dc=com,
    the search will target: ou=users,dc=example,dc=com

ides.config.auth.ldap.user-email-attribute

Specifies the LDAP attribute that contains the user's email address.

  • Purpose: Maps to the application’s internal email field.

  • Default: mail

  • Common alternatives: userPrincipalName, email

Must match the schema used in your LDAP directory.

Group sync and import

You can configure IDE Services with LDAP for user management in two ways:

  • Synchronization Mode — Users and group memberships are imported from LDAP on a defined schedule.

  • Authentication-Only Mode — Users are created on-demand upon successful login, no scheduled synchronization is performed.

Configure the required behavior by adding specific parameters to your IDE Services Server configuration file (application.yaml or values.yaml)

Synchronization mode

In this mode, the application periodically synchronizes user data and group memberships from the LDAP directory based on the distinguished names (DNs) of LDAP groups specified in the configuration. In addition to scheduled imports, users can also be imported or created automatically upon login.

Example:

tbe: auth: ldap: enabled: true url: 'ldap://localhost:10000' # ... other LDAP settings user-group-membership-attribute: 'memberOf' users: import: enabled: true provider: 'ldap' schedule: '0 */15 * * * *' # <-- every 15 min mapping: groups: - id: 'cn=developers,ou=groups' - id: 'cn=admins,ou=groups' admin-groups: - id: 'cn=admins,ou=groups' # <-- subset of groups
ides: config: auth: ldap: enabled: true url: 'ldap://localhost:10000' # ... other LDAP settings user-group-membership-attribute: 'memberOf' users: import: enabled: true provider: 'ldap' schedule: '0 */15 * * * *' # <-- every 15 min mapping: groups: - id: 'cn=developers,ou=groups' - id: 'cn=admins,ou=groups' admin-groups: - id: 'cn=admins,ou=groups' # <-- subset of groups
  • Users who are members of the specified LDAP groups are updated on every login and are also imported or updated according to the configured schedule.

  • Users not yet imported may still be created at login time, and their group memberships can be assigned on the fly, even if create-user-on-login is disabled.

  • LDAP directory serves as the single source for user data. Group memberships are kept in sync, and user records become read-only in the IDE Services user interface.

  • Group membership is evaluated based on the attribute specified in user-group-membership-attribute (e.g., memberOf).

  • Users listed in admin-groups are granted elevated privileges within IDE Services.

Authentication-only mode

In this mode, the application does not perform scheduled synchronization of users or groups. Instead, user accounts are created dynamically the first time a user successfully authenticates via LDAP.

Example:

tbe: auth: create-user-on-login: true ldap: enabled: true url: 'ldap://localhost:10000' # ... other LDAP settings users: import: enabled: false # default value
  • Users are not imported from LDAP groups on a schedule.

  • User records are created on-demand when a user logs in for the first time and passes authentication.

  • No LDAP group membership is used for assigning roles unless explicitly resolved during login.

  • Best suited for setups where LDAP is used solely for authentication, and user provisioning is handled within IDE Services.

Parameter

Description

tbe.auth.create-user-on-login

Enables automatic creation of a user record upon successful LDAP authentication, if the user does not yet exist in the system.

  • true: A new user is created dynamically at login time if authentication succeeds.

  • false (default): Only existing users can log in.

This option is recommended for Authentication-Only Mode when tbe.users.import.enabled: false.

tbe.auth.ldap.user-group-membership-attribute

Specifies the LDAP attribute on the user entry that lists the groups the user belongs to.

  • Default: memberOf

  • Active Directory: The memberOf attribute is available by default and lists all direct group memberships.

  • OpenLDAP: The memberOf attribute is not included by default. To use it, the memberof overlay must be enabled and configured on the server. This overlay automatically maintains reverse group membership references.

This attribute is used to resolve group-to-user associations when importing users or assigning roles based on group membership.

tbe.users.import.enabled

Controls whether periodic synchronization of users and groups from LDAP is enabled.

  • true – Enables scheduled LDAP import according to the configured cron schedule.

  • false – Disables scheduled import. Users can still be created on login if tbe.auth.create-user-on-login is enabled.

tbe.users.import.provider

Specifies the source system for user synchronization. Set this value to ldap to enable LDAP-based user import.

  • Required if tbe.users.import.enabled is set to true.

  • Other values are not supported in this context.

tbe.users.import.schedule

Defines the cron expression for how frequently the LDAP user import job runs.

Set the frequency to align with your LDAP server performance and load handling.

The schedule follows standard cron syntax with six fields (seconds may be required depending on system implementation).

Examples:

  • 0 */10 * * * * – Every 10 minutes

  • 0 0 * * * * – Every hour

  • 0 0 */3 * * * – Every 3 hours

  • 0 0 0 * * * – Daily at midnight

  • 0 0 7 * * * – Daily at 7:00 AM

  • 0 0 2 * * 1 – Every Monday at 2:00 AM

All users matching the configured user-object-filter will be fetched during each execution.

tbe.users.import.mapping.groups

Lists the LDAP groups to be used for user role mapping and filtering during synchronization.

  • groups – General list of user groups to be imported. All users who are members of any listed group will be synchronized.

  • admin-groups – Subset of groups whose members will be granted administrative privileges in IDE Services.

Group identifiers should be specified using relative distinguished names (DNs), excluding the base DN (specified by the tbe.auth.ldap.base-dn configuration property).

For example, cn=devs,ou=groups should be used as the group's mapping, when the group's full DN is cn=devs,ou=groups,dc=example,dc=com and the base DN is specified as dc=example,dc=com.

ides: config: auth: create-user-on-login: true ldap: enabled: true url: 'ldap://localhost:10000' # ... other LDAP settings users: import: enabled: false # default value
  • Users are not imported from LDAP groups on a schedule.

  • User records are created on-demand when a user logs in for the first time and passes authentication.

  • No LDAP group membership is used for assigning roles unless explicitly resolved during login.

  • Best suited for setups where LDAP is used solely for authentication, and user provisioning is handled within IDE Services.

Parameter

Description

ides.config.auth.create-user-on-login

Enables automatic creation of a user record upon successful LDAP authentication, if the user does not yet exist in the system.

  • true: A new user is created dynamically at login time if authentication succeeds.

  • false (default): Only existing users can log in.

This option is recommended for Authentication-Only Mode when ides.config.users.import.enabled: false.

ides.config.auth.ldap.user-group-membership-attribute

Specifies the LDAP attribute on the user entry that lists the groups the user belongs to.

  • Default: memberOf

  • Active Directory: The memberOf attribute is available by default and lists all direct group memberships.

  • OpenLDAP: The memberOf attribute is not included by default. To use it, the memberof overlay must be enabled and configured on the server. This overlay automatically maintains reverse group membership references.

This attribute is used to resolve group-to-user associations when importing users or assigning roles based on group membership.

ides.config.users.import.enabled

Controls whether periodic synchronization of users and groups from LDAP is enabled.

  • true – Enables scheduled LDAP import according to the configured cron schedule.

  • false – Disables scheduled import. Users can still be created on login if ides.config.auth.create-user-on-login is enabled.

ides.config.users.import.provider

Specifies the source system for user synchronization. Set this value to ldap to enable LDAP-based user import.

  • Required if ides.config.users.import.enabled is set to true.

  • Other values are not supported in this context.

ides.config.users.import.schedule

Defines the cron expression for how frequently the LDAP user import job runs.

Set the frequency to align with your LDAP server performance and load handling.

The schedule follows standard cron syntax with six fields (seconds may be required depending on system implementation).

Examples:

  • 0 */10 * * * * – Every 10 minutes

  • 0 0 * * * * – Every hour

  • 0 0 */3 * * * – Every 3 hours

  • 0 0 0 * * * – Daily at midnight

  • 0 0 7 * * * – Daily at 7:00 AM

  • 0 0 2 * * 1 – Every Monday at 2:00 AM

All users matching the configured user-object-filter will be fetched during each execution.

ides.config.users.import.mapping.groups

Lists the LDAP groups to be used for user role mapping and filtering during synchronization.

  • groups – General list of user groups to be imported. All users who are members of any listed group will be synchronized.

  • admin-groups – Subset of groups whose members will be granted administrative privileges in IDE Services.

Group identifiers should be specified using relative distinguished names (DNs), excluding the base DN (specified by the ides.config.auth.ldap.base-dn configuration property).

For example, cn=devs,ou=groups should be used as the group's mapping, when the group's full DN is cn=devs,ou=groups,dc=example,dc=com and the base DN is specified as dc=example,dc=com.

Prevent brute-force attacks with rate limiting

To protect against brute-force login attempts, the IDE Services applies rate limiting using two independent token buckets:

  • IP-based bucket: Limits authentication attempts from a single IP address within a defined time window.

  • Login-based bucket: Limits authentication attempts for a specific username within a defined time window.

An authentication attempt is allowed only if both buckets have available tokens. If either is exhausted, the attempt is denied until the corresponding window resets.

Configure the required behavior by adding specific parameters to your IDE Services Server configuration file (application.yaml or values.yaml)

Example:

tbe: auth: ldap: enabled: true url: 'ldap://localhost:10000' # ... other LDAP settings rate-limits: login: attempt-limit: 1 window-duration: 60s ip: attempt-limit: 1 window-duration: 60s

Parameter

Description

tbe.auth.ldap.rate-limits.login.attempt-limit

Maximum number of authentication attempts allowed for a specific login within the configured time window.

Default: 3

tbe.auth.ldap.rate-limits.login.window-duration

Time window over which failed login attempts are counted per username.

Default: 10s

tbe.auth.ldap.rate-limits.ip.attempt-limit

Maximum number of authentication attempts allowed from a single IP address within the configured time window.

Default: 30

tbe.auth.ldap.rate-limits.ip.window-duration

Time window over which failed login attempts are counted per IP address.

Default: 60s

ides: config: auth: ldap: enabled: true url: 'ldap://localhost:10000' # ... other LDAP settings rate-limits: login: attempt-limit: 1 window-duration: 60s ip: attempt-limit: 1 window-duration: 60s

Parameter

Description

ides.config.auth.ldap.rate-limits.login.attempt-limit

Maximum number of authentication attempts allowed for a specific login within the configured time window.

Default: 3

ides.config.auth.ldap.rate-limits.login.window-duration

Time window over which failed login attempts are counted per username.

Default: 10s

ides.config.auth.ldap.rate-limits.ip.attempt-limit

Maximum number of authentication attempts allowed from a single IP address within the configured time window.

Default: 30

ides.config.auth.ldap.rate-limits.ip.window-duration

Time window over which failed login attempts are counted per IP address.

Default: 60s

Additional parameters

Parameter

Description

tbe.auth.ldap.referral

Determines how the LDAP client handles referrals returned by the LDAP server. Referrals are pointers to other LDAP servers that may hold the requested data.

  • follow – Automatically follow the referral and attempt the operation on the referred LDAP server.

  • ignore – Do not follow referrals; treat them as if the referenced data is unavailable.

  • throw – Immediately throw an exception when a referral is encountered.

This setting is especially relevant in environments using directory forests or where entries may span multiple LDAP servers.

Default: ignore

tbe.auth.ldap.support-contact-link

Provides a link displayed on the login page for users to contact support if they experience login issues, such as LDAP authentication failures.

Can be either:

  • A URL to a helpdesk, documentation, or issue tracker (e.g., https://support.example.com).

  • A mailto: link for sending an email to the support team (e.g., mailto:support@example.com).

This link improves user experience by offering immediate help options in case of login errors.

Parameter

Description

ides.config.auth.ldap.referral

Determines how the LDAP client handles referrals returned by the LDAP server. Referrals are pointers to other LDAP servers that may hold the requested data.

  • follow – Automatically follow the referral and attempt the operation on the referred LDAP server.

  • ignore – Do not follow referrals; treat them as if the referenced data is unavailable.

  • throw – Immediately throw an exception when a referral is encountered.

This setting is especially relevant in environments using directory forests or where entries may span multiple LDAP servers.

Default: ignore

ides.config.auth.ldap.support-contact-link

Provides a link displayed on the login page for users to contact support if they experience login issues, such as LDAP authentication failures.

Can be either:

  • A URL to a helpdesk, documentation, or issue tracker (e.g., https://support.example.com).

  • A mailto: link for sending an email to the support team (e.g., mailto:support@example.com).

This link improves user experience by offering immediate help options in case of login errors.

01 September 2025