Authentication Providers

You can bind your OpenDrives systems to your domain server in order to use your system with domain usernames and passwords. (Currently we support Active Directory as well as LDAP. For more information on LDAP Binding, please see the API documentation for the LDAP related endpoints.)

Basic Operations

The basic operations of authentication providers are getting the bind status, checking the domain server’s information, joining your system to the domain, and leaving from the domain.

Lookup DNS

Send this request to check if your domain and nameserver are correct by using this route before joining your system to the domain.

Request Object

+ URL
  /api/v2/authorization/provider/ad/lookup_dns

+ Method
  POST

+ Headers
  Content-Type: application/json
  token: ThisIsNotARealTokenGenerateYourOwnToken

+ Body
  {
    "domain": "opendrives.com",
    "nameserver": "192.168.1.100"
  }

Response Object

You should get the information about your domain server if you provided correct domain and nameserver. Otherwise the response will return error saying either domain or nameserver you provided is wrong.

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

+ Body
  {
    "stdout": "Using domain server:\nName: 192.168.1.100\nAddress: 192.168.1.100#53\nAliases: \n\n_gc._tcp.opendrives.com has SRV record 0 100 3268 mainserver.opendrives.com.\n"
  }

Test Join

Send this request to check if your system is joined to the domain.

Request Object

+ URL
  /api/v2/authorization/provider/ad/testjoin

+ Method
  GET

+ Headers
  Content-Type: application/json
  token: ThisIsNotARealTokenGenerateYourOwnToken

+ Body
  { }

Response Object

You should get the current join status of your system.

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

+ Body
{
    "message": "Join is OK\n"
}

Join Domain

Send this request to join a system to your domain. Please provide an admin username (e.g. a username that’s in Administrators or Domain Admins group) and its password in order to join the domain. After this is complete, please remember to restart the winbind and smbd services.

Prerequisites
Unlike binding to the domain using OpenDrives user interface, using this route to join the domain will not alone change SMB authentication to Active Directory. You must first complete the steps outlined below in order to mount SMB shares with domain user credentials.

  • First, make sure the network time is correctly configured for the system. It should be using the same network time server as the Domain Server.

  • Second, use the SMB API endpoint to create an individual authentication configuration file.

  • Last, use the SMB API endpoint to include your individual authentication configuration file in the smb global authentication configuration file.

  • More information on the SMB API endpoints referenced above are available under the "Create Individual Authentication Configuration File" and "Set Global Authentication Configuration File" sections on the SMB page of our API documentation.

Request Object

+ URL
  /api/v2/authorization/provider/ad/join

+ Method
  POST

+ Headers
  Content-Type: application/json
  token: ThisIsNotARealTokenGenerateYourOwnToken

+ Body
  {
    "username": "administrator",
    "password": "YouAdministratorPassword!"
  }

Response Object

You will be returned a message confirming the outcome of the request.

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

+ Body
  {
    "message": "Using short domain name -- DOMAIN\nJoined 'HOSTNAME' to dns domain 'DOMAIN_NAME'\n"
  }

Leave Domain

Request for leaving domain is similar to joining domain. You need: username, and password. Please remember, once you leave the domain, you will need to remove your system’s name from the domain’s Computers list. You will also need to remove the individual authentication configuration file created during the join process, remove the reference to that configuration file in the global smb authentication configuration file, and restart the smbd and winbind services.

Request Object

+ URL
  /api/v2/authorization/provider/ad/leave

+ Method
  POST

+ Headers
  Content-Type: application/json
  token: ThisIsNotARealTokenGenerateYourOwnToken

+ Body
  {
    "username": "administrator",
    "password": "YourAdministratorPassword!"
  }

Response Object

You will get a success message when your system successfully leaves the domain.

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

+ Body
  {
    "message": "Deleted account for 'USERNAME' in realm 'OPENLAB.COM'\n"
  }

Flush Cache

Send this request to flush the Samba net cache.

Request Object

+ URL
  /api/v2/authorization/provider/ad/flush_cache

+ Method
  GET

+ Headers
  Content-Type: application/json
  token: ThisIsNotARealTokenGenerateYourOwnToken

+ Body
  { }

Response Object

You will get a success message when your system successfully flushes cached domain users and groups.

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

+ Body
  {
    "message": "Successfully cleared the cache of domain users and groups."
  }