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. LDAP Credentials

Configuration of LDAP is really to secure your credentials

ngeneahubctl manage config ldap auth --username "CN=John Doe,OU=Users,DC=example,DC=com" --password "your_password"

In this command, replace "CN=John Doe,OU=Users,DC=example,DC=com" with your LDAP username and "your_password" with your LDAP password.

4.6.2.1. Steps to Configure LDAP

1. Enable LDAP: Before you can configure LDAP, ensure that LDAP is enabled in your settings (LDAP_ENABLED environment variable). If LDAP is not enabled, the command will exit with a warning message.

2. Invoke the LDAP Configuration Command: To start the LDAP configuration process, you need to invoke the ldap auth command. This command is a sub-command of the config command.

3. Provide LDAP Credentials: The ldap auth command will prompt you to enter your LDAP username and password. These credentials are used to authenticate with the LDAP server. The username should be in the format: "CN=John Doe,OU=Users,DC=example,DC=com". If you don't provide these credentials as arguments, you will be prompted to enter them.

After running this command, your LDAP credentials will be encrypted and stored. You don't need to restart the server after this. If you want to change the credentials, you can run the command again.

4.6.3. Log in with an AD user

After enabling and configuring LDAP as above, 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.

When LDAP is enabled, non-AD users can still be created and authenticate as before.

4.6.4. Managing users and groups from AD in HUB

The user account which is generate 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.

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.

4.6.4.1. Authenticate LDAP with Kerberos

Using kerberos for authentication means that you will not need to provide a username and password for the LDAP server. The above LDAP settings still apply for operational LDAP access.

Authentication for LDAP is obtained via Kerberos. LDAP user and group enumeration is performed via the now authenticated (SASL) LDAP connection.

It is not required to configure LDAP authentication with ngeneahubctl manage config ldap auth in this configuration.

The following settings apply.

Setting	Description
KRB5_REALM	The Kerberos realm to use for authentication.
KERBEROS_SERVICE	The Kerberos service to use for authentication.
KRB5CCNAME	The location of the Kerberos ticket cache file set to KRB5CCNAME=FILE:/tmp/krb5cc_$(id -u)