Loading...

LDAP Connections

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.

file

LDAP Connection comes with a guided UI that helps configure the most common options for connecting to LDAP / AD.

file

If this UI is not flexible enough, you can alternatively setup a manual connection, specifying connection parameters via a JSON schema (see Manual connections).

Connection Information

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.

file

Server IP

The IP or hostname of your LDAP server. If you have multiple IP's, separate them with a space character.

Port

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

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.

file

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.

Domain Component

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.

file

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.

See Introduction to Drivers.

UID Attribute

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:

file

Note: you can have multiple filters.

When the filter menu is rendered, you need to provide up to 4 parameters:

  1. Title, so you can distinguish where the attributes came from, when looking at the attribute setup screen
  2. Base Distinguished Name (Base DN)
  3. Filter String. It can contain a variable, in the form of username, that is supplied during SSO process
  4. (Optional) Which attributes to retrieve from the filter result. To specify the required attributes, focus the field, type attribute name and press SPACE or ENTER.

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.

file

When executed, the filter returns the names of the arbitrary roles that user has been assigned to. You can see that attribute type cn is returned, as that is what we specified in the filter above.

file

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.

file

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.

file

Remove attributes which are not required:

file

Custom filter results appear at the bottom. In our example, cn is returned, which is renamed to customGroups.
The filter name is shown on the right hand side.

file

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.

file

Once a connection is created it can be consumed within Attribute Mappings.


Previous Article

Managing Service Providers

Next Article

Manual Connections

We're happy to talk

Our offices are open 8.30am - 7pm GMT, Monday to Friday - but you can always contact us via email. When we receive your email during opening hours, we aim to respond within 30 minutes or less. Should your email reach us out of hours, we will contact you when the office re-opens.

You can contact us using live chat