5.6. LDAP / Active Directory Login

Ngenea Hub provides integration with LDAP (Lightweight Directory Access Protocol) and Active Directory (AD), enabling users to log in using their existing credentials (username and password) from an LDAP or Active Directory server, rather than creating a manual account in Ngenea Hub. This integration streamlines the authentication process for users and administrators alike.

Key Concepts:

  • LDAP/Active Directory: These are systems used to store and manage user data, including usernames, passwords, and other information like group memberships. Most organizations use these systems to manage access to various resources within their network.

  • sAMAccountName: In Active Directory, the sAMAccountName is the unique identifier (or username) for a user. When using LDAP/Active Directory authentication in Ngenea Hub, this username is used to link the Ngenea Hub account with the user’s identity in the LDAP/Active Directory system.

  • Automatic Account Creation: When a user logs in successfully using their LDAP/AD credentials, Ngenea Hub will automatically create a corresponding user account in the system. This eliminates the need for manual user account creation.

Configuration Details:

  • LDAP Schema Requirements: To ensure proper integration, your LDAP or Active Directory service must be configured to support RFC2307 or RFC2307bis. These RFC standards define how user and group information should be stored and accessed in the directory.

Administrators can assign Hub groups and permissions prior to subsequent logins for ease of use. Refer to LDAP_MIRROR_GROUPS in Managing users and groups from AD in HUB

  • LDAP_MIRROR_GROUPS: If this setting is enabled, Ngenea Hub will automatically create new groups corresponding to those found in Active Directory or LDAP, if the groups don’t already exist in Ngenea Hub. This occurs when a user logs in for the first time and is a member of any groups that do not yet exist in Ngenea Hub.

  • Assigning Groups and Permissions: Administrators can pre-assign Ngenea Hub groups and permissions before the user logs in for the first time. This allows for a smoother user experience as permissions will be automatically granted when the user logs in. More details about this can be found in the section titled “Managing Users and Groups from AD in Hub.”

  • LDAP_USER_SEARCH and LDAP_GROUP_SEARCH: These settings control how users and groups are searched within your LDAP or Active Directory server. If these are not configured, all users from the LDAP/AD server can authenticate in Ngenea Hub, as long as the LDAP_DOMAIN setting is provided.

Internal User Authentication:

  • Even when LDAP integration is enabled, Ngenea Hub allows the creation and internal authentication of local users (i.e., users who do not exist in the LDAP/Active Directory system). This ensures flexibility in user management.

5.6.1. Configuration

  • The following settings control LDAP configuration.

  • The following are set in the main configuration file for Ngenea Hub at /etc/sysconfig/ngeneahub. Any setting which doesn’t specify a default is required when LDAP_ENABLED is true.

  • After changing settings in /etc/sysconfig/ngeneahub a Hub restart is required to reflect the changes applied.

Note: The table on LDAP settings needs to be added.

5.6.1.1. Example Configurations

No whitespace must be present in the below configurations.

LDAP

LDAP_ENABLED=True
LDAP_DOMAIN=ldap.example.com
LDAP_HOSTNAME=ldap://ldap.example.com:389

LDAP enumerating specific User and Group membership

LDAP_ENABLED=True
LDAP_DOMAIN=my.ldap.example.com
LDAP_HOSTNAME=ldap://ldap.example.com:389
LDAP_USER_SEARCH=cn=Users,dc=hubusers,dc=example,dc=com
LDAP_GROUP_SEARCH=cn=Groups,dc=hubgroup,dc=example,dc=com

LDAPS

LDAP_ENABLED=True
LDAP_DOMAIN=ldap.example.com
LDAP_HOSTNAME=ldaps://ldap.example.com:636
LDAP_GLOBAL_OPTIONS=OPT_X_TLS_REQUIRE_CERT:OPT_X_TLS_ALLOW

LDAP + STARTTLS

LDAP_ENABLED=True
LDAP_DOMAIN=ldap.example.com
LDAP_HOSTNAME=ldap://ldap.example.com:389
LDAP_START_TLS=true
LDAP_GLOBAL_OPTIONS=OPT_X_TLS_REQUIRE_CERT:OPT_X_TLS_ALLOW

5.6.2. Managing users and groups from AD in HUB

The user account which is generated for an AD user behaves the same as any other Ngenea Hub user. This means it can be assigned to Ngenea Hub groups, and will gain the permissions from those groups.

By default, a new AD user will not belong to any groups, and therefore will not have any permissions. A privileged user will need to assign the user to any appropriate Ngenea Hub groups.

If LDAP_MIRROR_GROUPS is enabled, then when a user logs in to Ngenea Hub, groups will be automatically be created for any AD groups the user belongs to (if the group doesn’t already exist), and the user will be assigned to those groups.

Only groups belonging to the LDAP_GROUP_SEARCH domain will be populated. If LDAP_USER_SEARCH is not set, we use LDAP_DOMAIN to work it out, then all AD groups that authenticated users belong to would be created. This is usually not what you want. Example of explicit search terms:

LDAP_USER_SEARCH=cn=Users,dc=hubusers,dc=example,dc=com

LDAP_GROUP_SEARCH=cn=Groups,dc=hubgroup,dc=example,dc=com

NOTE: When either LDAP_USER_SEARCH or LDAP_GROUP_SEARCH is not set, the search is constructed from domain e.g. LDAP_DOMAIN=ldap.example.com the search string will be dc=ldap,dc=example,dc=com.

Mirrored AD groups behave the same as any other Ngenea Hub group, meaning permissions can be assigned to them to apply role-based access controls (RBAC). By default, mirrored AD groups will have no permissions assigned.

Any user can be assigned to a Hub mirrored AD group. Assigning a user to a Hub mirrored group does not change group membership in AD.

How can I manage my Hub users and groups using AD?

  1. What settings are required?

    LDAP_MIRROR_GROUPS=True

    This will create an AD group in Hub for every group the user is a member of.

  2. If a user is added or removed from a group in AD, when is this reflected in Hub?

    AD changes are not immediately reflected in Hub.

    If a user is added to an AD group, the group membership for the individual user is updated on next authentication (API or UI login).

    If a user is removed from an AD group, the group membership for the individual user is updated on next authentication (API or UI login).

    Example:

    • If user1 has been added to a group in AD, the Hub state will not reflect the AD changes viewed by user2 until user1 logs in and user2 refreshes their view of users and groups.

    • If user1 has been removed from a group in AD, the Hub state will not reflect the AD changes viewed by user2 until user1 logs in and user2 refreshes their view of users and groups.

  3. How can I limit the groups created in Hub when LDAP_MIRROR_GROUPS=True

    Create a Hub specific OU in AD.

    Create groups to mirror to Hub in the OU.

    Add the required users in the ou=Hub/<groups>

    Only the groups in the ou=Hub will be mirrored to Hub on login.

  4. How do I set up the groups in readiness for future user logins?

    Create an AD user.

    Log the user in.

    Initially the AD user will not be granted permissions.

    As the Hub admin, set the permissions on the groups.

    Log out the user AD user and on next login they will be assigned to the groups and pick up the set permissions.

    When future users log in, they will be assigned to the groups and pick up the set permissions on login.

  5. If a user or group is deleted from AD how is this reflected in Hub?

    Users deleted from AD are not automatically deleted from Hub.

    The correlating Hub user account is unable to authenticate with Hub.

    Groups deleted from AD are not automatically deleted from Hub.

    Users who are currently logged in will retain security permissions until the group is deleted from Hub.

    Systems administrators must ensure to delete users and groups from Hub after their removal from AD.

  6. Does changing the password for a user affect the user hub?

    Hub does not store credentials for AD users.

    AD users who log in to Hub are authenticated against AD prior to allowing the user to login.

    If Hub cannot contact AD to authenticate the user, the user is not allowed to login.

  7. Does user and group management in Hub affect AD?

    No, Hub ‘mirrors’ the group membership on login, but the mirror is only from AD to Hub.

    There are no updates pushed from Hub to AD.