Skip to content

Files

Latest commit

 

History

History
271 lines (215 loc) · 14.1 KB

proc_manage-ldap-setup.adoc

File metadata and controls

271 lines (215 loc) · 14.1 KB

LDAP Authentication Setup for {productname}

Lightweight Directory Access Protocol (LDAP) is an open, vendor-neutral, industry standard application protocol for accessing and maintaining distributed directory information services over an Internet Protocol (IP) network. {productname} supports using LDAP as an identity provider.

Considerations when enabling LDAP

Prior to enabling LDAP for your {productname} deployment, you should consider the following.

Existing {productname} deployments

Conflicts between usernames can arise when you enable LDAP for an existing {productname} deployment that already has users configured. For example, one user, alice, was manually created in {productname} prior to enabling LDAP. If the username alice also exists in the LDAP directory, {productname} automatically creates a new user, alice-1, when alice logs in for the first time using LDAP. {productname} then automatically maps the LDAP credentials to the alice account. For consistency reasons, this might be erroneous for your {productname} deployment. It is recommended that you remove any potentially conflicting local account names from {productname} prior to enabling LDAP.

Manual User Creation and LDAP authentication

When {productname} is configured for LDAP, LDAP-authenticated users are automatically created in {productname}'s database on first log in, if the configuration option FEATURE_USER_CREATION is set to true. If this option is set to false, the automatic user creation for LDAP users fails, and the user is not allowed to log in. In this scenario, the superuser needs to create the desired user account first. Conversely, if FEATURE_USER_CREATION is set to true, this also means that a user can still create an account from the {productname} login screen, even if there is an equivalent user in LDAP.

Configuring LDAP for {productname}

You can configure LDAP for {productname} by updating your config.yaml file directly and restarting your deployment. Use the following procedure as a reference when configuring LDAP for {productname}.

  1. Update your config.yaml file directly to include the following relevant information:

    # ...
AUTHENTICATION_TYPE: LDAP (1)
# ...
LDAP_ADMIN_DN: uid=<name>,ou=Users,o=<organization_id>,dc=<example_domain_component>,dc=com (2)
LDAP_ADMIN_PASSWD: ABC123 (3)
LDAP_ALLOW_INSECURE_FALLBACK: false (4)
LDAP_BASE_DN: (5)
  - dc=example
  - dc=com
LDAP_EMAIL_ATTR: mail (6)
LDAP_UID_ATTR: uid (7)
LDAP_URI: ldap://<example_url>.com (8)
LDAP_USER_FILTER: (memberof=cn=developers,ou=Users,dc=<domain_name>,dc=com) (9)
LDAP_USER_RDN: (10)
  - ou=people
LDAP_SECONDARY_USER_RDNS: (11)
    - ou=<example_organization_unit_one>
    - ou=<example_organization_unit_two>
    - ou=<example_organization_unit_three>
    - ou=<example_organization_unit_four>
# ...

    1. Required. Must be set to LDAP.

    2. Required. The admin DN for LDAP authentication.

    3. Required. The admin password for LDAP authentication.

    4. Required. Whether to allow SSL/TLS insecure fallback for LDAP authentication.

    5. Required. The base DN for LDAP authentication.

    6. Required. The email attribute for LDAP authentication.

    7. Required. The UID attribute for LDAP authentication.

    8. Required. The LDAP URI.

    9. Required. The user filter for LDAP authentication.

    10. Required. The user RDN for LDAP authentication.

    11. Optional. Secondary User Relative DNs if there are multiple Organizational Units where user objects are located.

  2. After you have added all required LDAP fields, save the changes and restart your {productname} deployment.

Enabling the LDAP_RESTRICTED_USER_FILTER configuration field

The LDAP_RESTRICTED_USER_FILTER configuration field is a subset of the LDAP_USER_FILTER configuration field. When configured, this option allows {productname} administrators the ability to configure LDAP users as restricted users when {productname} uses LDAP as its authentication provider.

Use the following procedure to enable LDAP restricted users on your {productname} deployment.

Prerequisites

  • Your {productname} deployment uses LDAP as its authentication provider.

  • You have configured the LDAP_USER_FILTER field in your config.yaml file.

Procedure

  1. In your deployment’s config.yaml file, add the LDAP_RESTRICTED_USER_FILTER parameter and specify the group of restricted users, for example, members:

    # ...
AUTHENTICATION_TYPE: LDAP
# ...
FEATURE_RESTRICTED_USERS: true (1)
# ...
LDAP_ADMIN_DN: uid=<name>,ou=Users,o=<organization_id>,dc=<example_domain_component>,dc=com
LDAP_ADMIN_PASSWD: ABC123
LDAP_ALLOW_INSECURE_FALLBACK: false
LDAP_BASE_DN:
    - o=<organization_id>
    - dc=<example_domain_component>
    - dc=com
LDAP_EMAIL_ATTR: mail
LDAP_UID_ATTR: uid
LDAP_URI: ldap://<example_url>.com
LDAP_USER_FILTER: (memberof=cn=developers,ou=Users,o=<example_organization_unit>,dc=<example_domain_component>,dc=com)
LDAP_RESTRICTED_USER_FILTER: (<filterField>=<value>) (2)
LDAP_USER_RDN:
    - ou=<example_organization_unit>
    - o=<organization_id>
    - dc=<example_domain_component>
    - dc=com
# ...

    1. Must be set to true when configuring an LDAP restricted user.

    2. Configures specified users as restricted users.

  2. Start, or restart, your {productname} deployment.

After enabling the LDAP_RESTRICTED_USER_FILTER feature, your LDAP {productname} users are restricted from reading and writing content, and creating organizations.

Enabling the LDAP_SUPERUSER_FILTER configuration field

With the LDAP_SUPERUSER_FILTER field configured, {productname} administrators can configure Lightweight Directory Access Protocol (LDAP) users as superusers if {productname} uses LDAP as its authentication provider.

Use the following procedure to enable LDAP superusers on your {productname} deployment.

Prerequisites

  • Your {productname} deployment uses LDAP as its authentication provider.

  • You have configured the LDAP_USER_FILTER field field in your config.yaml file.

Procedure

  1. In your deployment’s config.yaml file, add the LDAP_SUPERUSER_FILTER parameter and add the group of users you want configured as super users, for example, root:

    # ...
AUTHENTICATION_TYPE: LDAP
# ...
LDAP_ADMIN_DN: uid=<name>,ou=Users,o=<organization_id>,dc=<example_domain_component>,dc=com
LDAP_ADMIN_PASSWD: ABC123
LDAP_ALLOW_INSECURE_FALLBACK: false
LDAP_BASE_DN:
    - o=<organization_id>
    - dc=<example_domain_component>
    - dc=com
LDAP_EMAIL_ATTR: mail
LDAP_UID_ATTR: uid
LDAP_URI: ldap://<example_url>.com
LDAP_USER_FILTER: (memberof=cn=developers,ou=Users,o=<example_organization_unit>,dc=<example_domain_component>,dc=com)
LDAP_SUPERUSER_FILTER: (<filterField>=<value>) (1)
LDAP_USER_RDN:
    - ou=<example_organization_unit>
    - o=<organization_id>
    - dc=<example_domain_component>
    - dc=com
# ...

    1. Configures specified users as superusers.

  2. Start, or restart, your {productname} deployment.

After enabling the LDAP_SUPERUSER_FILTER feature, your LDAP {productname} users have superuser privileges. The following options are available to superusers:

  • Manage users

  • Manage organizations

  • Manage service keys

  • View the change log

  • Query the usage logs

  • Create globally visible user messages

Common LDAP configuration issues

The following errors might be returned with an invalid configuration.

  • Invalid credentials. If you receive this error, the Administrator DN or Administrator DN password values are incorrect. Ensure that you are providing accurate Administrator DN and password values.

  • *Verification of superuser %USERNAME% failed. This error is returned for the following reasons:

    • The username has not been found.

    • The user does not exist in the remote authentication system.

    • LDAP authorization is configured improperly.

  • Cannot find the current logged in user. When configuring LDAP for {productname}, there may be situations where the LDAP connection is established successfully using the username and password provided in the Administrator DN fields. However, if the current logged-in user cannot be found within the specified User Relative DN path using the UID Attribute or Mail Attribute fields, there are typically two potential reasons for this:

    • The current logged in user does not exist in the User Relative DN path.

    • The Administrator DN does not have rights to search or read the specified LDAP path.

      To fix this issue, ensure that the logged in user is included in the User Relative DN path, or provide the correct permissions to the Administrator DN account.

LDAP configuration fields

For a full list of LDAP configuration fields, see LDAP configuration fields