DreamFactory Active Directory authentication over LDAP

Table of contents

DreamFactory 2.0 has built-in support for Active Directory authentication over LDAP. Developers can now provide the ability for their users to sign in using their enterprise/corporate login credentials. In other words, you can now easily set up an enterprise app to allow users to sign in using their corporate username and password, eliminating the need for creating and remembering yet another set username and password for their app.

AD/LDAP in DreamFactory 2.0 works just like other services in DreamFactory. It starts with provisioning an AD/LDAP service using the Services tab in the DreamFactory 2.0 admin console. While provisioning the service, simply specify your Active Directory server details such as hostname, base DN etc., as well as a default role. This role will be used for any users authenticating using your AD/LDAP service. You can easily create a role in DreamFactory 2.0 using the admin console. Here is a short how-to on setting up an AD/LDAP service with DreamFactory 2.0. We will start with setting up a role for our AD/LDAP service.

Creating a role in DreamFactory 2.0

  1. Log into the DreamFactory 2.0 admin console using your admin account and click on the ‘Roles’ tab.
  2. From the left action pane click on the ‘Create’ button to create a new role. Provide a name and description for your role and make sure the ‘Active’ checkbox is checked.Roles screenshot
  3. Once the basic role information is entered, click on the ‘Access’ tab. This is where you specify what services/components your role has access to. You can pick any services that are provisioned in the system and set the access level. For our AD/LDAP service I am allowing access (GET, POST, PUT, PATCH, DELETE) to all components of the ‘files’ service (a local storage service) and only allowing GET requests to the ‘system’ service and all sub-components of the ‘app’ component.Create role screenshot
  4. Click on ‘Create Role’ button to create the role ‘AD_Role’.

Provisioning an AD/LDAP service

  1. From the DreamFactory 2.0 admin console, click on the ‘Services’ tab and then click on the ‘Create’ button from left action pane. This will bring up the ‘Info’ tab of the service creation page. Under Service Type, select ‘AdLdap integration’ from the drop down list. Provide a short, meaningful, one word name for your service. In this case I am using ‘demo’. Enter label, description, and check the ‘Active’ checkbox.Create services screenshot
  2. After filling out the basic service information, click on the ‘Config’ tab. Fill out this form, starting with selecting the ‘Default Role’ that we created in the earlier steps. Enter your AD server Host name and Base Dn. Optionally you can enter the Account Suffix here.Create services screenshot
  3. Click on the ‘Create Service’ button to create this AD/LDAP service. Now you are all set to use your newly created AD/LDAP service.

Authenticating using AD/LDAP service in DreamFactory 2.0

The ‘demo’ AD/LDAP service that we just provisioned is now ready for users to authenticate against an AD server over LDAP using a POST API call like this:

curl -i -k -X POST https://example.com/api/v2/user/session?service=demo
-d ‘{“username”:”jdoe”,”password”:”secret”}’

Alternatively you can also put the service name in the JSON payload, removing it from the url parameter like below.

curl -i -k -X POST https://example.com/api/v2/user/session
-d {“username”:”jdoe”, “password”:”secret”, “service”:”demo”}

DreamFactory 2.0 also includes all active AD/LDAP services in the system environment data. You can get the system environment data using a simple GET call.

curl -i -k -X GET https://example.com/api/v2/system/environment

The response from this call includes system authentication information, which shows APIs and services available in the system for logging in. This will help you create a proper login UI based on the services available in the system. Here is a sample response from ‘system/environment’ call showing the adldap services data.

{
...
"authentication": {
...
"adldap": [
{
"path": "user/session?service=demo",
"name": "demo",
"label": "AD/LDAP Demo",
"verb": "POST",
"payload": {
"username": "string",
"password": "string",
"service": "demo",
"remember_me": "bool"
}
}
]
},
}