About LDAP

GroundWork Monitor can authenticate/authorize through GroundWork or LDAP/AD. Administrators can configure LDAP mapping of LDAP containers to GroundWork roles from one or more domains, and reorder domains to control which are used. OpenLDAP and Active Directory servers need to be available and reachable from the GroundWork server on a defined port to use this feature. Users in LDAP/Active Directory groups corresponding to the GroundWork user/roles which are mapped will have access to GroundWork Monitor. You will also need to provide login credentials for an LDAP/AD search user to find and map the actual users and roles. Additionally, an LDAPS certificate can be chosen.

LDAP Management in GroundWork Monitor (Administration > LDAP) initially displays the authentication/authorization source options for GroundWork and LDAP/AD. Local (GroundWork) users will always work, even if LDAP is specified and mappings are defined. You can create and save LDAP configurations that can be switched on or off. You will of course need details of the domains you manage with LDAP/AD, and contexts for users and groups to map to roles in GroundWork Monitor.

Configuring the LDAP Connector

Before configuring the LDAP connector make sure you are using a version of GroundWork Monitor 8.1.3 or above and certificates are setup:

  • All certs need to be pem format
  • If using publicly issued certs (CAs e.g., GoDaddy, Let's Encrypt, DigiCert etc.), this step should not be necessary, as the root certs are already trusted. If using certs from a private chain:
    • Verify you have the complete chain: Self-signed CA, all intermediates (if applicable), and the Leaf CA the LDAP server is using
    • Put all the certs in a single chain cert, and load the chain cert using this procedure Adding Certificates to HTTPS under the section Adding Root CA Cert to Container
  • Use the ldapsearch command line tool to verify the LDAP bind account credentials, DNS resolution, and user context DN, Role context DN, and LDAP groundwork group membership

Adding a Domain

  1. Go to Administration > LDAP where you will be presented with two authentication/authorization sources: GroundWork and LDAP/AD.

    administration ldap
    • GroundWork is the default authentication/authorization. It is also used as a fallback in the case where LDAP is selected, but the user can’t be found in LDAP. Switching between the two does not remove any LDAP/AD configuration.
    • Selecting LDAP/AD exposes options to get started configuring LDAP. There are some options to consider: 
      • Endpoint names as prefixes (optional): This places the specified endpoint name as a prefix on the username, e.g., domain\username. This is useful if you have more than one domain and wish to differentiate users based on domain name. 

      • Enable mapper (optional, advanced mapping): When this function is enabled, GroundWork maps LDAP roles for a user using LDAP roles for LDAP roles! It starts with the roles defined for the user in LDAP. It then attempts to find additional roles defined for each of these roles. If it finds new roles, it replaces the user's original LDAP role with the new roles and continues recursively. In effect, this walks the LDAP roles hierarchy, stopping only when it finds roles without additional LDAP roles. This feature is often used with different role contexts that constrain the role lookup.

        If you have users with the same login name in LDAP and in the local GroundWork user, you will not be able to log in with the LDAP username and password. In this case we recommend changing the LDAP user name or using the prefix option. You can't change the name of the local GroundWork user if it is a system account (e.g., user admin), so if you want to use one or more of these usernames specified in LDAP, use a prefix (domain\admin) to differentiate them.

  2. Next, to configure LDAP or AD mapping, click Add Domain.
  3. In the New Domain screen you will need to enter the following fields:

  4. Once you fill out the form, click Save, then Edit again. You should be able to test connectivity to the LDAP server with the security principle using the Test button. If it fails, make sure all the contexts are exactly correct. It won't work unless you have the connection string exactly right. In particular look for the distinction of OU vs CN, and dc vs dn. These vary between OpenLDAP and Active directory, and even between versions. 

    • Windows AD users can find the security principle connection string with the dsquery command. For example, if your search user is named gw_ldap, you can open a command prompt on your active directory controller and type:
      dsquery user -name gw_ldap
      This will give you the exact string to paste into the Security Principal field. 
    • Similarly, you can use dsquery to look for the OU or CN for users and roles, for example:
      dsquery ou domainroot -name CORP*
      This will tell you if the role context "CORP GROUPS" is an OU or a CN. 
  5. Selecting Show advanced options provides more options. It's rare that you will need these, but they are available. Make sure you refer to LDAP/AD documentation for your site if you think you need to adjust the defaults:
    • Role attribute ID: Usually sAMAccountName for Active Directory
    • Use TLS: Optional
    • Role attribute ID:
    • Role matching mode: e.g., UDN
    • Security authentication: e.g., simple
    • Security protocol: No default
    • UID attribute ID: No default
    • Updatable Credential Password: No default
    • User Certificate Attribute ID: e.g., userCertificate
    • User properties query string: e.g., Name=firstname,sn=lastname,userPrincipalName=mail
    • User search scope:  e.g., SUBTREE
  6. After completing the various advanced options, click Save then Edit again. You can then click Test to see if your security principle user can still log in. If you need to make changes while editing, click Apply.
  7. To search the tree for roles to map, click Search. You will then see a mapping screen listing the role in the Role context you specified.

    search for roles to map

  8. Click Map to role to select GroundWork roles to map to the LDAP/AD role you select:

    map to role

    Every user in LDAP that is a member of the LDAP role you map to a GroundWork role will be granted the rights of that GroundWork role. You can have as many GroundWork roles as you like, and map them to as many LDAP roles as you like, and the resulting access granted to the user will be the union of all mapped role privileges. 

  9. Click Save when finished, and you're done! This saves the role mapping, and at this point, LDAP users with membership in groups matching mapped roles may log in to GroundWork and receive the privileges of their mapped roles.

Related Resources