Please rate how useful you found this document: 
Average: 3 (2 votes)

Note: Available as of ProcessMaker v.3.2.2. Customers with previous versions should contact support for further instructions.

Introduction

The Windows Single Sign-On Plugin is an extension that can be installed on a ProcessMaker server to allow users to use Active Directory accounts like normal ProcessMaker accounts. This means that users will be able to automatically log in to ProcessMaker without going through the login screen using their Active Directory accounts. For ProcessMaker installations in Linux environments, now Processmaker can use an Apache module named mod_auth_ker.

How the Plugin Works

As part of the plugin configuration, a dummy user will be created in Active Directory. This user will link ProcessMaker and the Active Directory service. The first time that the user logs in to ProcessMaker, ProcessMaker will log in to Active Directory (using the dummy user) and verify that the user exists within the Active Directory.

Below is a brief summary of the procedure described above:

  • The Windows Single Sign-On plugin works for Microsoft Active Directory and uses the user's account credentials to log in to ProcessMaker. The Active Directory account list will be automatically synched with the ProcessMaker account list.
  • New accounts created in Active Directory will be also created in ProcessMaker.
  • For employees that no longer work at the company, but whose accounts are still maintained in Active Directory, move their accounts to the "Terminated" OU so ProcessMaker will consider them disabled.
  • The current version of this plugin also synchronizes groups.
  • For accounts created using the Windows Single Sign-On plugin, the authentication is replicated on your Active Directory server. Remember that ProcessMaker does NOT save the user password, it just verifies the password when logging in via a trusted connection with the Active Directory server.

Requirements

  • A running Active Directory server.
  • Credentials for a valid account with administrator permissions on the Active Directory server.
  • DNS Domain entries, in the case your network requires them.
  • It is recommended that the user doing the installation has access to the Active Directory server to check the logs for Windows Single Sign-On.
  • The Active Directory server and the server where ProcessMaker is installed must be on the same domain.
  • The devices of the users that will have access to ProcessMaker must be on the same domain too.

Configuring the Active Directory Server

Read the following instructions:

  1. Create a dummy user, who will be used to connect the Apache service with the Active Directory server using Kerberos. The dummy user can be a regular user (known as a "service account") without special permissions.
  2. An SPN must be granted for this user. This can be done using a command prompt or the graphical interface. The SPN must follow the format:

    HTTP/<ProcessMaker-hostname>;@domain

    For example:

    HTTP/stack205;@PROCESSMAKER.NET

  3. The Other encryption options → AES 256 bit encryption option must be checked in the dummy user's configuration, as shown in the image below:

Configuring the Linux Server

Follow the instructions below to configure the Linux server where ProcessMaker is installed.

  1. The Linux server must have Kerberos installed and configured according to this guide to exchange tickets with the Active Directory server.

    If the Linux server doesn't have Kerberos, install Kerberos and its tools running the following commands:

    yum install krb5
    yum -y install krb5-server krb5-libs

    Verify the dummy user can request tickets to the Active Directory server by running the following commands:

    kinit pmsso@PROCESSMAKER.NET Password: list Ticket cache: FILE:/tmp/krb5cc_0 Default principal: pmsso@PROCESSMAKER.NET Valid starting Expires Service principal 07/11/2017 16:46:34 07/12/2017 02:46:34 krbtgt/PROCESSMAKER.NET@PROCESSMAKER.NET renew until 07/12/2017 16:46:17

  2. Generate the .keytab file by following the instructions in this guide.

    For example:

    ktpass -princ HTTP/stack205.processmaker.net@PROCESSMAKER.NET -mapuser pmsso@PROCESSMAKER.NET -crypto AES256-SHA1 -ptype KRB5_NT_PRINCIPAL -pass <USER_PASSWORD> -out C:\Users\Administrator\Desktop\auth_kerb.keytab

    Where <USER_PASSWORD> is the password of the dummy user.

    Verify that the .keytab file was generated correctly by running the following command:

    klist -e -k -t /etc/httpd/auth_kerb.keytab

    A result similar to the one below will be displayed.

    Keytab name: FILE:/etc/httpd/auth_kerb.keytab
    KVNO Timestamp           Principal
    ---- ------------------- ------------------------------------------------------
    3 01/01/1970 00:00:00 HTTP/stack205@PROCESSMAKER.NET (aes256-cts-hmac-sha1-96)

  3. Copy the .keytab file to the folder /etc/httpd/ on the Linux server and grant it the following permissions:

    chown root.apache /etc/httpd/auth_kerb.keytab
    chmod 0640 /etc/httpd/auth_kerb.keytab
  4. The .keytab file will be used to exchange tickets. To verify that the dummy user that was created on the domain can exchange tickets, run:
    kvno HTTP/stack205@PROCESSMAKER.NET
    HTTP/stack205@PROCESSMAKER.NET: kvno = 3
  5. Make sure ProcessMaker has the ldapAdvanced feature enabled.

  6. Create and configure a connection to the Active Directory server to import users, departments and groups to ProcessMaker. This connection must have the Enable Automatic Register option set to "Yes".

  7. Finally, to remove the tickets created in these tests, run:
    kdestroy

Single Sign-On Configuration

Read the following instructions to configure Windows Single Sign-On:

  1. Install the mod_auth_kerb module on the Linux Server. If using CentOS, run following command:

    yum install mod_auth_kerb

    For Amazon Linux servers, use the following command:

    yum install mod24_auth_kerb-5.4

  2. Open the Apache configuration file found at /etc/httpd/conf/httpd.conf and enable the module by removing the semicolon ; at the beginning of this line.

    LoadModule auth_kerb_module modules/mod_auth_kerb.so

  3. Open the pmos.conf file that was configured when ProcessMaker was installed and add the front-end lines in bold to your ProcessMaker configuration, plus the Single Sign-On virtual host configuration after the ProcessMaker configuration, as shown below:

    -------------------------------------------------- # ProcessMaker Configuration Listen portNumber <VirtualHost *:portNumber > ServerName your_processmaker_domain:portNumber DocumentRoot INSTALLATION-DIRECTORY/opt/processmaker/workflow/public_html DirectoryIndex index.html index.php <Directory INSTALLATION-DIRECTORY/opt/processmaker/workflow/public_html> Options Indexes FollowSymLinks MultiViews AddDefaultCharset UTF-8 AllowOverride None Require all granted <IfModule mod_headers.c> Header set Access-Control-Allow-Origin "*" Header set Access-Control-Allow-Headers "Content-Type,Depth,User-Agent,X-File-Size,X-Requested-With,If-Modified-Since,X-File-Name,Cache-Control,Authorization" Header set Access-Control-Allow-Methods "OPTIONS,GET,POST,PUT,DELETE" </IfModule> <IfModule mod_rewrite.c> RewriteEngine On RewriteCond %{REQUEST_FILENAME} !-f RewriteRule ^.*/(.*)$ app.php [QSA,L,NC] </IfModule> ExpiresActive On ExpiresDefault "access plus 1 day" ExpiresByType image/gif "access plus 1 day" ExpiresByType image/png "access plus 1 day" ExpiresByType image/jpg "access plus 1 day" ExpiresByType text/css "access plus 1 day" ExpiresByType text/javascript "access plus 1 day" #Deflate filter is optional. It reduces download size, but adds slightly more CPU processing: AddOutputFilterByType DEFLATE text/html text/css text/plain text/xml text/x-component text/javascript application/x-javascript application/javascript application/json appl </Directory> </VirtualHost> -------------------------------------------------- # Single Sign-On Configuration Listen portNumber <VirtualHost *:portNumber> ServerName your_processmaker_domain:portNumber DocumentRoot INSTALLATION-DIRECTORY/opt/processmaker/workflow/public_html DirectoryIndex index.html index.php <Directory INSTALLATION-DIRECTORY/opt/processmaker/workflow/public_html> Options Indexes FollowSymLinks MultiViews AddDefaultCharset UTF-8 AllowOverride All Allow from all Require all granted <Location /> AuthName "ProcessMaker SSO" AuthType Kerberos Krb5Keytab /etc/httpd/auth_kerb.keytab KrbAuthRealms PROCESSMAKER.NET KrbLocalUserMapping on KrbMethodNegotiate on KrbMethodK5Passwd off KrbServiceName HTTP/stack205@PROCESSMAKER.NET require valid-user </Location> ExpiresActive On ExpiresDefault "access plus 1 day" ExpiresByType image/gif "access plus 1 day" ExpiresByType image/png "access plus 1 day" ExpiresByType image/jpg "access plus 1 day" ExpiresByType text/css "access plus 1 day" ExpiresByType text/javascript "access plus 1 day" <IfModule mod_rewrite.c> RewriteEngine On RewriteCond %{REQUEST_FILENAME} !-f RewriteRule ^.*/(.*)$ app.php [QSA,L,NC] </IfModule> </Directory> </VirtualHost>

    Where:

    • AuthName: (Optional) The name assigned to the authentication.
    • AuthType: The type of authentication, which in this case is Kerberos.
    • Krb5Keytab: The location of the Kerberos .keytab file that was generated on the Active Directory server and copied to the Linux server.
    • KrbAuthRealms: The domain of the Linux server, which must be the same domain of the user's devices.
    • KrbLocalUserMapping: Set this setting to on so the domain won't be added to the usernames obtained from the clients.
    • KrbMethodNegotiate: Enables (on) or disables (off) the use of the Negotiate method.
    • KrbMethodK5Passwd: Enables (on) or disables (off) the use of password-based authentication for Kerberos v5.
    • KrbServiceName: The service name that was registered on the Active Directory server and was also used to generate the .keytab file. This name will be used by Apache for authentication.
    • require valid-user: Set this paramater, so all this configuration only applies if the request is made by an authenticated user to the domain.

    For example:

    # ProcessMaker Configuration <VirtualHost *:80> ServerName 127.0.0.1:80 DocumentRoot /opt/processmaker/workflow/public_html DirectoryIndex index.html index.php <Directory /opt/processmaker/workflow/public_html> Options Indexes FollowSymLinks MultiViews AddDefaultCharset UTF-8 AllowOverride None Require all granted <IfModule mod_headers.c> Header set Access-Control-Allow-Origin "*" Header set Access-Control-Allow-Headers "Content-Type,Depth,User-Agent,X-File-Size,X-Requested-With,If-Modified-Since,X-File-Name,Cache-Control,Authorization" Header set Access-Control-Allow-Methods "OPTIONS,GET,POST,PUT,DELETE" </IfModule> <IfModule mod_rewrite.c> RewriteEngine On RewriteCond %{REQUEST_FILENAME} !-f RewriteRule ^.*/(.*)$ app.php [QSA,L,NC] </IfModule> ExpiresActive On ExpiresDefault "access plus 1 day" ExpiresByType image/gif "access plus 1 day" ExpiresByType image/png "access plus 1 day" ExpiresByType image/jpg "access plus 1 day" ExpiresByType text/css "access plus 1 day" ExpiresByType text/javascript "access plus 1 day" #Deflate filter is optional. It reduces download size, but adds slightly more CPU processing: AddOutputFilterByType DEFLATE text/html text/css text/plain text/xml text/x-component text/javascript application/x-javascript application/javascript application/json appl </Directory> </VirtualHost> # Single Sign-On Configuration Listen 8080 <VirtualHost *:8080> ServerName 127.0.0.1:8080 DocumentRoot /opt/processmaker/workflow/public_html DirectoryIndex index.html index.php <Directory /opt/processmaker/workflow/public_html> Options Indexes FollowSymLinks MultiViews AddDefaultCharset UTF-8 AllowOverride All Allow from all Require all granted <Location /> AuthName "ProcessMaker SSO" AuthType Kerberos Krb5Keytab /etc/httpd/auth_kerb.keytab KrbAuthRealms PROCESSMAKER.NET KrbLocalUserMapping on KrbMethodNegotiate on KrbMethodK5Passwd off KrbServiceName HTTP/stack205@PROCESSMAKER.NET require valid-user </Location> ExpiresActive On ExpiresDefault "access plus 1 day" ExpiresByType image/gif "access plus 1 day" ExpiresByType image/png "access plus 1 day" ExpiresByType image/jpg "access plus 1 day" ExpiresByType text/css "access plus 1 day" ExpiresByType text/javascript "access plus 1 day" <IfModule mod_rewrite.c> RewriteEngine On RewriteCond %{REQUEST_FILENAME} !-f RewriteRule ^.*/(.*)$ app.php [QSA,L,NC] </IfModule> </Directory> </VirtualHost>

  4. Save all the changes and restart the Apache service.

Upgrading From Plexcel to mod_auth_kerb

Warning: The information in this section may change.

ProcessMaker installations that have the Single Sign-on feature working with Plexcel can be reconfigured to use mod_auth_kerb without major complications.

To do this, read the following instructions:

  1. Identify the user that was created to connect Active Directory with Plexcel (Plexcel user) and use it to generate the .keytab file following this guide.

  2. On the Linux server, disable the plexcel extension, add or comment (add the ; symbol) to the following line in the php.ini file:

    ;extension=plexcel.so
  3. Log in to MySQL and change the type of the provider to "ldapAdvanced" in the register that was created for the Single Sign-On plugin in the RBAC_AUTHENTICATION_SOURCE table using the following query:
    UPDATE 'RBAC_AUTHENTICATION_SOURCE' SET 'AUTH_SOURCE_PROVIDER' = 'ldapAdvanced' WHERE 'AUTH_SOURCE_PROVIDER' = 'windowsSSO';
  4. Also update the register in the RBAC_USERS table to change the value of the USR_AUTH_TYPE field to "ldapAdvanced"
    UPDATE 'RBAC_USERS' SET 'USR_AUTH_TYPE' = 'ldapAdvanced' WHERE 'USR_AUTH_TYPE' = 'windowsSSO';
  5. Once the database is updated, log in to ProcessMaker and verify that the configured authentication source can search users with no problems. If not, verify that the Enable automatic register option is enabled.