The RackForms editor can login and authenticate users with Active Directory via LDAP. This process can happen when we first install RackForms, or be applied to an existing installation. To use this feature we must be running RackForms 6 or higher.

Logins are based on active directory account membership to groups we define in the settings described below. It's key to note by AD login we mean the username in RackForms must be sAMAccountName AD property along with the password for that account.

Please note we cannot mix AD and standard RackForms logins with two exceptions:

• The master account created during install process will always access RackForms without AD credentials.
• Any addtional admin (level 9) accounts created using the User Management system.

Put another way, all non-admin accounts created after the install process must use AD authentication.

General Usage

In general, to use this feature, we must:

• Have the PHP LDAP extension installed on our server.
• Select the Use AD Login checkbox on the installer screen (when installing from scratch), or set the AUTH_AD property to 1 in app/config.php (post install)
• Properly configure our app/config.php file with valid AD/LDAP info.

Permission Levels

Before we enable AD login it's important to userstand thr permission model. First, AD installations have fewer effective permission levels than non-AD installs:

• The master admin account created during install (level 9).
• The level we define in app/config.php for the AUTH_AD_CUSTOM_LEVEL_GROUP_NAME_VALUE setting and:
• An optional "View Only" (level 3) AD account for the AUTH_AD_VIEW_ONLY_GROUP_NAME setting.

Thus, when using AD we have at most 3 permission levels.

Second, it's critical to note non-admin permissions are automatically assigned at login based on the current group membership of that user, with view-only access taking top precedent. That is, if a user belongs to the custom level and the view only group, their membership in view only will be applied at login.

Example

As noted above, when we install RackForms a master admin account is created. This account doesn't use AD login.

In your active directory solution create an AD Group for RackForms users. Assign users to it, and enter that group name in the AUTH_AD_CUSTOM_LEVEL_GROUP_NAME properties app/config.php setting.

Update app/config.php and set the AUTH_AD property to 1, and define the proper values for LDAP host, DN, and prefix. Save the config.php file to commit the changes.

Users attempting to access RackForms will have membership to that group checked. If they belong and their AD credentials are accepted, they're logged in using the permission level defined in AUTH_AD_CUSTOM_LEVEL_GROUP_NAME_VALUE.

Optionally then, we can also create a second AD group for users who will have read only access to RackForms. Same as above, to set this up we'll create the AD group, assign users to it, and then provide that AD group name to the AUTH_AD_VIEW_ONLY_GROUP_NAME field in the app/config.php file.

Updating and Managing Permissions

It's key to note when using AD logins we manage access to RackForms via AD group membership alone. We do not use RackForms user-management tools in any way.

Remove: To remove a users access to RackForms simply remove them from the AD group(s). Critically, this includes changes we make to app/config.php settings. That is, if we change the custom level group name to be a value that's not in your AD system, AD users will not be able to login at all.

Update Permission Level: To change the permissions for custom level users, simply update the AUTH_AD_CUSTOM_LEVEL_GROUP_NAME_VALUE configuration value. At the next login the users permissions within RackForms will be updated.

Change Group Membership: To change group membership we have two main paths. The first is to swap users between custom level and view only. To make this change simply make sure the user belongs to the AD group defined in the AUTH_AD_VIEW_ONLY_GROUP_NAME setting. Even if this user also belongs to a custom level group, the view only group overrides that membership and they're automatically placed into the least privileged group. The second path is to change groups in AD. In this workflow, we use our AD management tools to add and remove users from groups as needed. If the user is no longer within a valid custom level group, the next login fails for that user.

Installation And Configuration Details

At this point we hopefully have a good understanding of the overall workflow and purpose of the AD login system. The next step, if you decide this is a system you'd like to deploy, is to configure the server and settings needed to enable AD logins.

1. LDAP Extension

Before we can use Active Directory login, we must have the PHP LDAP extension installed on our server. This extension is generally used on Windows hosts, and for users of Microsoft's Web Platform Installer, is installed by default.

2. Select Use AD Login During Installation

Although not required as we can perform this task in step 3, if we know ahead of time our installation will always use Active Directory login, checking this box will enable Active Directory login for the very first login.

Please note checking this box will not create the master admin login as an AD user. The master account (the one we create during the install process), is never authenticated via AD, and thus can login at any point without needing valid AD credentials. However, any non-admin user who logs into the system after the installation process will use AD.

Finally, it's key to note the User Management system, when using AD logins, is not used for any non-admin users. Any non-admin users we create in this manner will always use AD login and thier access to RackForms is managed soly within AD group membership.

3. Configure app/config.php

In this step we must provide the RackForms config.php file, located at rackforms/app/config.php, the needed configuration data to contact and process AD login requests. This consists of three pieces of data:

1. The LDAP host. This will usually be the domain name of your organization and a port number. See this link for more details on the host value.

2. The domain prefix of your connection, which is used to form a domain name + user name. In the example below, CORP + the user name we type in the login screen would be used.

3. The base distinguished name for the username+password lookup. In Active Directory, user information is stored in a tree-like structure. If we do not point to the right location, an authentication lookup would not know where in the tree to look and will thus fail. The distinguished name property tells the LDAP call where to look for user account info.

The default values our config.php file could contain after are shown below. Note the 1 next to 'AUTH_AD', which means the RackForms instance will use Active Directory logins. Sample values are shown next to each setting.

define('AUTH_AD', '1'); 							// Use AD Authentication. 0 = No, 1 = Yes
define('AUTH_AD_DEBUG', '0'); 						// Debug AD Authentication. 0 = No, 1 = Yes

define('AUTH_AD_CUSTOM_LEVEL_GROUP_NAME', '');      // Blank, otherwise the AD group name that uses the custom level on the next line.
define('AUTH_AD_CUSTOM_LEVEL_GROUP_NAME_VALUE', 7); // The user privilege level for custom ad level users.

define('AUTH_AD_VIEW_ONLY_GROUP_NAME', '');         // Blank, otherwise the AD group name for read only access.

define('AUTH_AD_LDAP_HOST', '');                    // Host Name: e.g. LDAP://corp.sample.com:389
define('AUTH_AD_LDAP_PREFIX', '');                  // Optional AD Domain Prefix: e.g. CORP\\ Note: Must Use Double Slashes After Name.
define('AUTH_AD_LDAP_DN', '');                      // Distinguished Names: e.g. DC=corp,DC=sample,DC=com

To make changes, edit the value in-between the empty single quote marks for that setting.

Updating Existing Installations To Use LDAP

If we have an existing instillation of RackForms we can update the app/config.php file to enforce LDAP logins for all non-admin users. To do so, simply follow the items outlined in step 3. Once saved, these settings will ensure all non-admin users who attempt a login must have valid AD credentials and group membership as defined in the config file.

For the RackForms administrator, one additional step may be required. If the non-admin user who logs in via LDAP had existing jobs, the admin will need to update, via Job Ownership, those items to match with the new AD user. This is because when we login with LDAP, a new user record is created in the fb_admin database table, and this user id will be different than the previous value. As job ownership is tied to this id value, the update is required.