LDAP
Standing for Lightweight Directory Access Protocol, LDAP has been widely used for directory servers such as Active Directory. Atlas systems can bind to LDAP servers using LDAP, Kerberos, and SSSD configurations. Please note that this document will only cover the routes that are related to LDAP and not explain how to configure Kerberos and SSSD configurations and add SSL/TLS certificates which should be done prior to binding to a LDAP server.
Basic Operations
The basic operations of LDAP are getting and updating the LDAP configuration file. This file is for client applications (such as ldapsearch
) that use the LDAP libraries.
Get LDAP Configuration File
You can use this route to get the LDAP configuration file.
Request Object
+ URL /api/v2/ldap/conf + Method GET + Headers Content-Type: application/json token: ThisIsNotARealTokenGenerateYourOwnToken + Body {}
Response Object
Returns the LDAP configurations in raw string and an object with raw and json-formatted configurations.
+ Headers X-Powered-By: OpenDrives Access-Control-Allow-Origin: * Content-Type: application/json; charset=utf-8 + Body { "raw": "BASE\tdc=example,dc=com\nURI\tldap://apple.example.com\n\nTLS_REQCERT\tallow\nTLS_CACERT\t/etc/ssl/certs/mycacert.pem\n", "json": { "BASE": "dc=example,dc=com", "URI": "ldap://apple.example.com", "TLS_REQCERT": "allow", "TLS_CACERT": "/etc/ssl/certs/mycacert.pem" } }
Update LDAP Configuration File
You can use this route to update the LDAP configuration file. Please pass conf
in your request body as a raw string.
Request Object
+ URL /api/v2/ldap/conf + Method POST + Parameters conf (string, required, Body) - The raw configuration file string to set the ldap config in /etc/ldap/ldap.conf + Headers Content-Type: application/json token: ThisIsNotARealTokenGenerateYourOwnToken + Body { "conf": "BASE\tdc=example,dc=com\nURI\tldap://apple.example.com\n\nTLS_REQCERT\tallow\nTLS_CACERT\t/etc/ssl/certs/mycacert.pem\n" }
Bind Operations
Bind to LDAP Server
Use this route to bind to a LDAP server. Please pass the URL of your LDAP server as a value of ldapServer
in your request body.
Request Object
+ URL /api/v2/ldap/bind + Method POST + Parameters ldapServer (string, required, Body) - The LDAP Server you would like to bind to. + Headers Content-Type: application/json token: ThisIsNotARealTokenGenerateYourOwnToken + Body { "ldapServer": "ldap01.example.com" }
Response Object
The response will include your LDAP server’s information.
+ Headers X-Powered-By: OpenDrives Access-Control-Allow-Origin: * Content-Type: application/json; charset=utf-8 + Body { "raw": "# extended LDIF\n#\n# LDAPv3\n# base <dc=example,dc=com> (default) with scope subtree\n# filter: (objectclass=*)\n# requesting: ALL\n#\n\n# example.com\ndn: dc=example,dc=com\nobjectClass: top\nobjectClass: dcObject\nobjectClass: organization\no: example.com\ndc: example\n\n# admin, example.com\ndn: cn=admin,dc=example,dc=com ..." }
Check Bind Status
Check whether your system is bound to an LDAP server or not.
Request Object
+ URL /api/v2/ldap/bind_status + Method GET + Headers Content-Type: application/json token: ThisIsNotARealTokenGenerateYourOwnToken + Body {}
Response Object
The response will include the first entry of running a ldapsearch command: ldapsearch -x -H ldap://ldap01.example.com -z 1 -ZZ
.
+ Headers X-Powered-By: OpenDrives Access-Control-Allow-Origin: * Content-Type: application/json; charset=utf-8 + Body { "message": "Your system is bound to ldap://apple.example.com", "result": "# extended LDIF\n#\n# LDAPv3\n# base <dc=example,dc=com> (default) with scope subtree\n# filter: (objectclass=*)\n# requesting: ALL\n#\n\n# example.com\ndn: dc=example,dc=com\nobjectClass: top\nobjectClass: dcObject\nobjectClass: organization\no: example.com ..." }
Provide LDAP Admin Password to Samba
In order for Samba service to work with your LDAP server, it needs to know the LDAP Admin DN’s password. Sending this request will make smbpasswd -w
command with the provided password. This step must be done after configuring Samba configurations with your LDAP server’s information but before restarting smbd.service.
Request Object
+ URL /api/v2/ldap/smbpasswd + Method POST + Headers Content-Type: application/json token: ThisIsNotARealTokenGenerateYourOwnToken + Parameters password (string, required, Body) - The LDAP Administrator DN's password. + Body { "password": "YourLdapAdminDnPassword" }
Response Object
smbpasswd
command that this route executes doesn’t know if the provided password is correct or not. Therefore it will never return an error message after the command is executed unless there was a problem in the server to run this command. Furthermore, if the command is successful, an empty string will be returned. The only way to find out if you have provided the correct password is to restart smbd.service and check its status. If you see an error message saying "Invalid Credentials", please make this route again with a correct LDAP Admin DN’s password.
+ Headers X-Powered-By: OpenDrives Access-Control-Allow-Origin: * Content-Type: application/json; charset=utf-8 + Body { "message": "" }
Unbind LDAP Server
Unbind process includes: clear SSSD cache, update LDAP configuration file, delete the individual Kerberos and SSSD configuration files, update the global SSSD configuration file, restart sssd.service. Please make sure to remove Samba configurations that are related to LDAP before using this Unbind route. Also it is a courtesy to clean up the host/computer entry from the domain after leaving/unbinding from the domain server.
Request Object
+ URL /api/v2/ldap/leave + Method POST + Parameters providerName (string, required, Body) - Custom name to identify your authentication provider across the OpenDrives UI. domain (string, required, Body) - The domain of the server you are trying to leave. + Headers Content-Type: application/json token: ThisIsNotARealTokenGenerateYourOwnToken + Body { "providerName": "examplecom", "domain": "example.com" }
Response Object
Returns a message containing whether binding is successful or not. If you want to make sure your system is disconnected from your LDAP server, please make a bind_status
request.
+ Headers X-Powered-By: OpenDrives Access-Control-Allow-Origin: * Content-Type: application/json; charset=utf-8 + Body { "message": "Successfully left the domain! We are unable to retrieve the domain user's information anymore." }