Configuring LDAP Sync

This document is no longer available beyond version 5.0. Information can now be found here: Configuring LDAP Sync with Altium On-Prem Enterprise Server for version 6.0

Applies to NEXUS Server version: 5.0

This documentation page references NEXUS Server (part of the deployed NEXUS solution), which has been discontinued. All your PCB design, data management and collaboration needs can now be delivered by Altium Designer and a connected Altium 365 Workspace. Check out the FAQs page for more information.

 

Parent page: Managing Users

To simplify the process of connecting to and accessing company networks, the Altium NEXUS Server facilitates directory services support through its browser interface.

This offers domain user synchronization based on the Lightweight Directory Access Protocol (LDAP), which queries the network’s central LDAP server to retrieve domain user group and role membership information. Authenticating domain users through established directory services in this way offers the potential of a single login for access to all company systems, including the NEXUS Server.

The NEXUS Server LDAP synchronization queries the network services on a user role basis, where role membership information is gathered for NEXUS Server user access authorization. Polling the domain membership through the LDAP service (synchronizing) allows the system to respond to a domain user configuration change within a synchronization cycle.

For more information on the LDAP principles, capabilities and implementation syntax, see https://tools.ietf.org/html/rfc4510 and its constituent documentation pages.

LDAP Sync

An LDAP Sync allows an administrator of an Altium NEXUS Server to leverage the network domain’s existing username and password credentials, so that user credentials do not have to be created manually one at a time on the Users page of the NEXUS Server's browser interface. When set up correctly, the Users page will automatically populate with user credentials, enabling any user listed to sign into the Altium NEXUS Server using their regular corporate network username and password.

When signing in to your Altium NEXUS Server, to use your Windows login credentials – taking advantage of the NEXUS Server's support for Windows Authentication – enable the Use Windows Session option (browser interface), or Use Windows Session credentials option (Sign in dialog in Altium NEXUS).
The Altium NEXUS Server supports both Standard LDAP, and LDAPS (LDAP over SSL).

This article details a proven approach that has been successfully used in setting up an LDAP Sync on a domain. Try this approach when setting up an LDAP Sync on your own domain.

What do I need?

  • Administrative access to the Altium NEXUS Server.
  • Optionally, an extremely helpful utility is an application called LDAP Admin (download LdapAdminExe-<version>.zip from https://sourceforge.net/projects/ldapadmin/ )
LDAP Admin can be used to identify the exact User Group query strings and syntax required to configure the Altium NEXUS Server LDAP setup page.

Obtaining the LDAP Search string (Distinguished Name)

When configuring an LDAP Sync task through the Altium NEXUS Server's browser-based interface, you need to supply the LDAP Distinguished Name (DN). This is entered in string format, and identifies the base object of the LDAP search. To get this string, we're going to use the LDAP Admin utility, so first ensure the zip file is downloaded, and extract out the LdapAdmin executable therein.

Download and extract the LdapAdmin.exe file.
Download and extract the LdapAdmin.exe file.

Run the LdapAdmin.exe executable as Administrator (just right-click on it and select Run as administrator).

When the LDAP Admin panel opens, choose Start » Connect to access the Connections dialog, then double-click New connection to access the Connection properties dialog.

Creating a new connection within the LDAP Admin utility.
Creating a new connection within the LDAP Admin utility.

On the General tab of the Connection properties dialog, configure the connection information in relation to your domain, an example of which might be:

  • Connection name: just any arbitrary name to be used for the connection icon.
  • Host: testsite.com
  • Port: 389
If you are configuring for LDAPS (LDAP over SSL), then the port needs to be 636.
  • Base: DC=testsite, DC=com
  • Enable the GSS-API option.
If you are configuring for LDAPS (LDAP over SSL), then you also need to enable the SSL option.
  • Account: just leave the Use current user credentials option enabled.


An example configured connection, when using standard LDAP. If using LDAPS (LDAP over SSL),
change the Port to 636, and enable the SSL option.

With the connection properties configured, press the Test connection button. If all is set correctly, you should see the Connection is successful message. Click OK to finish creating the new connection.

You now need to identify the string that targets the base object of the LDAP search. To do this:

  1. Select your newly-created connection and click OK in the Connections dialog – your network domain and user group hierarchy will be presented.
  2. Expand the relevant folder path until you get to the folder containing the required users.
  3. Right-click on this folder and choose the Search command from the context menu. This will open the Search panel. The key piece of information you are after is the string already populated in the Path field. Reading from left-to-right, this string represents the path to this folder of users from the bottom-up, within the domain structure. For our example, we'll assume a folder of specific users – Engineers – which is a child of the parent folder – Users. For this case, our string is: OU=Engineers,OU=Users,DC=testsite,DC=com.
  4. Copy and paste this string to a text file for subsequent use in the configuration process, or optionally just leave the Search panel accessible.

At this point, the LDAP Admin utility is no longer required for any further steps.

Configuring the NEXUS Server to use LDAP Sync

Now sign into the target NEXUS Server – through its browser interface – as an Administrator. If you are intending to create user credentials from LDAP automatically, then you probably want to remove any existing manually created users. So ideally just start with the default administrative user – admin (on the Admin - Users page of the interface).

An example target NEXUS Server, with just the default administrative user, admin.
An example target NEXUS Server, with just the default administrative user, admin.

If you want the users from the LDAP Sync to be associated with a specific role, you can switch to the Roles page and create a new role as required (e.g. Electrical Designers, Mechanical Designers, PCB Specialists, etc…), leaving it empty of users. The example here uses the default role that was part of the installed sample data, called Engineers.

Now switch to the LDAP Sync page, and click the button (or the Create a new one link in this case) to access the LDAP Sync Creation window.

Adding a new LDAP Sync Task through the NEXUS Server's browser interface.
Adding a new LDAP Sync Task through the NEXUS Server's browser interface.

Fill in the following information (based on the example domain structure used in the previous section):

General

  • Target Role: Engineers
  • Distinguished Name: OU=Engineers,OU=Users,DC=testsite,DC=com
This is the string obtained from the Path field of the Search panel, when using the LDAP Admin utility in the previous section.
  • Url: LDAP://testsite.com:389
If configuring for LDAPS (LDAP over SSL), then the Url in this example would be: LDAPS://testsite.com:636.
  • Scope: sub
  • Attributes: sAMAccountName
  • Filter: leave this field blank to acquire all users from the specified group determined on the domain (in the DN field). If the nominated area of the domain structure contained further groupings of users, you could extract just a subset of those users by using an appropriate filtering string here.

For example, consider if there had been a set of users under the group of Engineers, gathered to have administrative powers (CN=Administrators). To target just this set of users, and not all of the Engineers (under the OU=Engineers area of the domain structure), a query string could be written that targets this point in the domain structure:

(&(objectClass=user)(memberof=CN=Administrators,OU=Engineers,OU=Users,DC=testsite,DC=com))

While the Filter field can be left blank, returning all users along the path defined by the DN field, this can be quite dangerous. That path could be pointing to an area of the domain structure that contains a huge number of users, and could lock up the whole organization due to excessive load on the Altium NEXUS Server and Active Directory. It really is better to target one or more sets of specific users, using dedicated filtering. For more information regarding LDAP queries that can be used to target specific sets of users, use the following links:

Attribute Mapping

  • First Name: givenName
  • Last Name: sn
  • Email: mail
  • User Name: sAMAccountName
  • Overwrite existing users – when enabled, the LDAP Sync will override manually created users with those returned by the sync query, as long as the users' names are an identical match.

Authentication

  • User Name: domain\<your username> (e.g. testsite\jason.howie)
  • Password: <your password>
  • User authentication type: Windows
  • Domain: testsite.com

Example LDAP Sync task, configured with all required information when using standard LDAP. If using LDAPS (LDAP over SSL), the Url entry would be changed to LDAPS://testsite.com:636.
Example LDAP Sync task, configured with all required information when using standard LDAP. If using LDAPS (LDAP over SSL), the Url entry would be changed to LDAPS://testsite.com:636.

When you have completed entering all settings, click . This will initiate the Sync process, which may take a minute or two, as it processes the information you just entered.

Now access the Users page. This list should now be populated with all users as defined by the OU=<GroupName> setting (see example image below). Now anyone can sign into the NEXUS Server using their regular Windows login.

When signing in to your Altium NEXUS Server, to use your Windows login credentials – taking advantage of the NEXUS Server's support for Windows Authentication – enable the Use Windows Session option (browser interface), or Use Windows Session credentials option (Sign in dialog in Altium NEXUS).
Note that additional users can be manually added outside of the LDAP Sync group – so you can indeed have a mixture of manually created users as well as LDAP-specified (automatically created) users.

Example population of users for an Altium NEXUS Server, through use of an LDAP sync.
Example population of users for an Altium NEXUS Server, through use of an LDAP sync.

Content