LDAP configuration reference

1. Intro

LDAP authentication is based on the Symfony Security component authenticators for LDAP.

SuiteCRM extends some of Symfony’s services. Thus, most of the configuration will be similar to the one on core Symfony.

Please have in mind that the configuration to connect SuiteCRM to an LDAP provider will vary depending on:

The LDAP provider being used
How the LDAP provider is configured

This documentation describes the LDAP configuration options available in SuiteCRM. It is NOT a guide on how to configure LDAP.

2. Note on legacy configuration

Before starting to configure LDAP, please take into account the following:

The configuration described on this page:
- Is not used by v4 or v8 API login
- Does not read from legacy configuration
- Is the way to configure SuiteCRM login screen to use LDAP. Legacy configuration is not taken into account
The LDAP configuration available on SuiteCRM Administration > Password Management menu is only used by the legacy v4 API

This means that you may have to configure LDAP using .env.local (as described on the following sections) and , if you want to use v4 with LDAP, also configure LDAP using the Administration > Password Management menu of your instance.

3. Enabling LDAP authentication

To enable LDAP authentication change your .env.local and set:

AUTH_TYPE=ldap

⚠️ After making a change to your .env.local please be sure to run ./bin/console cache:clear from root or Repair and Rebuild from the Admin Menu.

4. LDAP connection configuration reference

SuiteCRM exposes some of Symfony’s LDAP configuration as env variables. The .env file has the default value for all the available variables. When configuring an instance add the variables you want to override to .env.local file.

Default .env LDAP connection config

###> LDAP CONFIG ###
LDAP_CONNECTION_STRING=~ # available from 8.7.0
LDAP_HOST=~
LDAP_PORT=389
LDAP_ENCRYPTION=tls
LDAP_PROTOCOL_VERSION=3
LDAP_REFERRALS=false
LDAP_DN_STRING=''
LDAP_QUERY_STRING=''
LDAP_SEARCH_DN=''
LDAP_SEARCH_PASSWORD=''

# All the following options are available from 8.7.0
# ldap debug logs go to php error log
LDAP_CONNECTION_OPTION_DEBUG_LEVEL=~
LDAP_CONNECTION_OPTION_API_INFO=~
LDAP_CONNECTION_OPTION_DEREF=~
LDAP_CONNECTION_OPTION_SIZELIMIT=~
LDAP_CONNECTION_OPTION_TIMELIMIT=~
LDAP_CONNECTION_OPTION_RESTART=~
LDAP_CONNECTION_OPTION_SERVER_CONTROLS=~
LDAP_CONNECTION_OPTION_CLIENT_CONTROLS=~
LDAP_CONNECTION_OPTION_API_FEATURE_INFO=~
LDAP_CONNECTION_OPTION_HOST_NAME=~
LDAP_CONNECTION_OPTION_ERROR_NUMBER=~
LDAP_CONNECTION_OPTION_ERROR_STRING=~
LDAP_CONNECTION_OPTION_MATCHED_DN=~

LDAP_CONNECTION_OPTION_TIMEOUT=~
LDAP_CONNECTION_OPTION_NETWORK_TIMEOUT=~
LDAP_CONNECTION_OPTION_X_TLS_CACERTDIR=~
LDAP_CONNECTION_OPTION_X_TLS_CACERTFILE=~
LDAP_CONNECTION_OPTION_X_TLS_CERTFILE=~
LDAP_CONNECTION_OPTION_X_TLS_CRL_ALL=~
LDAP_CONNECTION_OPTION_X_TLS_CRL_NONE=~
LDAP_CONNECTION_OPTION_X_TLS_CRL_PEER=~
LDAP_CONNECTION_OPTION_X_TLS_KEYFILE=~
LDAP_CONNECTION_OPTION_X_TLS_REQUIRE_CERT=~
LDAP_CONNECTION_OPTION_X_TLS_PROTOCOL_MIN=~
LDAP_CONNECTION_OPTION_X_TLS_CIPHER_SUITE=~
LDAP_CONNECTION_OPTION_X_TLS_RANDOM_FILE=~
LDAP_CONNECTION_OPTION_X_TLS_CRLFILE=~
LDAP_CONNECTION_OPTION_X_TLS_PACKAGE=~
LDAP_CONNECTION_OPTION_X_TLS_CRLCHECK=~
LDAP_CONNECTION_OPTION_X_TLS_DHFILE=~
LDAP_CONNECTION_OPTION_X_SASL_MECH=~
LDAP_CONNECTION_OPTION_X_SASL_REALM=~
LDAP_CONNECTION_OPTION_X_SASL_AUTHCID=~
LDAP_CONNECTION_OPTION_X_SASL_AUTHZID=~
LDAP_CONNECTION_OPTION_X_KEEPALIVE_IDLE=~
LDAP_CONNECTION_OPTION_X_KEEPALIVE_PROBES=~
LDAP_CONNECTION_OPTION_X_KEEPALIVE_INTERVAL=~
###< LDAP CONFIG ###

Base options

LDAP_HOST

The host for the LDAP instance

LDAP_PORT

The port for the LDAP instance (e.g. 389)

LDAP_ENCRYPTION

The type of encryption used to connect to LDAP, either: none, tls or ssl

LDAP_DN_STRING

The DN string used to identify the user in LDAP. It can have the username set as a variable, e.g.: 'cn={username},dc=example,dc=org'

LDAP_QUERY_STRING

Allows to set a search string to search for a user. The found DN will be the one used to validate the credentials.

LDAP_SEARCH_DN

A DN of another user that is going to be used to search for the DN.

LDAP_SEARCH_PASSWORD

Password for the user used in LDAP_SEARCH_DN

Connection options

All the following options are available from SuiteCRM 8.7.0

These options correspond to the options available in PHP’s ldap_set_option.

Please refer to ldap_set_option documentation for a description of each of the following options and expected values.

LDAP_CONNECTION_OPTION_DEBUG_LEVEL
- Set to LDAP_CONNECTION_OPTION_DEBUG_LEVEL=7 for max logging level
- The debug info is logged to the php error log
LDAP_CONNECTION_OPTION_API_INFO
LDAP_CONNECTION_OPTION_DEREF
LDAP_CONNECTION_OPTION_SIZELIMIT
LDAP_CONNECTION_OPTION_TIMELIMIT
LDAP_CONNECTION_OPTION_RESTART
LDAP_CONNECTION_OPTION_SERVER_CONTROLS
LDAP_CONNECTION_OPTION_CLIENT_CONTROLS
LDAP_CONNECTION_OPTION_API_FEATURE_INFO
LDAP_CONNECTION_OPTION_HOST_NAME
LDAP_CONNECTION_OPTION_ERROR_NUMBER
LDAP_CONNECTION_OPTION_ERROR_STRING
LDAP_CONNECTION_OPTION_MATCHED_DN
LDAP_CONNECTION_OPTION_TIMEOUT
LDAP_CONNECTION_OPTION_NETWORK_TIMEOUT
LDAP_CONNECTION_OPTION_X_TLS_CACERTDIR
LDAP_CONNECTION_OPTION_X_TLS_CACERTFILE
LDAP_CONNECTION_OPTION_X_TLS_CERTFILE
LDAP_CONNECTION_OPTION_X_TLS_CRL_ALL
LDAP_CONNECTION_OPTION_X_TLS_CRL_NONE
LDAP_CONNECTION_OPTION_X_TLS_CRL_PEER
LDAP_CONNECTION_OPTION_X_TLS_KEYFILE
LDAP_CONNECTION_OPTION_X_TLS_REQUIRE_CERT
LDAP_CONNECTION_OPTION_X_TLS_PROTOCOL_MIN
LDAP_CONNECTION_OPTION_X_TLS_CIPHER_SUITE
LDAP_CONNECTION_OPTION_X_TLS_RANDOM_FILE
LDAP_CONNECTION_OPTION_X_TLS_CRLFILE
LDAP_CONNECTION_OPTION_X_TLS_PACKAGE
LDAP_CONNECTION_OPTION_X_TLS_CRLCHECK
LDAP_CONNECTION_OPTION_X_TLS_DHFILE
LDAP_CONNECTION_OPTION_X_SASL_MECH
LDAP_CONNECTION_OPTION_X_SASL_REALM
LDAP_CONNECTION_OPTION_X_SASL_AUTHCID
LDAP_CONNECTION_OPTION_X_SASL_AUTHZID
LDAP_CONNECTION_OPTION_X_KEEPALIVE_IDLE
LDAP_CONNECTION_OPTION_X_KEEPALIVE_PROBES
LDAP_CONNECTION_OPTION_X_KEEPALIVE_INTERVAL

5. User auto-creation configuration reference

Context

User auto creation is disabled by default for LDAP.

When disabled you will only be able to authenticate users using LDAP if you first create them on SuiteCRM.

The auto-create option will auto create users from LDAP if they do not exist on SuiteCRM yet.

Please note that auto-created users will not have any password set on SuiteCRM and the external_auth_only is set to 1 (or true) by default.

Enabling user auto-creation

To enable LDAP user auto creation change your .env.local and set:

LDAP_AUTO_CREATE=enabled

Auto-create options

When enabling user auto-creation you also need to specify the configurations required to find the user in LDAP.

Like the other LDAP configuration options already covered, for the user auto-creation the .env file also contains the default values that you can override.

Default .env LDAP auto create config

###> LDAP AUTO CREATE CONFIG ###
LDAP_AUTO_CREATE=disabled
LDAP_PROVIDER_BASE_DN=''
LDAP_PROVIDER_SEARCH_DN=''
LDAP_PROVIDER_SEARCH_PASSWORD=''
LDAP_PROVIDER_DEFAULT_ROLES=ROLE_USER
LDAP_PROVIDER_UID_KEY=''
LDAP_PROVIDER_FILTER=''
###< LDAP AUTO CREATE CONFIG ###

Options reference

LDAP_PROVIDER_BASE_DN

The base DN used to search for the users

LDAP_PROVIDER_UID_KEY

The attribute on your LDAP entry to use as uid. This is used to but build a query like ({uid_key}={username})

LDAP_PROVIDER_FILTER

Optional. Allows to specify a query search for the user in LDAP. The default filter is ({uid_key}={username})

LDAP_PROVIDER_SEARCH_DN

A DN of another user that is going to be used to search the user we are currently trying to authenticate with.

LDAP_PROVIDER_SEARCH_PASSWORD

Password for the user used in LDAP_PROVIDER_SEARCH_DN

Mapping user fields

User auto-creation allows to define fields to be set on the user record based on attributes from LDAP.

This can be achieved using the following options.

Options

ldap.extra_fields

An array of strings with the key of the LDAP entry attributes/fields to retrieve. See example on next section.

ldap.autocreate.extra_fields_map

Defines how to map the LDAP fields to the fields in the user. See example on next section.

Configuration file

The configuration for extra fields is not done through .env. It needs to be done by overriding container parameters. This means that this configuration is not as easily configurable per environment.

The default configuration for extra fields is defined on config/services/ldap/ldap.yaml.

To override the configurations you need to copy the file over to the extensions folder on a path like extensions/<your-package>/config/services/ldap/ldap.yaml

Example of extra_fields and extra_fields_map configuration File: extensions/<your-package>/config/services/ldap/ldap.yaml

parameters:
  ldap.extra_fields: [ 'name', 'sn', 'email' ]
  ldap.autocreate.extra_fields_map:
    name: first_name
    sn: last_name
    email: email1

5. Fallback to native authentication

SuiteCRM allows to fallback to native authentication using the password set on the SuiteCRM instance for that user.

If a user has external_auth_only set to 1 (or true), the login will fail if the provided password does not match the one on LDAP or if there are any other problem with the authentication against LDAP.

On the other hand, if a user has external_auth_only set to 0 (or false) and the authentication against LDAP fails, the system will immediately try to authenticate against SuiteCRM’s native authentication.

6. Using Symfony Secrets

Please consider using symfony secrets for storing sensitive information, like passwords, etc.

See the Using Symfony Secrets guide for more information on how to add them.

7. More information

For more information about options on LDAP see the Symfony’s Security Component documentation

Please make sure to read the documentation of the Symfony version used on your version of SuiteCRM