Introducing Alternate User Authentication in DreamFactory 2.11

DreamFactory supports all kinds of authentication schemes out of the box, including traditional native authentication (managing users and passwords in its own database), OAuth 1.0 and OAuth 2.0, as well as OpenID Connect and SAML 2.0. While these options cover most authentication scenarios, there are situations where none of these solutions work. For these cases, DreamFactory 2.11 includes an alternate user authentication feature that allows you to use your own database and user table for DreamFactory user authentication. 

Using the alternate authentication feature involves setting up your user database as a DreamFactory database service, configuring the built-in ‘User’ service with your database service for users, and specifying the table and fields involved in your authentication process. We'll go over the configuration and usage details below.

Note: Alternate authentication is only applicable to non-admin DreamFactory users. DreamFactory admin users are different and always use DreamFactory's native authentication.

Configure DreamFactory for Alternate Auth

Before you start configuring your DreamFactory instance for alternate authentication, you'll need to enable a configuration setting in your .env file. Open the .env file sitting in your DreamFactory installation root and for the following option:

## By default DreamFactory uses its own database table to authenticate all users.

## You can change that by setting the alternate auth flag below to 'true'.

## This will then allow you to configure the DreamFactory 'user' service with

## another DB service and table/fields information required for your

## custom/alternate authentication.

#DF_ENABLE_ALTERNATE_AUTH=false

Uncomment the line #DF_ENABLE_ALTERNATE_AUTH=false and set this option to true. It should look like this after your changes.

## By default DreamFactory uses its own database table to authenticate all users.

## You can change that by setting the alternate auth flag below to 'true'.

## This will then allow you to configure the DreamFactory 'user' service with

## another DB service and table/fields information required for your

## custom/alternate authentication.

DF_ENABLE_ALTERNATE_AUTH=true

After you enable the feature, log into your DreamFactory instance as an admin, head over to the ‘Services’ tab and select the ‘user’ service. Select the ‘Config’ tab of the user service. You should see some additional configuration fields with the “Alt. Auth.” prefix. We will go over configuring all these fields below.

NOTE: All field names are case sensitive. Make sure field names you specify here exactly match your actual field names.

• Alt. Auth. DB Service: Required. Select the database service that you will use for your alternate auth. This is the DreamFactory service for the database where your user table resides.
• Alt. Auth. Table: Required. Specify the table name that holds your user information. Table name is case sensitive so be very specific.
• Alt. Auth. Username field: Required. Specify the field name of your user table that holds the username. This is the username field that your user authenticates against. For example, if you are using email for authentication and your email field is called ‘email_address’, then put ‘email_address’ here.
• Alt. Auth. Password field: Required. Specify the field name of your user table that holds user password. Currently plain text (should avoid), md5, and bcrypt (recommended) hashes are supported for passwords.
• Alt. Auth. Email field: Required. Specify the field name of your user table that holds user email address. This is required, as the email address will be used by DreamFactory to keep track of your users within DreamFactory.
• Alt. Auth. Other field(s): Optional. If your authentication process requires checking other fields in addition to username and password, then you can specify those field(s) here. Separate multiple fields by comma. You can pass the values for these fields using request parameter or body, along with your username and password. For example, let’s say you want users to specify their country of residence to log in to your app. Assuming that the country field in your user table is ‘country’, you will specify this field name here. And your authentication payload will look like below assuming your username and password fields are ‘username’ and ‘password’. If you specify a field name here then you must pass the value for this field in your request payload. The authentication process will try to match all fields for successful authentication.

{

  "username":"jdoe",

  "password”:"secret",

  "country":"U.S.A"

}

• Alt. Auth. Field field(s): Optional. If you'd like to limit authentication to a certain type/group of user (example: all active users only) then you can specify the filter here. Filters can be specified by field=value format. Multiple filters can be separated by comma and will be used with the AND operator. Example: field1=value1,field2=value2

Using DreamFactory Alternate Auth

Using the alternate authentication configuration you just set up is easy. You don’t have to do anything special to use it. You're going to use the same API endpoint that you would normally use to authenticate into DreamFactory (learn more here). Internally, DreamFactory will use your alternate auth configuration to perform the authentication using your own database and user table. Note that for alternate auth you will use the key name 'username' in your payload, not 'email', as in the example above.

Behind the Scenes

Behind the scenes during authentication, DreamFactory makes a database service call to your user database service using a filter based on your configured fields and passed in values. If your user is found then this database service call returns the user with the password hash. It then verifies user password by checking the supplied password with the password hash retrieved from the user database service.

This blog post described how to easily set up altenate authentication in DreamFactory. Check out the community forum to discuss this feature or let us know what you think in the comments!