4.6. LDAP / Active Directory Login

This section describes the LDAP / Active Directory integration for Ngenea Hub.

A user can log in to Ngenea Hub using their username and password stored in the LDAP / Active Directory server rather than a manually created account in Ngenea Hub.

LDAP services are required to implement RFC2307 or RFC2307bis for provisioning of the LDAP schema.

As such, the username corresponds to the identity store user's sAMAccountName, etc.

Upon successful login, a Ngenea Hub user account will be automatically created for that user.

Where LDAP_MIRROR_GROUPS is configured, new groups are created in Ngenea Hub if not existing when the first user login is a member of the groups.

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

If LDAP_USER_SEARCH and/or LDAP_GROUP_SEARCH is not set, all LDAP / Active Directory users can authenticate via the setting of LDAP_DOMAIN.

When LDAP is enabled, internal Ngenea Hub users can still be created and internally authenticated.

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

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

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