4.6. Active Directory

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

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.

Setting	Description
LDAP_ENABLED	Setting to enable or disable LDAP-based authentication. Default: False
LDAP_HOSTNAME	The URI of the LDAP server.
LDAP_USER_SEARCH	Domain to search for users who may authenticate.
LDAP_GROUP_SEARCH	Domain to search for groups to populate when mirroring groups
LDAP_MIRROR_GROUPS	If True, LDAP groups will be auto-populated (see below). Default: False
LDAP_ALWAYS_UPDATE_USER	If True, the fields of the user object will be updated with the latest values from the LDAP directory. default: True
LDAP_AUTHORIZE_ALL_USERS	If True, LDAPBackend will furnish permissions for any Django user. default: False
LDAP_BIND_AS_AUTHENTICATING_USER	If True, authentication will leave the LDAP connection bound as the authenticating user. default: False
LDAP_REFRESH_DN_ON_BIND	If True, it refreshes the DN attribute of the user. default: False
LDAP_CACHE_TIMEOUT	The amount of time, in seconds, a user’s group memberships and distinguished name are cached. default: 0
LDAP_CONNECTION_OPTIONS	A dictionary of options to pass to each connection to the LDAP server via LDAPObject.set_option().default: {}
LDAP_DENY_GROUP	The distinguished name of a group, authentication will fail for any user that belongs to this group. default: None
LDAP_FIND_GROUP_PERMS	If True, LDAPBackend looks up Django Groups matching LDAP group names, and assigns user permissions. default: False
LDAP_GLOBAL_OPTIONS	A dictionary of options to pass to ldap.set_option(). Keys are ldap.OPT_* constants. default: {}
LDAP_MIRROR_GROUPS_EXCEPT	It must be a list or other collection of group names. This will enable group mirroring. default: None
LDAP_PERMIT_EMPTY_PASSWORD	If True, authentication will be allowed with empty password. default: False
LDAP_REQUIRE_GROUP	The distinguished name of a group, authentication will fail for user not belonging to this group. default: None
LDAP_NO_NEW_USERS	Prevent the creation of new users during authentication. default: False
LDAP_START_TLS	If True, each connection to the LDAP server will enable TLS encryption over the standard LDAP port. default: False
LDAP_USER_QUERY_FIELD	when set, it is used to query the authenticating user in the database. If unset, it uses the username. default: None
LDAP_USER_ATTRLIST	A list of operational attributes to load for the authenticated user. default: None
LDAP_USER_DN_TEMPLATE	A string template that describes any user’s distinguished name based on the username. default: None
LDAP_USER_FLAGS_BY_GROUP	A mapping from boolean User field names to distinguished names of LDAP groups. default: {}

4.6.1.1. Example Configurations

LDAP_ENABLED=True

LDAP_HOSTNAME=ldap://localhost
LDAP_USER_SEARCH=cn=Users,dc=tech,dc=local
LDAP_GROUP_SEARCH=cn=Groups,dc=tech,dc=local
LDAP_MIRROR_GROUPS=False

4.6.2. Log in with an AD user

Enable LDAP by adding LDAP_ENABLED=true to /etc/sysconfig/ngeneahub. An AD user can log in to Ngenea Hub using their AD credentials.

The username corresponds to the AD user's sAMAccountName

A Ngenea Hub user account will be automatically created for that user.

Only AD users belonging to the LDAP_USER_SEARCH domain may authenticate. If LDAP_USER_SEARCH is not set, we use LDAP_DOMAIN to work it out, then all AD users may authenticate.

When LDAP is enabled, non-AD users can still be created and authenticated as before by Ngenea Hub through the usual method.

4.6.3. 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=CAB,dc=TIN,dc=EXAMPLE,dc=COM LDAP_GROUP_SEARCH=ou=Security,ou=LAB - Groups,dc=CAB,dc=TIN,dc=EXAMPLE,dc=COM

NOTE: When either LDAP_USER_SEARCH or LDAP_GROUP_SEARCH is constructed from domain e.g. LDAP_DOMAIN=cab.tin.example.com the search string will be dc=cab,dc=tin,dc=example,dc=com for whichever of these that is not set.

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 mirrored AD group. This WILL NOT change group membership in AD itself.