How to configure LDAP

REDIRECT: This URL has changed to https://support8.gwos.com/gw/gw8/latest/documentation/administration/ldap-mapping
Click the link above if you are not automatically redirected in 10 seconds.

LDAP Management in GroundWork Monitor (Administration > LDAP) initially displays the authentication/authorization source options GroundWork (default) and LDAP/AD. LDAP configurations can be on or off (with saved configurations). For an LDAP configuration you will need the details for the domains you manage with LDAP/AD and contexts for users and groups to map to roles in GroundWork Monitor. For an overview, please see LDAP Mapping.

Adding a domain

  1. By selecting Administration > LDAP you will be presented with two authentication/authorization sources: GroundWork and LDAP/AD. 
  2. 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.
  3. 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): This advanced option maps LDAP roles that have LDAP roles. See Advanced Mapping below. 

      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.

  4. To configure LDAP or AD mapping, click Add Domain.

    administration ldap
  5. In the New Domain screen you will need to enter the following:
    • LDAP server to add: IP or DNS name of the LDAP or AD server
    • Endpoint Name: Arbitrary, but usually set to the LDAP or AD domain name
    • Server Type: OpenLDAP and Active Directory are supported
    • Port: Usually 389, unless you are using LDAPS, which typically uses 636
    • Use LDAP/S: (optional)
    • Keystore: If using LDAPS, you will need to browse to the file and upload it
    • Security Principal: This is a user that has read access to the user context and the roles context

    • User and role contexts for domain: This is where the users are defined in the LDAP/AD tree, and where the Roles or Groups are defined that you want to map to roles in GroundWork.

      new domain

  6. 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*
      will tell you if the role context "CORP GROUPS" is an OU or a CN. 
  7. 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
  8. After completing the various 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.
  9. 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

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


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

Advanced Mapping

When the "Enable Mapper" 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.


Related articles