Integrating LDAP in Studio Server

Info: Performing the steps described in this article requires direct server access. Depending upon how your system is hosted and the level of access you have to that system, coordination may be required with your Partner or WoodWing Support team. For a full overview of the steps that need to be done by WoodWing and how to request them, see WoodWing Cloud - Change management.

By integrating LDAP (Lightweight Directory Access Protocol) in Studio Server, user authorizations can be better controlled and user accounts can be better maintained.

With LDAP enabled — which is optional — user authorization is controlled through the LDAP Server rather than through Studio Server.

The process is shown in the following overview:

• When a user logs in, it is validated by LDAP.
• If the account is validated, Studio Server synchronizes it by also making it available in its own database (when missing).
• It will then check if there are any user groups that are defined both in Studio Server and LDAP.
• Only taking those groups into account, if a user is assigned to a certain group in LDAP, that user will be assigned to the corresponding Studio Server user group and removed from other groups as well.

Notes: Studio Server supports both Windows Active Directory and OpenLDAP. See the comments at the end of this article for information about configuring multiple LDAP servers.

Enabling LDAP in Studio Server

Step 1. In the configserver.php file (recommended: config_overrule.php file) for Studio Server, locate the List of LDAP servers section.

/*
// -----------------------------------------------------------------------------
// List of LDAP servers. See '/server/dataclasses/LDAPServer.class.php' for more info.
// -----------------------------------------------------------------------------
require_once BASEDIR.'/server/dataclasses/LDAPServer.class.php';

// Options for the LDAP server.
// To manage groups in Studio Server and not LDAP set GROUPMEMBER_ATTRIB to null.
//    For Windows Active Directory usually: 
//       'AUTH_USER' => '%username%@myldap.mycompany.local', 
//       'AUTH_PASSWORD' => '%password%', 
//       'USERNAME_ATTRIB' => 'sAMAccountName',
//       'GROUPMEMBER_ATTRIB' => 'memberof', 
//       'ATTRIB_MAP' => array('FullName' => array( 'name' ), 'EmailAddress' => 'mail'), 
//		 'FULLNAME_SEPARATOR' => ', ',
//       'GROUP_CLASS' => 'group',
//       'EXCLUDE_USERNAMES' => array('woodwing'),
//       'EMAIL_NOTIFICATIONS' => true
//    For OpenLDAP usually: 
//       'AUTH_USER' => null, 
//       'AUTH_PASSWORD' => null, 
//       'USERNAME_ATTRIB' => 'uid', 
//       'GROUPMEMBER_ATTRIB' => 'memberof',
//       'ATTRIB_MAP' => array('FullName' => array( 'name' ), 'EmailAddress' => 'mail'),
//		 'FULLNAME_SEPARATOR' => ', ', 
//       'GROUP_CLASS' => 'posixGroup',
//       'EXCLUDE_USERNAMES' => array('woodwing'),
//       'EMAIL_NOTIFICATIONS' => true
//
$ldap_options = array(
	'AUTH_USER' => '%username%@myldap.mycompany.local', 
	'AUTH_PASSWORD' => '%password%',                    
	'BASE_DN' => 'DC=myldap,DC=mycompany,DC=local',     
	'USERNAME_ATTRIB' => 'sAMAccountName',              
	'GROUPMEMBER_ATTRIB' => 'memberof',                 
	'ATTRIB_MAP' => array( 
		'FullName' => array( 'name' ),
		'EmailAddress' => 'mail'), 
 	'FULLNAME_SEPARATOR' => ', ',						
	'GROUP_CLASS' => 'group',                           
	'EXCLUDE_USERNAMES' => array('woodwing'),           
	'EMAIL_NOTIFICATIONS' => true						
);

define( 'LDAP_SERVERS', serialize( array(
   //  LDAPServer( LDAP server IP, port number, Primary DNS Suffix, Options: see above )
   new LDAPServer( 'myldap_server', null, 'myldap.mycompany.local', $ldap_options )
)));
*/

Step 2. Move the following outside of the comments so that they become active:

• The first line require_once BASEDIR.'/server/dataclasses/LDAPServer.class.php';
• The last sections $ldap_options and define 'LDAP_SERVERS'

/*
// ------------------------------------------------------------------------------
// List of LDAP servers. See '/server/dataclasses/LDAPServer.class.php' for more info.
// ------------------------------------------------------------------------------

// Options for the LDAP server.
// To manage groups in Studio Server and not LDAP set GROUPMEMBER_ATTRIB to null.
//    For Windows Active Directory usually: 
//       'AUTH_USER' => '%username%@myldap.mycompany.local', 
//       'AUTH_PASSWORD' => '%password%', 
//       'USERNAME_ATTRIB' => 'sAMAccountName',
//       'GROUPMEMBER_ATTRIB' => 'memberof', 
//       'ATTRIB_MAP' => array('FullName' => array( 'name' ), 'EmailAddress' => 'mail'), 
//		 'FULLNAME_SEPARATOR' => ', ',
//       'GROUP_CLASS' => 'group',
//       'EXCLUDE_USERNAMES' => array('woodwing'),
//       'EMAIL_NOTIFICATIONS' => true
//    For OpenLDAP usually: 
//       'AUTH_USER' => null, 
//       'AUTH_PASSWORD' => null, 
//       'USERNAME_ATTRIB' => 'uid', 
//       'GROUPMEMBER_ATTRIB' => 'memberof',
//       'ATTRIB_MAP' => array('FullName' => array( 'name' ), 'EmailAddress' => 'mail'),
//		 'FULLNAME_SEPARATOR' => ', ', 
//       'GROUP_CLASS' => 'posixGroup',
//       'EXCLUDE_USERNAMES' => array('woodwing'),
//       'EMAIL_NOTIFICATIONS' => true
//
*/
require_once BASEDIR.'/server/dataclasses/LDAPServer.class.php';
				
$ldap_options = array(
	'AUTH_USER' => '%username%@myldap.mycompany.local', 
	'AUTH_PASSWORD' => '%password%',                   
	'BASE_DN' => 'DC=myldap,DC=mycompany,DC=local',     
	'USERNAME_ATTRIB' => 'sAMAccountName',              
	'GROUPMEMBER_ATTRIB' => 'memberof',                 
	'ATTRIB_MAP' => array( 
		'FullName' => array( 'name' ),
		'EmailAddress' => 'mail'), 
 	'FULLNAME_SEPARATOR' => ', ',						
	'GROUP_CLASS' => 'group',                          
	'EXCLUDE_USERNAMES' => array('woodwing'),          
	'EMAIL_NOTIFICATIONS' => true				
);

define( 'LDAP_SERVERS', serialize( array(
   //  LDAPServer( LDAP server IP, port number, Primary DNS Suffix, Options: see above )
   new LDAPServer( 'myldap_server', null, 'myldap.mycompany.local', $ldap_options )
)));

Step 3. Fill out the ldap_options as required. For an explanation of each option, see the comments in the configserver.php file. See also Mapping LDAP users with Studio Server user accounts below.

Step 4. Enter your LDAP server configuration in the LDAP_SERVERS object. For details, see the comments in the configserver.php file (recommended: config_overrule.php file).

Tip: The following are examples of matching log on names by using wildcards in the ‘EXCLUDE_USERNAMES' option. Example 1. Use a direct match of the log on name. To directly match the log on name by specifying the exact user name, use: 'EXCLUDE_USERNAMES' => array( 'username' ) Here, the log on name ‘woodwing’ is directly matched: 'EXCLUDE_USERNAMES' => array( 'woodwing' ) Example 2: Match the log on name by using a prefix. To match the log on name by starting with a prefix, use: 'EXCLUDE_USERNAMES' => array( '<prefix>.*' ) Here, the log on name ‘woodwing’ is matched by using the prefix 'wood.*': 'EXCLUDE_USERNAMES' => array( 'wood.*' ) Example 3: Match the log on name by using a postfix. To match the log on name by ending with a postfix, use: 'EXCLUDE_USERNAMES' => array( '.*<postfix>' ) Here, the log on name ‘woodwing’ is matched by using the postfix '*.wing.': 'EXCLUDE_USERNAMES' => array( '.*wing' ) Example 4: Match the log on name by using a infix. To match the log on name through an infix, use: 'EXCLUDE_USERNAMES' => array( '.*<infix>.*' ) Here, the log on name ‘woodwing’ is matched by using the infix '*.odwi.*.': 'EXCLUDE_USERNAMES' => array( '.*odwi.*' )

Linux LDAPS configuration

To make AD/LDAPS work on a Linux server, follow the additional steps below.

Step 1. Get the root certificate for the domain <application>.<customer.com> and copy it to the server into:

/etc/openldap/certs

Step 2. Access the /etc/openldap/ folder and open the ldap.conf file in a text editor.

Step 3. Add the following options (or verify that they are already there):

URI ldaps:// '<application>.<customer.com>'
TLS_REQCERT allow
TLS_CACERTDIR /etc/openldap/certs

Step 4. Restart the Apache (httpd) service.

Mapping LDAP users with Studio Server user accounts

Mapping LDAP with the properties for a user in Studio Server is done through the 'ATTRIB_MAP' setting of the $ldap_options in the configserver.php file (recommended: config_overrule.php file).

The following Studio Server properties can be mapped:

• FullName. Possible values:
• 'name' For mapping to the full name as set in LDAP
• 'sn' For mapping to the surname as set in LDAP
• 'cn' For mapping to the common name as set in LDAP
• array('givenName', 'sn') Use an array to map to multiple LDAP properties

Note: The separator used in the array is the one defined in FULLNAME_SEPARATOR. Its default value is a comma followed by a space ', '.

Examples: FullName' => 'name', FullName' => 'cn', FullName' => array('sn', 'givenName'),

• EmailAddress

Notes:  The values of the FullName and EmailAddress properties are used for identifying the user. When multiple users exist in the system with the same e-mail address, the user settings can become corrupted (especially when used in combination with LDAP). In Studio Server 10.17.0 and any higher version of Studio Server, the 'Authentication' test on the Health Check page provides a warning when multiple users with the same e-mail address are detected.

• Language
• TrackChangesColor
• Organization
• Location

Note: When LDAP is used, the values of the following fields are managed by LDAP and are therefore disabled on the User Maintenance page: New password User cannot change password Password expiration in days Valid from Valid till

Enabling LDAP in PHP

To use LDAP authorization your PHP installation must be LDAP enabled. This means that the following PHP extensions must be installed:

• On Windows:
• php_ldap.dll
• ssleay32.dll
• libeay32.dll

• On Linux:
• php_ldap.so
• openssl.so

Testing the installation

To verify the installation, run the LDAP test on the Studio Server Health Check page.

Step 1. In Studio Server, click Advanced in the Maintenance menu or on the Home page.

A page with all advanced Maintenance features appears.

Step 2. Click Health Check.

The Health Check page appears.

Step 3. Click Clear All to clear all selected tests.

Step 4. Select the test named 'Authentication' and click Test.

The test result should appear as 'OK'. In case the test fails, follow the instructions on the page.

Synchronizing user accounts and user groups

User groups that have already been set up in LDAP can be synchronized by importing them into Studio Server. User accounts are synchronized after successfully logging in, after which an account is created and the user's (LDAP) group memberships are synchronized with Studio Server.

The following data is synchronized:

• User Data: ID, Full Name, Password, and E-mail.
• Group Data: Name, Description.
• Memberships: User groups that are defined both in Studio Server and LDAP are assigned to the user logging in.

Note: When changing the user name in LDAP, Studio Server will automatically update the short user name in its system.

Importing user groups

Step 1. In the Maintenance menu or on the Home page, click User Groups.

The Overview of User Groups page appears.

Step 2. Below the list of groups, click Import User Group.

A page showing all created LDAP user groups appears.

Step 3. Select the user groups to import.

Step 4. Click Import Selection.

Note: This option is only available if Open LDAP or Active Directory are installed.

Step 5. Select the network domain from where you want to import from.

Step 6. (Optional) Apply a query such as “*Admin*” to narrow down the results.

Step 7. Tag the groups you want to import.

Step 8. Click Import.

Step 9. Add the imported groups to the User Authorizations section of the Brand that the users should have access to. by doing the following:

Step 9a. On the Brand Maintenance page, click Add in the User Authorizations section.

Figure: The User Authorizations section on a Brand Maintenance page.

The Authorization Maintenance page appears.

Step 9b. From the User Groups list, choose the user group that needs to be added.

Step 9c. Click Add Authorization.

Lists appear for the Category, Workflow Status and Access Profile.

Step 9d. Make a choice from each list.

Note: Use '<All>' to assign an Access Profile to all Categories and/or Workflow Statuses or choose a Category or Workflow Status from the list to assign the Access Profiles to that combination only.

Example: Imagine an Access Profile named 'Delete disabled' in which the options for deleting files have been disabled. When assigning user group A to Category '<All>', Status '<All>' and Profile 'Delete disabled', all members of user group A will not be able to delete any of the files in the Brand. When assigning user group B to Category '<All>', Status 'For publication' and Profile 'Delete disabled', users from group B cannot delete any files from the Brand that are set to the Workflow status 'For publication'. They can however delete all other files.

Step 9e. Click Update.

Step 9f. (Optional, only necessary when not having chosen '<All>' for both the Category and Workflow Status lists) Continue adding Authorizations for as many Category/Workflow Status combinations as necessary.

Note: When no authorizations are assigned, users can log in but cannot access any of the Brands they have been added to.

Verifying if users are assigned to user groups

Check the column named 'Assigned to User Groups' on the Overview of Users page.

A value of 'Yes' or 'No' can be shown:

• 'Yes' means: the user has been assigned to one or more user groups and therefore has access to one or more Brands.

• 'No' means: the user is created by a content source (such as WoodWing Assets) but has not yet been assigned to a user group and therefore does not have access to any Brands.

Note: The reason why the user has not been assigned to a user group could be because the user has never logged in and its settings have therefore not been automatically updated yet.

Troubleshooting: Even though 'Yes' is shown in the column for a user, that user does not have access to any Brands. Analysis: This happens when the LDAP option 'GROUPMEMBER_ATTRIB’ in the configserver.php file (used for automatically adding a user to a user group) is set to ‘null’. This means that the user is not automatically added to a user group. However, the Overview of Users page incorrectly indicates that the user has been assigned. Solution: Add the user manually to one or more user groups.

Notes

• When LDAP has been configured, users need to enter the short user name when logging in.

Steps when users are deactivated or integration is stopped

Once LDAP is fully up and running and used in production, there will come a time when one of the following scenarios occur:

• A user is deactivated in LDAP.
• The LDAP integration itself is stopped for some reason, for example because it is replaced by an integration with another system.

When this occurs, the credentials of LDAP users who have logged in to Studio Server (including those using one of the client applications that connect to it) are still stored on the server.

As a result, these users are still able to log in using these accounts.

In these scenarios, it is highly recommended to deactivate or remove these accounts from Studio Server to prevent these deactivated users from logging in to the system. For details about how to do this, see Deactivating user accounts versus removing user accounts in Studio Server.