How To
Troubleshooting Directory Services Issues
this article is intended to ease the difficulty of the initial integration of swimlane with active directory or open ldap, and provide some related best practice tips for subsequent experiences many swimlane platform administrators leverage the platformâs directory services feature to allow their soc engineers and analysts to log in to swimlane with directory credentials established previously increase the ease of administrative maintenance for groups of such swimlane users unfortunately, most admins encounter difficulty in their first attempts to integrate swimlane with active directory or open ldap (the two supported directory servers) initial integration and troubleshooting procedure verify that server settings are correct (server (host name or ip address), username, password, domain) use the test connection button to confirm for open ldap, the username must be an ldap distinguished name (such as cn=manager,dc=maxcrc,dc=com ) see the directory structure section in https //en wikipedia org/wiki/lightweight directory access protocol click the save button in the upper right so that the test connection button appears (the save operation will not succeed if required portions of the entire form are not filled out it will be necessary to add values (if only temporary values) in some portions of the form in order to proceed with the connectivity test ) click the test connection button if this test succeeds, then proceed to step 2 if it fails, then troubleshoot to establish tcp/ip and ldap connectivity to the director server this involves double checking the validity of all four of the server settings parameters, and it may also involve repeated trial and error connection attempts until the test connection operation succeeds during this process it may be necessary to open chrome developer tools, click the test connection button, and inspect the reply received from the http post to /api/settings/ldap/test if the response body contains the error message âthe remote certificate is invalid according to the validation procedureâ, then the connection failed because swimlane doesnât yet have access to a required tls certificate for linux single host deployments follow these instructions to provide the directory serverâs certificate to swimlane for linux ha deployments follow these instructions to upload a third party certificate confirm that swimlane has tcp/ip connectivity to the directory server for windows deployments, rdp to the swimlane server and use ping and telnet (port 389) to test connectivity for linux deployments, ssh into the host and try this command from the host os shell openssl s client connect \<server name> 636 openssl s client connect \<server name> 636 cafile ca crt (to experiment with a specific certificate file in x 509 base64 format) alternately (linux), ssh into the host and then use docker exec it sw api /bin/bash (single host) or kubectl exec it \<api pod name> n \<namespace name> /bin/bash (multi host kubernetes) to access the pertinent container/pod, and they try these commands python import socket print(socket gethostbyname ex('\<server name>')) \# if the above fails, try this print(socket gethostbyname ex('\<server ip address>')) confirm that the chosen directory user has sufficient privilege for the swimlane platformâs need to connect and traverse the directory tree disable any firewall thatâs blocking access to the directory server use wireshark (see https //www wireshark org/), an open source network transmission analysis tool, to inspect the ldap packets sent between swimlane and the directory server to identify other obstacles wireshark can be run on the swimlane server, or on the directory server, or on any third host that can gain access to the ldap transmissions between the swimlane server and the directory server note that if youâre directory services domain name collides with a name thatâs registered publicly on the internet (e g example com ), then the test connection may report a false positive success review the values in the user settings section the default values for both active directory and open ldap are often the most appropriate, but they may need to be altered to conform to your directory serverâs configuration delete the default value for member of field target it should typically be empty review the values in the field mapping section these values rarely need to deviate from defaults review the values in the group settings section pay special attention to the following delete the default value for user membership field target it should typically be empty the group location field must contain a distinguished name (dn) that articulates the complete path to the container in which the targeted group(s) is/are defined (see below) see dn background information referenced in step 1 above use an appropriate directory services client to inspect the targeted group(s) and make a note of the manner in which belonging users are affiliated to the group(s) is it done through the groups' property named member or the users' property named memberof , or through some other means? active directory open ldap review the values in the groups section this is simply a list of hand entered group names (note the need to click add value on far right when entering a new name for the first time ) click the save button again so that the validate groups button appears click the validate groups button if it succeeds then proceed to section 6 if it fails, then troubleshoot by confirming that group names are spelled correctly confirming that group names are defined within the container specified in the group location value (a distinguished name) in group settings employing further trial and error experiments until group validation has succeeded review the membership settings the membership setting can assume only one of two values by user field or by group field if, for example, the users are affiliated with their groups via the member property in each group, then choose by group field click the save button again so that the sync now button appears click the sync now button if it succeeds, then open the swimlane platformâs users page and inspect it to see if some/all of the users from the targeted groups have been added to the platform (if only some of the users have been added by an apparently successful sync, that may be owing to the fact the some admin defined users have the same user names as persons in the targeted groups ) if the sync reports failure, then experiment with group names, membership values, and the group location value, each time testing for group validity and sync success/failure if trial and error does not succeed, then resort to wireshark inspection of the syncâs transmissions (as this sometimes affords clues that can shed light on remediation steps) best practices / maintenance there is limited support for nested sub groups strive to ensure that all users to whom swimlane access will be granted belong to the groups specified explicitly in the groups section of the settings the swimlane role based access control (rbac) features allow for complex allocation of privileges within the platform keep things simple by adding each user to only one group, and affiliating each group with only one role wherever possible (privileges are defined within roles, and these privileges are granted by affiliating the role with groups and/or users ) when a user inherits or is given multiple roles, the more permissive roles will win out in that userâs effective access privilege active directory (ad) explorer from https //petri com/test connectivity to an active directory domain controller from pc this is a tool created by sysinternals, which is now a part of microsoft itâs a stand alone tool thatâs useful for querying ad and performing various tasks the official microsoft description states âactive directory explorer (ad explorer) is an advanced active directory (ad) viewer and editor you can use ad explorer to easily navigate an ad database, define favorite locations, view object properties and attributes without having to open dialog boxes, edit permissions, view an objectâs schema, and execute sophisticated searches that you can save and re execute â in the context of this article, ad explorer is also useful for ad connectivity tests download ad explorer once youâve downloaded the microsoft sysinternals ad explorer tool, simply run the adexplorer exe file type in the name of the dc you want to connect to and the credentials you want to bind with note if you provide credentials for a user that has domain admin or enterprise admin rights, then you will be able to perform actions on the ad tree this means that one wrong move and you may render your ad useless take caution, and best use a user account that has read only permissions to the ad tree