Authenticate OpsCenter users with LDAP

The Lightweight Directory Access Protocol (LDAP) is a standard way of authenticating users across applications. OpsCenter supports LDAP authentication for external LDAP services.

When you enable LDAP authentication in OpsCenter, users that are managed by external LDAP servers can be authenticated by OpsCenter. DataStax Enterprise (DSE) supports LDAP as well. See Defining an LDAP Scheme.

LDAP must be configured for both DSE and OpsCenter if you plan to use LDAP with both applications. DSE and OpsCenter can share the same underlying user base accessed through LDAP or Active Directory, but those applications do not share their LDAP configuration settings. LDAP configuration settings for DSE and OpsCenter are nearly identical.

Supported LDAP servers

OpsCenter LDAP requires a running LDAP v3 server. The supported LDAP servers are:

Microsoft Active Directory (Windows 2008 or 2012)
OpenLDAP 2.4.x
Oracle Directory Server Enterprise Edition 11.1.1.7.0

LDAP group mapping

To authenticate LDAP users to OpsCenter, at least one of the user’s assigned groups must map to a role with the same name in OpsCenter. If none of the groups match, authentication fails.

Upon successful authentication, OpsCenter grants the user the permissions associated with the mapped role in OpsCenter. If a user belongs to multiple mapped LDAP groups, the user is granted the permissions for all of their mapped roles.

Role mapping is defined in the OpsCenter LDAP configuration:

The admin_group_name option explicitly defines LDAP group names that map to OpsCenter admin roles. OpsCenter automatically creates roles for each group name specified in admin_group_name.
The group_search_type option determines how LDAP group membership is retrieved from the LDAP server for non-admin roles:
- directory_search (default): For successful authentication, the distinguished name (DN) set in the group_search_filter_with_dn option must return a list of LDAP groups that matches at least one OpsCenter role.
- memberof_search: For successful authentication, the list of LDAP roles provided by a user’s memberOf attribute must match at least one OpsCenter role. The memberOf attribute is set in the user_memberof_attribute option.
You must create roles in OpsCenter for non-admin LDAP groups that require access to OpsCenter.

Add roles for LDAP users

For each non-admin LDAP group that requires access to OpsCenter, create a corresponding role in OpsCenter and configure the appropriate permissions. This isn’t necessary for admin groups because OpsCenter automatically creates roles for those groups.

Log in to OpsCenter with an OpsCenter admin user.

Admin permissions are required to create and manage roles in OpsCenter.

If you haven’t enabled any authentication strategy in OpsCenter, you must enable default authentication before you can log in as an admin user and create roles.
Click Settings, and then click Roles.

The Manage Roles dialog appears.
Click Add Role.

When LDAP is enabled, you can only manage roles in OpsCenter. User management is disabled in OpsCenter because user management is handled by the LDAP server. If you need to change a user’s role assignments when LDAP is enabled, you must change their group membership on the LDAP server.

If you delete a role in OpsCenter, the mapping is invalidated and users with that role lose the associated permissions. If a user has no other roles, they lose access to OpsCenter entirely.
Select a cluster.
Enter a role name that matches an LDAP group name.

OpsCenter LDAP supports non-ASCII character sets in role names. By extension, non-ASCII character sets are also supported in user names provided by the LDAP server.
Select the appropriate permissions.

You can edit role permissions at any time in OpsCenter. For existing users, the new permissions take effect the next time that they authenticate to OpsCenter.
Click Save.

Configure LDAP for OpsCenter

The OpsCenter LDAP configuration is flexible with many options. For demonstration purposes, these steps configure a basic LDAP authentication example that searches for users in user and group categories.

If you are converting to LDAP from standard OpsCenter authentication, delete the old passwd.db file.
Edit the opscenterd.conf file.

The location of this file depends on the type of installation:
- Package installations: /etc/opscenter/opscenterd.conf
- Tarball installations: INSTALL_DIRECTORY/conf/opscenterd.conf

Add an [authentication] section with the following options:

Option Description

Option	Description
`password_db`	Contains the required OpsCenter user role information. The default directories are as follows: Package installations: `/usr/share/opscenter` where `sqlite3.db` is stored Tarball installations: `install_directory/passwd.db`
`enabled`	Set to `True` to enable LDAP authentication.
`authentication_method`	Set to `LDAP`, regardless if configuring Active Directory.

password_db

Contains the required OpsCenter user role information. The default directories are as follows:

Package installations: /usr/share/opscenter where sqlite3.db is stored
Tarball installations: install_directory/passwd.db

enabled

Set to True to enable LDAP authentication.

authentication_method

Set to LDAP, regardless if configuring Active Directory.

For example:

[authentication]
password_db = ./passwd.db
enabled = True
authentication_method = LDAP

Add an [ldap] section to opscenterd.conf with the relevant LDAP server options for your environment.

The following table lists commonly used options. For all options, see OpsCenter configuration properties. For examples, see Example: SSL LDAP implementation and Example: Active Directory (AD) implementation.

Option Description

Option	Description
`server_host`	The host name of the LDAP server.
`server_port`	The OpsCenter port on which the LDAP server listens: `389`: Default port for non-SSL LDAP and AD. `636`: Default port for SSL LDAP and AD.
`hostname_verification`	Whether hostname verification should happen for SSL/TLS connections. For example: `hostname_verification = True`.
`uri_scheme`	In LDAP v2 environments, TLS is normally started using the LDAP Secure URI scheme instead of the LDAP URI scheme. OpenLDAP command line tools allow either scheme to be used with the `-H` and `URI ldap.conf(5)` options. Defaults: `ldap` if `ldap_security = None` `ldaps` if `ldap_security = SSL` or `TLS`
`search_dn`	The username of the user that is used to search for other users on the LDAP server. When a user attempts to authenticate with LDAP, OpsCenter searches for the user in LDAP to discover whether the user exists and which roles the user is associated with. The only permission that the search user needs to have in the LDAP system is the ability to perform LDAP searches. If you omit `search_dn` and `search_password`, which constitute the search user entry point for locating users in LDAP, then the LDAP server connection attempts to make an anonymous bind to perform the user search.
`search_password`	The password of the `search_dn` user.
`user_search_base`	The search base for your domain, used to look up users. Set the `ou` and `dc` elements for your LDAP domain. For example: `ou=users,dc=domain,dc=top level domain` or the more specific `ou=users,dc=example,dc=com`. Active Directory uses a different user search base. For example: `CN=search,CN=Users,DC=Active Directory domain name,DC=internal` or the more specific `CN=search,CN=Users,DC=example-sales,DC=internal`.
`user_search_filter`	The LDAP search filter used to uniquely identify a user. The default value `(uid={0})` looks for a user by unique user identifier. The value of the `{0}` variable is the username provided when logging in to OpsCenter. When using Active Directory, set the filter to `(sAMAccountName={0})`. There is a known limitation in OpsCenter when using search filters for Active Directory. See troubleshooting OpsCenter authentication issues.
`group_search_base`	The LDAP search base used to find a group. For example: `ou=groups,dc=qaldap,dc=datastax,dc=lan`.
`group_search_filter`	Deprecated. Use `group_search_filter_with_dn` instead. The LDAP search filter used to find a user’s group. The following example filters `group_search_base` for members based on `cn`: `(member=cn={0},ou=users,dc=nodomain)`. For existing Active Directory implementations that have this configuration option already set, `group_search_filter_with_dn` overwrites the returned value with the user’s DN.
`group_search_filter_with_dn`	The LDAP search filter that is used to find a user’s group. Uses the full user’s `DN` from a user search. For example: `(member={0})`. Overrides the deprecated `group_search_filter`.
`group_name_attribute`	The LDAP field name used to identify a group’s name. For example: `cn`.
`admin_group_name`	An explicit mapping for the OpsCenter admin role. Provide one or more admin group names, using comma-separation for multiple group names. For example: `admin,superusers`. OpsCenter automatically creates roles with admin permissions for each group name specified in `admin_group_name`. Escape restricted characters, such as commas, in group names. For example, two admin groups `foo , bar` and `baz` are specified as `foo \, bar, baz`.
`user_memberof_attribute`	Set to the attribute on the user entry containing group membership information. Set this option when using a `memberof_search` for the `group_search_type`. OpsCenter allows for an alternate method of determining a user’s role: When using `memberof_search`, rather than doing a directory search in LDAP for any roles that match the user, only the user is inspected. You can specify which attribute for a user is inspected. For example, you can define a user with an attribute like `opscenter_role`, and then populate it with the user’s role in OpsCenter. Specify the value of the new attribute so that OpsCenter can inspect the correct user attribute.
`group_search_type`	Defines how group membership is determined for a user. Available options: `directory_search` (default): Perform a subtree search of `group_search_base` using `group_search_filter_with_dn` to filter the results. `memberof_search`: Get groups from a user’s `memberOf` attribute on the LDAP server, as specified in the `user_memberof_attribute` option. To use `memberof_search`, the directory server must support `memberOf`. The `group_search_base` and `group_search_filter_with_dn` options aren’t required. For more information, see LDAP group mapping.
`user_memberof_stores_dn`	Set to `True` if the value of the `memberOf` attribute in your LDAP directory is distinguished names of groups. This option must be set to `True` when configuring Active Directory, OpenLDAP, or when any other LDAP implementation that returns a DN for the `memberOf` attribute value. Set to `False` if the value of `user_memberof_attribute` is an attribute that contains 0 or more group names corresponding to roles in OpsCenter. For example, if `user_memberof_attribute` is set to `employeeType`, you would set `user_memberof_stores_dn` to `False` because the `employeeType` attribute value isn’t a distinguished name. If authentication fails when `user_memberof_stores_dn` is `False` and OpsCenter suspects the group name might be a DN, a warning is logged: `[opscenterd] WARN: It looks like you might be using Active Directory for authentication. You may need to set the 'user_memberof_stores_dn' config value to True and set the group_name_attribute config value appropriately in opscenterd.conf.` Default: `False`
`ldap_security`	The type of security to use with LDAP: `None`: Don’t use TLS or SSL, and set `uri_scheme` to `LDAP`. `TLS`: Use TLS, and set `uri_scheme` to `LDAPS`. `SSL`: Use SSL, and set `uri_scheme` to `LDAPS`.
`truststore`	Path to the truststore for SSL certificates.
`truststore_type`	Type of the truststore. Default: `JKS` (Java Keystore)
`truststore_pass`	The password to access the truststore.
`enforce_single_user_search_result`	Whether to return an error when multiple entries are returned from a user search after all applicable referrals are followed. Set to `False` if `user_search_base` isn’t confined to one Organizational Unit (OU). Default: `True`
`connection_timeout`	The number of seconds to wait before concluding that the LDAP server is down. Default: `20`

server_host

The host name of the LDAP server.

server_port

The OpsCenter port on which the LDAP server listens:

389: Default port for non-SSL LDAP and AD.
636: Default port for SSL LDAP and AD.

hostname_verification

Whether hostname verification should happen for SSL/TLS connections. For example: hostname_verification = True.

uri_scheme

In LDAP v2 environments, TLS is normally started using the LDAP Secure URI scheme instead of the LDAP URI scheme. OpenLDAP command line tools allow either scheme to be used with the -H and URI ldap.conf(5) options.

Defaults:

ldap if ldap_security = None
ldaps if ldap_security = SSL or TLS

search_dn

The username of the user that is used to search for other users on the LDAP server.

When a user attempts to authenticate with LDAP, OpsCenter searches for the user in LDAP to discover whether the user exists and which roles the user is associated with. The only permission that the search user needs to have in the LDAP system is the ability to perform LDAP searches.

If you omit search_dn and search_password, which constitute the search user entry point for locating users in LDAP, then the LDAP server connection attempts to make an anonymous bind to perform the user search.

search_password

The password of the search_dn user.

user_search_base

The search base for your domain, used to look up users.

Set the ou and dc elements for your LDAP domain. For example: ou=users,dc=domain,dc=top level domain or the more specific ou=users,dc=example,dc=com.

Active Directory uses a different user search base. For example: CN=search,CN=Users,DC=Active Directory domain name,DC=internal or the more specific CN=search,CN=Users,DC=example-sales,DC=internal.

user_search_filter

The LDAP search filter used to uniquely identify a user.

The default value (uid={0}) looks for a user by unique user identifier. The value of the {0} variable is the username provided when logging in to OpsCenter. When using Active Directory, set the filter to (sAMAccountName={0}).

There is a known limitation in OpsCenter when using search filters for Active Directory. See troubleshooting OpsCenter authentication issues.

group_search_base

The LDAP search base used to find a group. For example: ou=groups,dc=qaldap,dc=datastax,dc=lan.

group_search_filter

Deprecated. Use group_search_filter_with_dn instead.

The LDAP search filter used to find a user’s group. The following example filters group_search_base for members based on cn: (member=cn={0},ou=users,dc=nodomain). For existing Active Directory implementations that have this configuration option already set, group_search_filter_with_dn overwrites the returned value with the user’s DN.

group_search_filter_with_dn

The LDAP search filter that is used to find a user’s group. Uses the full user’s DN from a user search. For example: (member={0}).

Overrides the deprecated group_search_filter.

group_name_attribute

The LDAP field name used to identify a group’s name. For example: cn.

admin_group_name

An explicit mapping for the OpsCenter admin role. Provide one or more admin group names, using comma-separation for multiple group names. For example: admin,superusers.

OpsCenter automatically creates roles with admin permissions for each group name specified in admin_group_name.

Escape restricted characters, such as commas, in group names. For example, two admin groups foo , bar and baz are specified as foo \, bar, baz.

user_memberof_attribute

Set to the attribute on the user entry containing group membership information. Set this option when using a memberof_search for the group_search_type.

OpsCenter allows for an alternate method of determining a user’s role: When using memberof_search, rather than doing a directory search in LDAP for any roles that match the user, only the user is inspected. You can specify which attribute for a user is inspected. For example, you can define a user with an attribute like opscenter_role, and then populate it with the user’s role in OpsCenter. Specify the value of the new attribute so that OpsCenter can inspect the correct user attribute.

group_search_type

Defines how group membership is determined for a user.

Available options:

directory_search (default): Perform a subtree search of group_search_base using group_search_filter_with_dn to filter the results.
memberof_search: Get groups from a user’s memberOf attribute on the LDAP server, as specified in the user_memberof_attribute option. To use memberof_search, the directory server must support memberOf. The group_search_base and group_search_filter_with_dn options aren’t required.

For more information, see LDAP group mapping.

user_memberof_stores_dn

Set to True if the value of the memberOf attribute in your LDAP directory is distinguished names of groups. This option must be set to True when configuring Active Directory, OpenLDAP, or when any other LDAP implementation that returns a DN for the memberOf attribute value.

Set to False if the value of user_memberof_attribute is an attribute that contains 0 or more group names corresponding to roles in OpsCenter. For example, if user_memberof_attribute is set to employeeType, you would set user_memberof_stores_dn to False because the employeeType attribute value isn’t a distinguished name.

If authentication fails when user_memberof_stores_dn is False and OpsCenter suspects the group name might be a DN, a warning is logged: [opscenterd] WARN: It looks like you might be using Active Directory for authentication. You may need to set the 'user_memberof_stores_dn' config value to True and set the group_name_attribute config value appropriately in opscenterd.conf.

Default: False

ldap_security

The type of security to use with LDAP:

None: Don’t use TLS or SSL, and set uri_scheme to LDAP.
TLS: Use TLS, and set uri_scheme to LDAPS.
SSL: Use SSL, and set uri_scheme to LDAPS.

truststore

Path to the truststore for SSL certificates.

truststore_type

Type of the truststore.

Default: JKS (Java Keystore)

truststore_pass

The password to access the truststore.

enforce_single_user_search_result

Whether to return an error when multiple entries are returned from a user search after all applicable referrals are followed.

Set to False if user_search_base isn’t confined to one Organizational Unit (OU).

Default: True

connection_timeout

The number of seconds to wait before concluding that the LDAP server is down.

Default: 20

Restart OpsCenter for the changes to take effect.

Example: SSL LDAP implementation

The following example configuration reflects a typical SSL LDAP (OpenLDAP or Oracle) implementation.

The server_port value of 636 is for an SSL configuration.

If the search_dn and search_password options are omitted, LDAP attempts to make an anonymous bind to perform the user search.

This example configuration attempts to authenticate a user by searching in user categories (user_search_base and user_search_filter) and group categories (group_search_base and group_search_filter). Notice that the group_search_type is directory_search.

The user_search_base and user_search_filter options are commented out because they are only applicable to an Active Directory (AD) configuration.

[authentication]
password_db = ./passwd.db
enabled = True
authentication_method = LDAP

[ldap]
server_host = ldap.myCompany.lan
server_port = 636
hostname_verification = true
uri_scheme = ldaps
search_dn = cn=admin,dc=devldap,dc=datastax,dc=lan
search_password = ****
user_search_base = ou=users,dc=devldap,dc=datastax,dc=lan
user_search_filter = (uid=\{0})
#user_search_base = CN=search,CN=Users,DC=datastax,DC=internal # AD base
#user_search_filter = (sAMAccountName=\{0}) # AD filter
group_search_base = ou=users,dc=devldap,dc=datastax,dc=lan
group_search_filter_with_dn = (member=\{0})
group_name_attribute = cn
group_search_type = directory_search
admin_group_name = superusers,superusers2
ldap_security = SSL_TLS
truststore_type = JKS
truststore = ./truststore.jks
truststore_pass = secret

Example: Active Directory (AD) implementation

The following example reflects an Active Directory (AD) for Windows 2008 configuration. Unlike the previous LDAP example for OpenLDAP or Oracle, this AD configuration makes use of user_search_base and user_search_filter for Active Directory configuration options.

The user search base configuration for AD differs in format from the LDAP example.

The user_memberof_stores_dn option is explicitly set to True so that OpsCenter correctly handles the value of the memberof_attribute as a distinguished name (DN).

[authentication]
password_db = ./passwd.db
enabled = True
authentication_method = LDAP

[ldap]
server_host = mywin2008.myCompany.lan
server_port = 636
hostname_verification = true
uri_scheme = ldaps
search_dn = CN=Administrator,CN=Users,DC=prodwin2008,DC=datastax,DC=lan
search_password = ****
user_search_base = CN=Users,DC=prodwin2008,DC=datastax,DC=lan # AD base
user_search_filter = (sAMAccountName=\{0}) # AD filter
admin_group_name = superusers
group_search_type = memberof_search
group_name_attribute = cn
user_memberof_attribute = memberof
user_memberof_stores_dn = True
ldap_security = SSL_TLS
truststore_type = JKS