Ldap

ldap is a protocol used for accessing and managing directory information over an ip network ldap (lightweight directory access protocol) is a protocol used to access and manage directory information over an ip network the ldap turbine connector allows swimlane turbine users to automate directory management tasks such as adding, deleting, modifying, and searching directory entries by integrating ldap with swimlane turbine, users can streamline user synchronization and directory management processes, enhancing operational efficiency and reducing manual intervention prerequisites before you can use the ldap connector for turbine, you'll need access to an ldap server this requires the following authentication to the ldap server using the appropriate credentials authentication this connector uses ldap3 https //ldap3 readthedocs io/ for ldap binds configure connection and authentication on the ldap asset supported authentication types authentication asset fields behavior simple (default) user (bind dn), password standard ldap bind anonymous no user or password anonymous bind ntlm user (for example domain\user ), password ntlm bind (active directory) sasl external tls client certificate b64 , tls client private key b64 ; optional tls ca cert b64 , verify ssl , sasl external identity sasl external over ldaps with mutual tls matches ldap3 authentication=sasl , sasl mechanism=external gssapi kerberos fields below sasl gssapi (kerberos) runs kinit with a keytab, builds krb5 conf at runtime, then binds via ldap3 + the python gssapi package set authentication to one of anonymous , simple , ntlm , sasl external , gssapi connection asset fields field required default description host yes — ldap server hostname or ip also used as the default kdc host for gssapi when kerberos kdc host is not set domain name yes — alternative to host ; resolved to an ip when host is omitted port no 389 ldap port user no — bind dn for simple/ntlm password no — password for simple or ntlm sasl external identity no "" optional authorization identity for sasl external tls ca cert b64 no — optional ca bundle for sasl external / ldaps tls client certificate b64 for sasl external — client certificate (pem), base64 or filesystem path tls client private key b64 for sasl external — client private key (pem), base64 or filesystem path use ssl no false use ldaps when true auto enabled for sasl external connect timeout no 120 connection timeout in seconds auto bind no no tls no tls , default , none , tls before bind , or tls after bind use no tls for typical cleartext ldap on port 389 verify ssl no true when false, sasl external / ldaps skips server certificate validation (testing only) provide host or domain name gssapi / kerberos asset fields used when authentication is gssapi field required default description kerberos principal yes — client principal for kinit (for example adminuser\@example com ) kerberos keytab path yes — base64 encoded keytab for kerberos principal kerberos realm no from principal kerberos realm (for example example com ) parsed from kerberos principal when omitted kerberos domain no lowercase realm dns domain (for example example com ) used to expand short service hostnames to fqdns kerberos kdc host no host kdc hostname or ip when the kdc is on a different host than ldap sasl kerberos service hostname no host / kdc host hostname in the ldap service principal ( ldap/hostname\@realm ) short names are expanded with kerberos domain when set example assets simple bind { "host" "10 0 0 10", "port" 389, "user" "cn=admin,dc=example,dc=com", "password" "secret", "authentication" "simple", "auto bind" "no tls", "use ssl" false } sasl external asset fields used when authentication is sasl external field required description host yes ldap server hostname or ip port no default 636 recommended for ldaps use ssl no set true for ldaps (defaulted to true when using sasl external) tls client certificate b64 yes base64 encoded client certificate (pem) tls client private key b64 yes base64 encoded client private key (pem) tls ca cert b64 no base64 encoded ca bundle (pem) verify ssl no set false for self signed / lab certificates sasl external identity no optional external authorization identity; omit for cert only auth the connector writes decoded pem files to temp paths, builds a ldap3 tls object, opens ldaps, then runs sasl external bind the same way as the standalone external test script sasl external example { "host" "10 0 0 10", "port" 636, "authentication" "sasl external", "use ssl" true, "auto bind" "no tls", "verify ssl" false, "tls ca cert b64" "\<base64 ca pem>", "tls client certificate b64" "\<base64 client cert pem>", "tls client private key b64" "\<base64 client key pem>" } generating base64 tls material for sasl external the connector expects pem encoded certificate and key files, each encoded as a single base64 string with no line breaks at runtime it decodes them to temporary files and uses them for mutual tls (ldaps on port 636 ) you need three files pem file asset field required ca certificate (trust anchor) tls ca cert b64 no (recommended for production) client certificate tls client certificate b64 yes client private key tls client private key b64 yes each file should look like pem text, for example \ begin certificate \ end certificate \ begin private key \ end private key linux — encode each file as one line ( w0 disables wrapping) base64 w0 /etc/ldap/client/ca crt base64 w0 /etc/ldap/client/client crt base64 w0 /etc/ldap/client/client key macos — base64 wraps by default; strip newlines base64 i /path/to/ca crt | tr d '\n' base64 i /path/to/client crt | tr d '\n' base64 i /path/to/client key | tr d '\n' paste each output into the matching asset field in swimlane turbine, or into data/asset json for local testing { "tls ca cert b64" "\<paste ca base64>", "tls client certificate b64" "\<paste client cert base64>", "tls client private key b64" "\<paste client key base64>" } verify a value decodes back to valid pem before saving the asset echo "\<paste base64 here>" | base64 d | head 3 \## should show begin certificate or begin private key openssl — if you only have separate cert/key paths on the ldap host base64 w0 /etc/ldap/cacert pem \## client cert + key issued for sasl external / mutual tls base64 w0 /etc/ldap/client/client crt base64 w0 /etc/ldap/client/client key for openldap sasl external , the client certificate is typically mapped to an ldap identity via olcauthzregexp (for example cn=john → uid=john,dc=example,dc=com ) include a cn on the client cert that matches your server mapping set verify ssl to false only in lab environments with self signed server certificates gssapi bind { "host" "10 0 0 10", "port" 389, "authentication" "gssapi", "auto bind" "no tls", "use ssl" false, "kerberos principal" "adminuser\@example com", "kerberos keytab path" "\<base64 encoded keytab>", "sasl kerberos service hostname" "ldap server example com" } generate base64 for kerberos keytab path on the kdc/ldap host base64 w0 /path/to/adminuser keytab for local tsdk action run local runs, set host to a server reachable from the connector container (for example a vm ip, or host docker internal when ldap runs on the docker host) references ldap3 operations https //ldap3 readthedocs io/en/latest/operations htmlldap3 bind / sasl / kerberos https //ldap3 readthedocs io/en/latest/bind html#sasl capabilities this connector provides the following ldap operations search query all users query system custom query user is member of group pagination support (using page size and page number parameters) if neither page size nor page number is provided returns all objects matching the query if only page size is provided returns results with default page number = 1 if only page number is provided returns results with default page size = 1000 if both page size and page number are provided works accordingly using the specified values add add user add computer add contact add shared folder add organizational unit custom create delete delete user delete computer delete contact delete shared folder delete organizational unit modify disable user enable user modify password modify password at next login update system update container custom update csv export support all actions (search, add, delete, and modify) support csv export functionality by setting the to csv parameter to true , the operation results will also be returned as a csv file object, enabling easy data export and integration with other systems use cases microsoft active directory see the examples below to implement your own microsoft active directory functionalities for more information please read the microsoft active directory technical specification https //learn microsoft com/en us/openspecs/windows protocols/ms adts/d2435927 0999 4c62 8c6d 13ba31a52e1a search operations query all users operation search inputs "search base" "dc=testdomain,dc=local", "search filter" "(&(objectclass=user)(objectcategory=person)(|(cn= )))" note without page size or page number , this returns all users matching the query query system operation search inputs "search base" "cn=windowsnt,ou=executives,dc=testdomain,dc=local", "search filter" "(&(objectclass=computer)(objectcategory=person)(|(cn= )))" custom query operation search inputs "search base" "dc=testdomain,dc=local", "search filter" "(&(objectclass=user)(objectcategory=person)(|(cn= )))" "attributes" {} user is member of group operation search inputs "search base" "cn=leeroy jenkins,ou=friends,dc=testdomain,dc=local", "search filter" "(&(objectclass=user)(objectcategory=person)(|(cn= )))" pagination support the search action supports pagination using page size and page number parameters search with page size only operation search inputs "search base" "dc=testdomain,dc=local", "search filter" "(&(objectclass=user)(objectcategory=person)(|(cn= )))", "page size" 50 note returns 50 results from page 1 (default) search with page number only operation search inputs "search base" "dc=testdomain,dc=local", "search filter" "(&(objectclass=user)(objectcategory=person)(|(cn= )))", "page number" 2 note returns up to 1000 results (default page size) from page 2 search with both page size and page number operation search inputs "search base" "dc=testdomain,dc=local", "search filter" "(&(objectclass=user)(objectcategory=person)(|(cn= )))", "page size" 10, "page number" 3 note returns 10 results from page 3 as specified csv export support search with csv export operation search inputs "search base" "dc=testdomain,dc=local", "search filter" "(&(objectclass=user)(objectcategory=person)(|(cn= )))", "to csv" true search with pagination and csv export operation search inputs "search base" "dc=testdomain,dc=local", "search filter" "(&(objectclass=user)(objectcategory=person)(|(cn= )))", "page size" 50, "page number" 2, "to csv" true add operations add user operation add inputs "dn" "cn=charles,ou=friends,dc=testdomain,dc=local", "object class" \["person", "user"], "attributes" {} add computer operation add inputs "dn" "cn=windowsnt,ou=executives,dc=testdomain,dc=local", "object class" \["computer"] add contact operation add inputs "dn" "cn=a contact,ou=friends,dc=testdomain,dc=local", "object class" \["contact"] add shared folder operation add inputs "dn" "cn=a folder,ou=friends,dc=testdomain,dc=local", "object class" \["volume"] add organizational unit operation add inputs "dn" "ou=organizational unit name,ou=friends,dc=testdomain,dc=local", "object class" \["organizationalunit"] custom create operation add inputs "dn" "cn=nacho libre,ou=friends,dc=testdomain,dc=local", "object class" \["top", "person", "organizationalperson", "user"], "attributes" {} add user with csv export operation add inputs "dn" "cn=charles,ou=friends,dc=testdomain,dc=local", "object class" \["person", "user"], "attributes" {}, "to csv" true delete operations delete user operation delete inputs "dn" "cn=charles,ou=friends,dc=testdomain,dc=local" delete computer operation delete inputs "dn" "cn=windowsnt,ou=executives,dc=testdomain,dc=local" delete contact operation delete inputs "dn" "cn=a contact,ou=friends,dc=testdomain,dc=local" delete shared folder operation delete inputs "dn" "cn=a folder,ou=friends,dc=testdomain,dc=local" delete organizational unit operation delete inputs "dn" "ou=organization unit name,ou=friends,dc=testdomain,dc=local" delete user with csv export operation delete inputs "dn" "cn=charles,ou=friends,dc=testdomain,dc=local", "to csv" true modify operations disable user operation modify inputs "dn" "cn=john doe,ou=friends,dc=testdomain,dc=local", "changes" \[ { "attribute name" "useraccountcontrol", "operation" "modify replace", "value" \[ "514" ] } ] enable user operation modify inputs "dn" "cn=john doe,ou=friends,dc=testdomain,dc=local", "changes" \[ { "attribute name" "useraccountcontrol", "operation" "modify replace", "value" \[ "512" ] } ] modify password operation modify inputs "dn" "cn=john doe,ou=friends,dc=testdomain,dc=local", "changes" \[ { "attribute name" "userpassword", "operation" "modify replace", "value" \[ "123qwe" ] } ] modify password at next login operation modify inputs "dn" "cn=john doe,ou=friends,dc=testdomain,dc=local", "changes" \[ { "attribute name" "pwdlastset", "operation" "modify replace", "value" \[ "0" ] } ] update system operation modify inputs "dn" "cn=john doe,ou=friends,dc=testdomain,dc=local", "changes" \[ { "attribute name" "operatingsystem", "operation" "modify replace", "value" \[ "windows server 2012" ] } ] update container operation modify inputs "dn" "cn=john doe,ou=friends,dc=testdomain,dc=local", "changes" \[ { "attribute name" "email", "operation" "modify replace", "value" \[ "new email\@example com" ] } ] custom update operation modify inputs "dn" "cn=john doe,ou=friends,dc=testdomain,dc=local", "changes" \[ { "attribute name" "sn", "operation" "modify replace", "value" \[ "swimlane" ] } ] modify user with csv export operation modify inputs "dn" "cn=john doe,ou=friends,dc=testdomain,dc=local", "changes" \[ { "attribute name" "useraccountcontrol", "operation" "modify replace", "value" \[ "512" ] } ], "to csv" true link to ldap operations documentation https //ldap3 readthedocs io/en/latest/operations htmllink to ldap bind and sasl documentation https //ldap3 readthedocs io/en/latest/bind html#sasllink to ldap modify operation documentation https //ldap3 readthedocs io/en/latest/modify html in the case of using the ldap modify connector action, please pass the input changes parameter as shown below "changes" \[ {"attribute name" "memberof", "operation" "modify add", "value" \["cn=group1,ou=groups,dc=testdomain,dc=local"]}, {"attribute name" "memberof", "operation" "modify delete", "value" \["cn=group2,ou=groups,dc=testdomain,dc=local"]}, {"attribute name" "useraccountcontrol", "operation" "modify replace", "value" \["514"]} ] configurations ldap authentication authenticates ldap server configuration parameters parameter description type required host address to the target host string optional domain name domain name string optional port port number number optional user username string optional password password string optional use ssl use ssl boolean optional connect timeout the timeout in seconds for each connection attempt number optional verify ssl verify ssl certificate boolean optional auto bind auto bind string optional authentication simple, anonymous, ntlm, sasl external (mutual tls client certificate), or gssapi (kerberos) string optional sasl external identity optional authorization identity string for sasl external omit for certificate only auth string optional tls ca cert b64 optional base64 encoded ca bundle (pem) for sasl external / ldaps trust anchors string optional tls client certificate b64 base64 encoded client certificate (pem) for sasl external required unless tls client certificate path is set string optional tls client private key b64 base64 encoded client private key (pem) for sasl external required unless tls client private key path is set string optional kerberos principal client principal for keytab based kinit (for example adminuser\@example com mailto\ adminuser\@example com ) the realm after @ is used for kerberos configuration when kerberos realm is not set string optional kerberos keytab path base 64 encoded keytab file string optional kerberos realm optional kerberos realm (for example example com) defaults to the realm in kerberos principal string optional kerberos domain optional dns domain for the ldap service hostname (for example example com) defaults to kerberos realm lowercased and is used to expand short service hostnames to fqdns string optional kerberos kdc host optional kdc hostname or ip defaults to host when not set string optional sasl kerberos service hostname hostname used in the ldap\@host service principal for gssapi bind if omitted, host or kerberos kdc host is used string optional actions add add a new entry to the ldap directory using the provided distinguished name (dn) and object class input argument name type required description dn string required parameter for add object class array required parameter for add attributes object optional parameter for add attributes cn string optional parameter for add attributes sn string optional parameter for add attributes givenname string optional name of the resource attributes uid string optional unique identifier attributes mail string optional parameter for add attributes userpassword string optional parameter for add to csv boolean optional when true, also return the add operation result as a csv file object input example {"dn" "cn=charles mfmi77,ou=people,dc=example,dc=com","object class" \["top","person","organizationalperson","inetorgperson"],"attributes" {"cn" "charles mfmi77","sn" "mfmi77","givenname" "charles","uid" "charles mfmi77","mail" "charles mfmi77\@example com","userpassword" "your password here"}} output parameter type description file object file file file name string name of the resource file file string output field file file output example {"file" \[{"file" "urn\ swimlane\ playbook run file 29f36333 9778 49ea 96c2 78bbce050c44","file name" "ldap search 20251216t042448z csv"}]} delete remove an entry from the ldap directory using the specified distinguished name (dn) input argument name type required description dn string required parameter for delete to csv boolean optional when true, also return the delete operation result as a csv file object input example {"dn" "cn=nacho libre,ou=friends,dc=testdomain,dc=local"} output parameter type description file object file file file name string name of the resource file file string output field file file output example {"file" \[{"file" "urn\ swimlane\ playbook run file 29f36333 9778 49ea 96c2 78bbce050c44","file name" "ldap search 20251216t042448z csv"}]} modify modify an existing ldap directory entry using the distinguished name (dn) and specified changes input argument name type required description dn string required parameter for modify changes array required parameter for modify changes attribute name string required the ldap attribute that needs to be modified example useraccountcontrol for enabling or disabling a user account changes operation string required the type of modification to be performed on the attribute supported operations are modify add, modify delete, modify replace, modify increment changes value array required the new value(s) for the specified attribute the format depends on the attribute type for example, setting useraccountcontrol to 514 disables an ldap user to csv boolean optional when true, also return the modify operation result as a csv file object input example {"dn" "cn=john doe,ou=friends,dc=testdomain,dc=local"} output parameter type description file object file file file name string name of the resource file file string output field file file output example {"file" \[{"file" "urn\ swimlane\ playbook run file 29f36333 9778 49ea 96c2 78bbce050c44","file name" "ldap search 20251216t042448z csv"}]} search perform an ldap search using a specified base and filter to retrieve directory entries while respecting access controls input argument name type required description search base string required parameter for search search filter string required parameter for search attributes array optional ' ' will return all attributes, '1 1' will return no attributes (as per rfc 4511) and '+' will only return operational attributes (as per rfc 3673) search scope string optional parameter for search page size number optional page size page number number optional page number to csv boolean optional when true, also return the search results as a csv file object input example {"search base" "dc=testdomain,dc=local","search filter" "(&(objectclass=user)(objectcategory=person)(|(cn=john doe)))","page size" 10,"page number" 1} output parameter type description file object file file file name string name of the resource file file string output field file file output example {"file" \[{"file" "urn\ swimlane\ playbook run file 29f36333 9778 49ea 96c2 78bbce050c44","file name" "ldap search 20251216t042448z csv"}]} response headers header description example content type the media type of the resource application/json date the date and time at which the message was originated thu, 01 jan 2024 00 00 00 gmt