Skip to content

LDAP Configuration

The software uses the LDAP configuration in several different components:

  • Authentication - When the Login button is pressed on the software's authentication screen, it tries to authenticate the user account using the provided account and password information across each enabled Local User Directory marked with the "Direct Login" flag. This process occurs sequentially, following alphabetical order.
    Users have the option to specify a particular LDAP configuration for authentication by providing the LDAP configuration name before the account in the user field separated with back slash such as in the example: ldap-name\account.

  • Authorization - The software utilizes account and group membership data obtained from the configured LDAP Server to verify permissions set for objects and roles.

  • Permissions - System owners can search for user accounts and groups in the configured LDAP Servers to use in object and role permissions.

  • Metadata - The software might use account metadata obtained from the configured LDAP Server to improve the visual presentation for different system functionalities. Examples of LDAP metadata include Thumbnail, Display Name or Creation Date.

Info

Use the Verify Trust button to verify or to establish trust with a remote LDAP server by importing its certificate into the software's keystore. When the LDAP certificate is updated, use the Verify Trust option again to re-import the new certificate to ensure trust with the remote LDAP server.

Creating a new LDAP Connection

To integrate with an LDAP external user directory like Active Directory or OpenLDAP, please follow the steps provided in this section.

  1. Log in with an account that has either the System Administrator or Configuration Manager role in this tenant.
  2. Navigate to Configuration > LDAP and click the Add button to create a new LDAP integration.
  3. Click on the parameter name for details about each or follow the guidance provided here:
    • Name: Enter a unique, but recognizable name for this LDAP connection.
    • Server: Enter the server address of your LDAP endpoint. The server value should be provided in the format: ldaps://dc.company.com:636. We recommend connecting over a secure connection (LDAPS) rather than insecure (LDAP), but both options are supported. Please include the appropriate port number for your connection. When using a secure LDAPS connection, the directory's SSL Certificate Subject should match the Server name provided.
    • Service User: Enter the name of the service binding account username. Use the format: username@company.com
    • Service Password: Enter the valid password of the Service User. If the password is changed in the future, please remember to update this integration with this new password.

Tip

The remaining parameters can be auto-populated using the Connect and Auto-Populate button at the top of this form. We recommend using this option to minimize the configuration steps, but you can do this manually following the guidance provided below or from the in-app help tips.

  • Scheme: Select the scheme for your integration type.

    • User Base: This parameter defines the root LDAP Server DN for user queries. All accounts from this LDAP server that have access to the application are located in the LDAP branch defined by this parameter. Example value: OU=IT Support,DC=company,DC=com
    • User Search: This parameter defines the LDAP query to select a user entry from the user directory by its login name. Use the $login placeholder to designate a place in the query where the application substitutes the user name when performing the search. Example value is: (&(objectClass=person)(UserPrincipalName=$login)). Another example is: (&(objectclass=account)(uid=$login)).
    • User Format: This parameter defines the account pattern to construct the full account name for verification and query purposes. This parameter allows users to enter a short portion of the account name (for example, bob) relying on the application to use the full name acceptable by LDAP Servers (for example, bob@branch.company.com). Use $login placeholder to designate the place in the query where the application substitutes the user name when performing the search. Example value is: $login@company.com.
    • Group Base: This parameter defines the root LDAP Server DN for group queries. All groups from this LDAP server that have access to the application are located in the LDAP branch defined by this parameter. Example value is: OU=IT Support,DC=company,DC=com. For multi-branch selections, please review the in-app guide by clicking on this parameter's name.
    • Group Search: This parameter defines the LDAP query to select a group entry from the user directory by group name. Use the $group placeholder to designate the place in the query where the application substitutes the group name when performing the search. Example value is: (&(objectClass=group)(cn=$group)).
    • Role Search: This parameter defines the group membership search strategy for a user. To query groups, a user who is a member of the application might use one of the following strategies:
      • Client Side Search - The application first queries the groups a user belongs to. After that the application uses a similar query for each group found to find groups these groups are members of. The application continues to issue such queries for all groups found until it reaches the root of the hierarchy. This is the slowest strategy to query group membership from the networking perspective. However, this strategy does not overload the LDAP server as other strategies do. In this case this strategy might be preferred method to query group membership.
      • Server Side Search - The application issues a single query to the LDAP Server to return a recursive list of all groups a user belongs to. To respond, the server performs a recursive search. If supported by the LDAP Server (typically, Microsoft Active Directory) this strategy reduces the network traffic while increasing the load on the LDAP Server.
      • Attribute Based Search - The application uses a special user entry attribute (if is provided by the LDAP Server) to query group membership. When such an attribute is provided by the LDAP Server (typically, Microsoft Active Directory Server) the LDAP Server maintains a value of this attribute using offline processes so it could return the requested result faster and more efficiently.
    • Direct Login: This parameter indicates whether the Application can use this LDAP Server configuration to allow users from this LDAP server to login to the application using user and password entered on the login screen.
    • Enabled: This parameter indicates whether this LDAP configuration is enabled. The configuration must be enabled to support integration.

  • Use the Test Connection button to confirm connectivity and authentication between 12Port and this LDAP server.

  • Use the Verify Trust button to verify or to establish trust with the LDAP server by importing its certificate into the application's keystore. Later, if the LDAP certificate is updated use this Verify Trust option again to re-import the new certificate to ensure trust with this LDAP server.
  • Finally, use the Save button to complete the integration.

Verifying your Integration

To verify your integration with LDAP was successfully:

  1. Use the Test Connectivity button. A successful integration will return a Connection Successful message. If you receive a failed message, check your supplied values and try again.
  2. Navigate to any page where there is a User and Group lookup. For example, navigate to Management > Space Roles and click the Grant button. On the User or Group parameter, click the dropdown and select the name of your LDAP integration. Next, enter the account name of a valid user from this LDAP server into the field and it should appear in the type-ahead menu. Repeat the same for Group search by first clicking on the Group icon and then entering a valid Group name from this LDAP server. If both your User and Group were located, then your integration is successful.
  3. Open a new private browser and navigate to the software's login page. On the login form, enter the LDAP credentials of a valid user from this LDAP directory and ensure this login is successful.

Logins with UserPrincipalName (UPN)

After using the Connect and Auto-Populate option, LDAP logins to 12Port are configured to support usernames in sAMAccountName format. For example, if your LDAP (Active Directory) login is bwilliams@contoso.com, then you can authenticate into 12Port by simply entering bwilliams and your valid password. This makes it more convenient for users by not requiring them to enter their full UPN account for each login.

If you would prefer or require that users enter only their full UPN account to login (i.e. bwilliams@contoso.com) then you can change the User Format parameter in your LDAP configuration for this tenant to:

UserPrincipalName (UPN) parameter:
User Format: %s

With this change, 12Port will take the entire value that is entered into the Username field on the login page as-is by the user, which requires that they specify their domain.

To revert UPN logins (bwilliams@contoso.com) to sAMAccountName logins (bwilliams), change this same User Format parameter to the below, replacing <yourDomain.com> with your LDAP domain like contoso.com:

sAMAccountName parameter:
User Format: %s@<yourDomain.com>

Applied example:
User Format: %s@contoso.com