ProcessMaker - Windows Single SignOn V 2.0.x

Introduction

The Windows Single SignOn Plugin is an extension that can be installed in a ProcessMaker server in order to bring the ability to use Active Directory accounts like normal ProcessMaker accounts and enable Windows Single SignOn. It means that this enable users to automatically login into ProcessMaker, skipping the login screen, using their Active Directory account. Since ProcessMaker is running in Linux and Active Directory is running under windows, Processmaker uses a third party software, named PLEXCEL.

How the plugin works

During the installation you will create a plexcel user in active directory. This user will be the link from ProcessMaker and Active Directory. The first time the user logins into ProcessMaker, ProcessMaker logins into Active Directory (using plexcel user) and verifies if the user exists in the server. If the user exists in Active Directory and not in ProcessMaker, the plugin will create the user in ProcessMaker (this will not import the password).

As follows, you will find a brief summary of this:

• Windows Single SignOn plugin works for Microsoft Active Directory and it uses user's accounts credentials to login into ProcessMaker. Also this plugin allows you to maintain synchronized your server's account list with the ProcessMaker account list.

• New accounts created in the Active Directory will be also created in ProcessMaker.

• For employees/accounts resign from the company anymore, but still have their accounts in Active Directory, move them to "Terminated" OU and ProcessMaker will consider them like disabled accounts.

• Current version of this plugin also synchronizes groups.

• For accounts created using Windows Single Sign-On plugin, the authentication is replicated on your Active Directory Server, ProcessMaker doesn't save the real password, just verify the password when logging in by a trusted connection with Active Directory Server.

Requirements

Access to Active Directory Server

• An Active Directory server running.
• Credentials for a valid account in the Active Directory server, with administrator permissions
• DNS Domain entries, in case your network requires them.
• We recommended that the user who is doing the installation has access to Active Directory Server to check the logs for both Windows Single Sign On Plugin and Plexcel Libraries.
• Must verify that the Active Directory Server and Plexcel Server are synchronized (their time must not surpass 5 minutes)

Plexcel's license

- It supports an unlimited number of users and groups for 60 days after which it will not support more than 25 users or 25 groups. In this case a license must be acquired.

Installation and Configuration

Download Plexcel Operator's Manual to have a complete guide on how to install plexcel.

Plexcel Component

Install Plexcel Component

You should follow the steps below in order to install Plexcel Components (plexcel-2.7.26.tar.gz is the last version tested with the plugin)

• Download the file plexcel-2.7.26.tar.gz (This is version has been tested to works properly in ProcessMaker).

• Extract the compressed file of plexcel provided (plexcel-2.7.26.tar.gz is the last version tested with the plugin), execute file as root:

# apachectl stop
# tar -xvzf plexcel-2.7.26.tar.gz
# cd plexcel-2.7.26
# ./install

• To enable plexcel extension, add or uncomment the following line from the php.ini file

extension=plexcel.so

• During the installation you should get a Warning installation is not complete. Create an HTTP service account is not required for ProcessMaker.

• Modify the plexcel.ini file. This file can be located in /etc/php.d/ for RedHat or /etc/php5/cli/conf.d/ for Ubuntu. Then add the DNS server IP where the connection will be set up as shown in below:

• To make sure the IP is pointing correctly modify the phosts and add SRV record information that plexcel needs to connect to the Active Directory server, this file is usually located at /var/lib/plexcel

• Modify the level log from 1 to 5. 1 meaning it will log only the most critical issues and 5 meaning it will log every event. This is only recommended for testing purposes, for the main reason that the log will increase in size rapidly.

• We need to verify that the DNS server is properly setup. To verify we can use the NSLOOKUP in windows and DIG command in Linux. If we are not able to see the DNS server we need to open and modify PHOST file. This file can be found in /var/lib/plexcel/ for RedHat and /var/lib/plexcel/ in Ubuntu.

• Add SRV record information that plexcel needs to connect to the Active Directory server

ldap._tcp.[Domain Name] 		SRV 0 0 389 	[Active Directory Server Name].[Domain Name]
_kerberos._tcp.[Domain Name] 	        SRV 0 0 88 	[Active Directory Server Name].[Domain Name]
_ldap._tcp.dc.[Domain Name] 	        SRV 0 0 389 	[Active Directory Server Name].[Domain Name]
_kerberos._tcp.dc.[Domain Name] 	SRV 0 0 88 	[Active Directory Server Name].[Domain Name] 

[Active Directory Server Name].[Domain Name] IN A [IP address of Active Directory Server]

• Finally restart apache service.

# apachectl start

Setup Plexcel Component

After installing the plexcel component for PHP, Plexcel must be configured, for this click on ADMIN > Plugins> Enterprise Plugins Manager in the list of plugins enterprise.

To configure Windows SSO, select Windows Single SignOn plugin from the list and click the ADMIN button.

This will open the following screen.

If a response has been achieved in the specified domain, then proceed to enter data from a user with administrator permissions.

Then it is asked to create an unique user, in this way Plexcel can set the connection to the Active Directory server.

Proceed to create the user, the data suggested by the wizard configuration of Plexcel is used.

Once created, the user should proceed to change the password.

After changing the server password it is necessary to restart the apache on the server.

Active Directory

Active Directory Authentication

• ProcessMaker has a plugin-able RBAC authentication design.

• This design allows to define an own ways to Verify authentication for users.

• This plugin is an example of how extent RBAC to allow users to be authenticated with Active Directory

• A connection needs to be defined, this connection is called Authentication Source.

• An Authentication Source, basically it is the server and the port of Active Directory server.

• PM creates a record for the user in the database with a flag that this user should be authenticated against Active Directory.

Setup an Authentication Source

To configure the authentication source go to ADMIN > Users > Authentication source.

This panel shows on the top a link to create a new authentication source, and on the bottom an authentication sources list.

In order to create a New Authentication Source, Click on New to create an authentication source.

After that define the fields in the authentication source form:

Where:

• Name: The name to identify the authentication source.
• Enable/dsable automatic register: Enable/disable automatic register of new users
• Server Name: The server name needs to be a valid Active Directory server. (Load automatically from the plexcel configuration).
• Port: The port of the LDAP service (Load automatically from the plexcel configuration).
• Base DN: The base DN is the base from all the searchs will be done. (Load automatically from the plexcel configuration
• OU for retiredEmployees OU: The OU Terminated is used for the fired/disabled OU, that means all accounts moved to this OU.

Note Select YES in the enable automatic register.

Once the authentication has been configured you will be able to import user and departments using WindowsSSO.

Authentication Source List

In this list there is the name, provider, server name and port for every one of the authentication sources.

Also there are three link options:

• Edit: This link field takes the user to the same panel for the creation of an authentication source, with the filled fields.
• Delete: This link field deletes the authentication source.
• Import Users: This link field imports the users from the created authentication source.
• Synchronize Departments: This link show the tree of the OU in the Active Directory.
• Synchronize Groups: This link show the list of the groups in the Active Directory.

Import Users

To import click on the Import Users link.

On the panel Search introduce a Keyword: This field is used to make queries to database and retrieve as many users as matches the keyword. The search is a *keyword* pattern.

Click on search to see a list that matches the keyword typed. The list has the following fields:

• [SELECT-ALL]:This check box field is to select the user. If the user has already been imported a text User name already exists:(name), will show instead of the check box. Press on [SELECT-ALL] so all the users can be checked at once.
• Name: This field shows the user's complete name.
• E-Mail: This field shows the user's email.
• Distinguished Name: This field shows the users DN. The DN is a chain of information needed to validate a user, such as the user name, domain, etc.
• Import: This button is to import the checked users.

windowsSSO plugin uses the User Identifier Field to check if an account was previouly imported or not.

Synchronize Departments

In the tree will display all existing departments in the "Active Directory" server in a hierarchy way, each department has a checkbox on the right side, which allows it to be selected or deselected for consideration by the cron for the synchronization.

For departments that were selected and the cron running, will display the number of users that belongs to them, which were successfully imported to PM.

Once selected and / or deselect the departments, to save the changes it must be pressed button "Save Changes", which is located at the bottom right.

Synchronize Groups

In the tree will display all existing groups in the "Active Directory" server in a hierarchy way, each group has a checkbox on the right side, which allows it to be selected or deselected for consideration by the cron for the synchronization.

For groups that were selected and ran the cron will display the number of users that belong to them, which were successfully imported to PM.

Once selected and / or deselect the groups, to save the changes it must be pressed button "Save Changes", which is located at the bottom right.

Automatic User Registration

This feature and the Synchronization are very useful, because the ProcessMaker administrator doesn't need to create one by one every account in ProcessMaker. meanwhile the Synchronization create and syncronize users in specific departments, the automatic register will create an account in ProcessMaker for users who are not created in ProcessMaker but already created in Active Directory.

The new created user should go to ProcessMaker login page and then provide their Active Directory password and the plugin after check the password will create a new account in ProcessMaker automatically.

The user is created with the PM_OPERATOR Role.

This feature can be enabled or disabled in the Authentication Source Form.

Probably if the automatic Synchronization is enabled, this feature should be disabled.

Disabled or Fired accounts

For employees/accounts resigned from the company, but still accounts in Active Directory, this plugin allows to define an OU for these ex-valid users. This OU is for to move them to the Terminated OU.

ProcessMaker will consider them like disabled accounts.

The syncronize process will check for every user his current OU, if the OU for any user is the same as the OU specified in the Terminated OU, that user will be disabled.

Log for Monitor Active Directory activities

New version of the plugin creates automatically a text log for all activities.

This log is very useful for debug purposes, or just to see what is happening with the plugin.

This log is located in shared/log/windowsSSO.log

there is only one log file for all workspaces.

the methods logged are:

• Bind to server like anoymous or with user credentials
• Sucessful logins for accounts
• Unsucessful logins
• Filter used in searchs
• How many users are returned in each search
• Accounts automatic registered
• OUs syncronized

Also logs the Active Directory error, and the error message in case there are an error in the connection.

Enable The Plugin

Finally enable the plugin on ProcessMaker

Setup Browser to enable Windows Single SignOn

To enable Windows Single SignOn functionality it is necessary to configure the browsers in which the system will be used, in Mozilla Firefox enter the advanced settings, this is done by entering in the address bar "about: config", once there look for the word "trusted" and in the 2 results that appear add the servers where are installed ProcessMaker and Plexcel (if there are many separated them by commas).

On Internet Explorer enter Tools -> Internet Options -> Advanced and check that the option Enable Integrated Windows Authentication is enabled.

Then enter to Tools -> Internet Options -> Security and both Internet and Local Intranet verify that it is selected the option Automatic logon with current user and password.

Finally enter into Tools -> Internet Options -> Security -> TrustedSites -> Sites and add the names of the places where it is installed and ProcessMaker and Plexcel.

• Once all this has been setup correctly. We just need to open an explorer and enter the correct URL to start ProcessMaker:
• The entire URL must be entered correctly, to login automatically to ProcessMaker.

Setting up the License

Installing the License

Once you have purchase or given Plexcel license from ProcessMaker (license.key), you need to copy this file to the plexcel directory.

Moving New license to a new server

Move the license.key from the old server to new server.

Setup Group Policy (optional)

With the group policies it is possible to set by default the configuration required to enable the Windows Single SignOn for all computers that authenticate to the domain, so it can be avoided the manual configuration on each computer.