Checkbox 8 - LDAP configuration

Checkbox 8 has significantly changed the way that LDAP works, allowing better cross-platform access.  This has expanded the configuration settings.  In this guide we will go through all of the configuration settings which may be accessed in your ldap.json configuration file, located in api-core\Configs and checkbox-service-core\Configs.



LDAP configuration is broken up into membership providers and role providers.  At least one should be provided in order for your configuration to work.  The membership provider is responsible for reading and validation of individual Users as well as groups, while the role provider is responsible for mapping users with roles.


Membership provider properties

Properties Default value Description Notes
name* NULL Unique name of membership provider  
server* NULL A string specifying the server ID, which can be a domain name.  
port* 0 The port number to use when connecting to the server.  
providerType Default Type of supported Membership provider Possible values: Default, Wrapper
authType Basic The supported authentication type Possible values:  Anonymous, Basic, Negotiate, Ntlm, Digest, Sicily, Dpa, Msn, External, Kerberos
protocolVersion* 3 The LDAP protocol version to use Only version 3 is supported by Checkbox.
referralChasing None Specifies how the LDAP library follows referrals returned by LDAP servers Possible values:
None, Subordinate, External, All
useSsl false Whether secure socket layer is enabled.  
username NULL The username associated with the credentials  
password NULL The password for the user name associated with the credentials.  
domainName NULL The domain name that is used for the account login For example, "corp" for login "corp\administrator"
supportedControls:   Supported DirectoryControls on server  
- hasSortRequestControl false Whether a sort request control is to be used to sort search results before returning them to the client application  
-hasPageResultRequestControl true Whether the server should return search requests with a specified page size  
maxServerPageSize 1000 The page size for requests  
rootDistinguishedName string.Empty The distinguished name of the requested object  
searchScope Subtree Specifies the possible scopes for a director search Possible values: Base, OneLeve, Subtree
enableCache NULL enable caching  
attributeMapUserName sAMAccountName Maps against a UserName  
attributeMapGroupName cn Maps against a GroupName  

* - required


Role provider properties

Properties Default value Description
domainDn NULL The container on the store to use as the root of the context.  All queries are performed under this root, and all inserts are performed into this container.

For Domain and ApplicationDirectory context types, this parameter is the distinguished name of a container object.

For Machine context types, this parameter must be set to NULL.
username NULL The username used to connect to the store.  If the username and password parameters are both NULL, the default credentials of the current principal are used.  Otherwise, both username and password must be non-null, and the credentials they specify are used to connect to the store.
password NULL The password used to connect to the store.  See description of username immediately above.
domainName NULL

The name of the domain or server for Domain context types, the machine name for Machine context types, or the name of the server and port hosting the ApplicationDirectory instance.


If the name is null for a Domain context type this context is a domain controller for the domain of the user principal under which the thread is running.  If the name is null for a Machine context type, this is the local machine name.  This parameter cannot be null for ApplicationDirectory context types.

enableCache NULL Enable caching
groupNameToRoleNameMap NULL Map AD groups to Checkbox roles.  For example, "Domain Users=Report Viewer, Domain Users=Respondent"


Sample configuration file for Checkbox8 (AWS Simple Active Directory)




        "name": "Checkbox8",
        "providerType": "Default",
        "server": "",
        "port": 3268,
        "authType": "Basic",
        "protocolVersion": 3,
        "referralChasing": "None",
        "useSsl": false,
        "username": "corp\\Administrator",
        "password": "***",
        "domainName": "corp",
        "supportedControls": {
          "hasSortRequestControl": false,
          "hasPageResultRequestControl": true
        "maxServerPageSize": 1000,
        "rootDistinguishedName": "DC=corp,DC=ad-checkbox,DC=com",
        "searchScope": "Subtree",
        "enableCache": true,
        "attributeMapUserName": "sAMAccountName",
        "attributeMapGroupName": "cn"

        "domainDn": "DC=corp,DC=ad-checkbox,DC=com",
        "username": "corp\\Administrator",
        "password": "***",
        "domainName": "",
        "enableCache": true,
        "groupNameToRoleNameMap": "Domain Users=Report Viewer,Domain Users=Respondent"






Have more questions? Submit a request


Article is closed for comments.