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"
  }

Response Object

Returns a success message in the response body.

+ Headers
  X-Powered-By: OpenDrives
  Access-Control-Allow-Origin: *
  Content-Type: application/json; charset=utf-8

+ Body
  {
    "message": "Successfully set ldap.conf"
  }

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."
  }