LDAP Connection Management can be found under Settings.
Connections are configurations for Drivers. You may have one or more connections per driver. Each Service Provider requires a Connection in order to verify User Credentials.
Step 1- Creating an LDAP Connection
Create a new connection by navigating to Connections, then clicking New Connection, found in the top right.
LDAP Connection comes with a guided UI that helps configure the most common options for connecting to LDAP / AD.
If this UI is not flexible enough, you can alternatively setup a manual connection, specifying connection parameters via a JSON schema (see Manual connections).
The first part of the new LDAP connection describes connection information. It requires LDAP hostname / IP, port and protocol version to operate correctly. Admin username and password are marked mandatory, but are only used when executing search filters, if bind user credentials are insufficient for that action. More detail on this under filters.
The IP or hostname of your LDAP server. If you have multiple IP's, separate them with a space character.
Port LDAP is listening to. If you use default installation, this port is
389. If you use encrypted connections using SSL, the port should be
If you use TLS, then port is
389 unless specified differently in your LDAP server setup.
Working with LDAP over SSL
Using self-signed certificates can cause issues with LDAPS. To fix them, OS adjustment is required. Please see SSL LDAP Connection Errors.
Once adjustments have been made, enter the following information into the Server IP and Port.
Note: you must specify ldaps:// before IP, in the screenshot above you can see an example. The port for LDAP and SSL is usually
636. If you have more than one LDAP server, you can specify multiple endpoints separated by a space, in the same box with the hostname.
Admin Username and Password
These credentials are used if you require additional LDAP filters after authentication. The User specified here does not need to be an LDAP
administrator, but any user that is granted permission to execute LDAP filters.
The DC (domain component) value of your LDAP tree. This is used for user authentication.
Organizational Unit with Users
This is the LDAP OU (one or more) which contain your user information.
To authenticate user(s) against OU=Directors, we first need to specify the full path to that OU in LDAP tree. LDAP syntax is defined backwards.
What we read as "OU=Staff and then OU=Directors and then OU=Board" is specified as: "OU=Board,OU=Directors, OU=Staff"
AuthStack accepts a list of OU's, separated by new line. These are used for LDAP bind. Binding will stop once successful, therefore it would improve performance by including larger and more frequently used OU's, higher in the list.
If you require dynamic OU lookups, or additional functionality, the default driver can be extended and customised. One example would be to support switching OU based on EntityId.
This is the attribute that will be used during searches. It is the
username that user(s) specify at the SSO login screen.
Post Authentication Filters
After the user successfully authenticates, you may require additional attributes, not returned from the first search. AuthStack handles this via post-authentication filters.
Example: Lets assume LDAP does not have an overlay, such as memberOf, but you wish to check if the user belongs to a certain group. For that purpose, we use authentication filters.
To add a new filter, click Add New Filter:
Note: you can have multiple filters.
When the filter menu is rendered, you need to provide up to 4 parameters:
- Title, so you can distinguish where the attributes came from, when looking at the attribute setup screen
- Base Distinguished Name (Base DN)
- Filter String. It can contain a variable, in the form of username, that is supplied during SSO process
- (Optional) Which attributes to retrieve from the filter result. To specify the required attributes, focus the field, type attribute name and press
Filters can be tested. Credentials that will be used for the lookup are the admin username and password specified in the Connection Information form.
Example: Here we have entered the user UID to lookup. There are two variables (EntityId and UID), which are populated from the form underneath for testing purposes.
When executed, the filter returns the names of the arbitrary roles that user has been assigned to. You can see that
cn is returned, as that is what we specified in the filter above.
Step 2 - Attribute Settings
The first step is to define a username and password which has permission to authenticate with LDAP. Username and password are required.
Entity ID and Post-authentication filters are optional. If ticked, the filter result will be appended to the Attribute Setup list.
If the LDAP bind was successful, the attribute setup list will be populated with a list of available attributes, all pre-checked. These attributes are not what are forwarded to the Service Provider, but what are provided to the Attribute Mapper. Therefore, one set of attributes within a connection can be consumed by many attribute mappings. Do not configure for a specific Service Provider, but consider a wider use-case and scope.
You may override the attribute name, which is returned to the mapper.
Remove attributes which are not required:
Custom filter results appear at the bottom. In our example,
cn is returned, which is renamed to
The filter name is shown on the right hand side.
Step 3 - Create Connection
The final step requires a title, with optional
admin access granted, based on attributes returned from LDAP.
Ticking Grant Admin access When Authenticated Using this Connection will provide administrator access to AuthStack for users who match specific attribute/values.
In the example below, we inspect the custom filter
customGroups and check if the value
administrator is returned, if so, the LDAP user will be granted AuthStack administrator privileges. If the attribute is multi-valued, i.e. an array, AuthStack will inspect each value until a match is made.
Once a connection is created it can be consumed within Attribute Mappings.