Difference between revisions of "Globalyzer Server LDAP Installation"

From Lingoport Wiki
Jump to: navigation, search
(What Differences Will I see Using LDAP?)
(23 intermediate revisions by the same user not shown)
Line 1: Line 1:
  +
== Overview ==
Configuring Globalyzer LDAP Server
 
 
Many large companies use LDAP to manage user information. As new users are hired, they are entered into the company's LDAP system. When users leave the company, they are removed from the company's LDAP system. LDAP is also used to give user's authority to access certain applications within the company.
 
Many large companies use LDAP to manage user information. As new users are hired, they are entered into the company's LDAP system. When users leave the company, they are removed from the company's LDAP system. LDAP is also used to give user's authority to access certain applications within the company.
   
Line 5: Line 5:
   
 
If the user's phone number, title, last name, etc., is modified in LDAP, then the next time the user logs in to Globalyzer, their Globalyzer account information will be updated with the latest information from LDAP. If the user leaves the company and is removed from LDAP, the user can no longer access their Globalyzer account. All Globalyzer user access and information is managed by LDAP.
 
If the user's phone number, title, last name, etc., is modified in LDAP, then the next time the user logs in to Globalyzer, their Globalyzer account information will be updated with the latest information from LDAP. If the user leaves the company and is removed from LDAP, the user can no longer access their Globalyzer account. All Globalyzer user access and information is managed by LDAP.
How to Configure LDAP
 
LDAP configuration involves two files: enterprise.bat/sh and GzserverConfig.groovy.
 
   
  +
== How to Configure LDAP ==
Gzserver Startup Script for Linux: enterprise.sh
 
  +
LDAP configuration involves setting the environment variable GZSERVER_LDAP_MODE to true, and configuring GzserverConfig.groovy.
  +
  +
=== Setting GZSERVER_LDAP_MODE ===
 
If your server runs on Linux, in the enterprise.sh file, set GZSERVER_LDAP_MODE to true.
 
If your server runs on Linux, in the enterprise.sh file, set GZSERVER_LDAP_MODE to true.
   
  +
#!/bin/sh
enterprise.sh
 
  +
 
  +
export GZSERVER_ENTERPRISE_MODE=true
#!/bin/sh
 
  +
<b>export GZSERVER_LDAP_MODE=true</b>
 
  +
export CATALINA_HOME=/usr/local/tomcat
export GZSERVER_ENTERPRISE_MODE=true
 
  +
...
export GZSERVER_LDAP_MODE=true
 
  +
If your server runs on Windows, and you are using the enterprise.bat file to start/stop your server, set GZSERVER_LDAP_MODE to true:
export CATALINA_HOME=/usr/local/tomcat
 
export GZSERVER_CONFIG=$CATALINA_HOME/secret/GzserverConfig.groovy
 
export JAVA_OPTS="-Xms256m -Xmx1600m -Dstringchararrayaccessor.disabled=true"
 
 
export CATALINA_PID=$CATALINA_HOME/.tomcatpid
 
 
if test $1 = "restart"
 
then
 
echo "Restarting Tomcat"
 
$CATALINA_HOME/bin/catalina.sh stop -force
 
$CATALINA_HOME/bin/catalina.sh start
 
exit 0
 
fi
 
 
if test $1 = "redeploy"
 
then
 
echo "Redeploying Gzserver on Tomcat"
 
$CATALINA_HOME/bin/catalina.sh stop -force
 
rm -rf $CATALINA_HOME/webapps/gzserver
 
rm -f $CATALINA_HOME/webapps/gzserver.war
 
cp $CATALINA_HOME/gzserver.war $CATALINA_HOME/webapps/
 
$CATALINA_HOME/bin/catalina.sh start
 
exit 0
 
fi
 
 
$CATALINA_HOME/bin/catalina.sh $1 $2 $3
 
 
 
Gzserver Startup Script for Windows: enterprise.bat
 
If your server runs on Windows, in the enterprise.bat file, set GZSERVER_LDAP_MODE to true.
 
 
enterprise.bat
 
 
@echo off
 
 
if "%OS%" == "Windows_NT" setlocal
 
 
set "GZSERVER_ENTERPRISE_MODE=true"
 
set "GZSERVER_LDAP_MODE=true"
 
set "CATALINA_HOME=C:\apache-tomcat-8.5.23"
 
set "GZSERVER_CONFIG=%CATALINA_HOME%\secret\GzserverConfig.groovy"
 
set "JAVA_OPTS=-Xms256m –Xmx1600m -Dstringchararrayaccessor.disabled=true"
 
set "CATALINA_PID=%CATALINA_HOME%\.tomcatpid"
 
set "EXECUTABLE=%CATALINA_HOME%\bin\catalina.bat"
 
 
if %1==start goto execStart
 
if %1==stop goto execStop
 
if %1==restart goto execRestart
 
if %1==redeploy goto execRedeploy
 
goto end
 
 
:execStart
 
call "%EXECUTABLE%" start
 
goto end
 
 
:execStop
 
call "%EXECUTABLE%" stop
 
goto end
 
 
:execRestart
 
echo Restarting Tomcat
 
call "%EXECUTABLE%" stop
 
call "%EXECUTABLE%" start
 
goto end
 
 
:execRedeploy
 
echo Redeploying Gzserver on Tomcat
 
call "%EXECUTABLE%" stop
 
rd /s /q %CATALINA_HOME%\webapps\gzserver
 
del /q %CATALINA_HOME%\webapps\gzserver.war
 
xcopy %CATALINA_HOME%\gzserver.war %CATALINA_HOME%\webapps
 
call "%EXECUTABLE%" start
 
goto end
 
 
:end
 
 
   
  +
@echo off
  +
  +
if "%OS%" == "Windows_NT" setlocal
  +
  +
set "GZSERVER_ENTERPRISE_MODE=true"
  +
<b>set "GZSERVER_LDAP_MODE=true"</b>
  +
set "CATALINA_HOME=C:\apache-tomcat-8.5.23"
  +
...
   
  +
If your server runs on Windows and you are running Tomcat as a service, create a new GZSERVER_LDAP_MODE environment variable for the machine, and set it to true.
   
GzserverConfig.groovy LDAP Customization
+
=== Configuring GzserverConfig.groovy ===
 
The bulk of the LDAP configuration takes place in the GzserverConfig.groovy file. There is a section in the file dedicated to LDAP configuration.
 
The bulk of the LDAP configuration takes place in the GzserverConfig.groovy file. There is a section in the file dedicated to LDAP configuration.
   
 
Your company's LDAP stores information for each LDAP user. Map the field names defined in LDAP so that Globalyzer knows how to access the user's first name, last name, etc.
 
Your company's LDAP stores information for each LDAP user. Map the field names defined in LDAP so that Globalyzer knows how to access the user's first name, last name, etc.
   
  +
// ************************ START OF LDAP CONFIGURATION *********************
 
  +
// **
 
  +
// ** Uncomment the following 7 gzserver lines and map them to fields in your LDAP
// ************************ START OF LDAP CONFIGURATION *********************
 
  +
// ** If your LDAP does not have the information per user, leave it as empty string
 
  +
// ** NOTE: It is required that LDAP contains an email field for each LDAP user
// **
 
  +
// **
// ** Uncomment the following 7 gzserver lines and map them to fields in your LDAP
 
  +
//gzserver.ldap.ctx.firstName = ""
// ** If your LDAP does not have the information per user, leave it as empty string
 
  +
//gzserver.ldap.ctx.lastName = ""
// ** NOTE: It is required that LDAP contains an email field for each LDAP user
 
  +
//gzserver.ldap.ctx.email = "mail"
// **
 
//gzserver.ldap.ctx.firstName = ""
+
//gzserver.ldap.ctx.phone = ""
//gzserver.ldap.ctx.lastName = ""
+
//gzserver.ldap.ctx.title = ""
//gzserver.ldap.ctx.email = "mail"
+
//gzserver.ldap.ctx.country = ""
//gzserver.ldap.ctx.phone = ""
+
//gzserver.ldap.ctx.timeZone = ""
//gzserver.ldap.ctx.title = ""
 
//gzserver.ldap.ctx.country = ""
 
//gzserver.ldap.ctx.timeZone = ""
 
   
   
 
For example, if the field name for phone is "telephone" in your LDAP, then change the line in GzserverConfig.groovy to this:
 
For example, if the field name for phone is "telephone" in your LDAP, then change the line in GzserverConfig.groovy to this:
   
  +
gzserver.ldap.ctx.phone = "telephone"
 
gzserver.ldap.ctx.phone = "telephone"
 
 
   
 
If your LDAP does not store a telephone number for LDAP users, then leave the line like this:
 
If your LDAP does not store a telephone number for LDAP users, then leave the line like this:
   
  +
gzserver.ldap.ctx.phone = ""
 
gzserver.ldap.ctx.phone = ""
 
 
   
 
The only required field is email. Your company's LDAP must store email information for each user, since the email field is required to create a Globalyzer account.
 
The only required field is email. Your company's LDAP must store email information for each user, since the email field is required to create a Globalyzer account.
   
 
In addition to user information, your company's LDAP defines groups and group membership. Group membership is used to determine the applications users have access to, as well as the level of access. For Globalyzer, three new groups should be added to your company's LDAP by your company's LDAP administrator:
 
In addition to user information, your company's LDAP defines groups and group membership. Group membership is used to determine the applications users have access to, as well as the level of access. For Globalyzer, three new groups should be added to your company's LDAP by your company's LDAP administrator:
a Globalyzer admin group
+
* a Globalyzer admin group
a Globalyzer manager group
+
* a Globalyzer manager group
a Globalyzer member group
+
* a Globalyzer member group
   
 
Users who have access to Globalyzer will be members of one of these three groups. Your LDAP administrator can choose the group names; below is where you map the groups names defined in LDAP.
 
Users who have access to Globalyzer will be members of one of these three groups. Your LDAP administrator can choose the group names; below is where you map the groups names defined in LDAP.
   
  +
// **
 
  +
// ** Uncomment the following 3 gzserver lines and map them to groups defined in your LDAP
// **
 
  +
// ** The LDAP groups represent globalyzer admin, manager, and member access:
// ** Uncomment the following 3 gzserver lines and map them to groups defined in your LDAP
 
  +
// **
// ** The LDAP groups represent globalyzer admin, manager, and member access:
 
  +
//gzserver.ldap.admin.groupName = "GlobalyzerAdmin"
// **
 
//gzserver.ldap.admin.groupName = "GlobalyzerAdmin"
+
//gzserver.ldap.manager.groupName = "GlobalyzerManager"
//gzserver.ldap.manager.groupName = "GlobalyzerManager"
+
//gzserver.ldap.member.groupName = "GlobalyzerMember"
//gzserver.ldap.member.groupName = "GlobalyzerMember"
 
 
 
   
 
Configure the message that displays if the user logging in is NOT a member of one of the Globalyzer groups defined above.
 
Configure the message that displays if the user logging in is NOT a member of one of the Globalyzer groups defined above.
   
  +
// **
 
  +
// ** Uncomment the following gzserver line and configure
// **
 
  +
// ** This text will be displayed to users who are not members of a
// ** Uncomment the following gzserver line and configure
 
  +
// ** Globalyzer group
// ** This text will be displayed to users who are not members of a
 
// ** Globalyzer group
+
// **
  +
//gzserver.ldap.noaccess = "You are not authorized to access Globalyzer."
// **
 
//gzserver.ldap.noaccess = "You are not authorized to access Globalyzer."
 
 
 
   
 
Next, configure the LDAP server address and then uncomment the providerNames line, as it is already configured correctly.
 
Next, configure the LDAP server address and then uncomment the providerNames line, as it is already configured correctly.
   
  +
// **
 
  +
// ** Uncomment the following grails line and set to the address of the LDAP server
// **
 
  +
// **
// ** Uncomment the following grails line and set to the address of the LDAP server
 
  +
//grails.plugin.springsecurity.ldap.context.server = 'ldap://localhost:389'
// **
 
  +
//grails.plugin.springsecurity.ldap.context.server = 'ldap://localhost:389'
 
  +
// **
 
  +
// ** Uncomment the following grails line; it is already configured properly for LDAP
// **
 
  +
// **
// ** Uncomment the following grails line; it is already configured properly for LDAP
 
  +
//grails.plugin.springsecurity.providerNames = ['ldapAuthProvider','anonymousAuthenticationProvider']
// **
 
//grails.plugin.springsecurity.providerNames = ['ldapAuthProvider','anonymousAuthenticationProvider']
 
 
 
   
 
To authenticate LDAP users, Globalyzer connects to your company's LDAP server, logging in via the information provided below. This can be a read only LDAP account and password.
 
To authenticate LDAP users, Globalyzer connects to your company's LDAP server, logging in via the information provided below. This can be a read only LDAP account and password.
 
 
  +
// **
 
  +
// ** Uncomment the following two grails lines and set to the DN to authenticate with
// **
 
// ** Uncomment the following two grails lines and set to the DN to authenticate with
+
// ** Globalyzer; will connect the LDAP server and log in via this account
  +
// ** <b>See the next section for information on how to encrypt the managerPassword</b>
// ** Globalyzer; will connect the LDAP server and log in via this account
 
// **
+
// **
//grails.plugin.springsecurity.ldap.context.managerDn = 'cn=read-only-admin,dc=example,dc=com'
+
//grails.plugin.springsecurity.ldap.context.managerDn = 'cn=read-only-admin,dc=example,dc=com'
//grails.plugin.springsecurity.ldap.context.managerPassword = 'password'
+
//grails.plugin.springsecurity.ldap.context.managerPassword = 'password'
 
   
 
The rest of the LDAP section of the GzserverConfig.groovy file needs to be configured to perform searches for users and groups.
 
The rest of the LDAP section of the GzserverConfig.groovy file needs to be configured to perform searches for users and groups.
   
  +
// **
  +
// ** Uncomment the following grails line and configure -
  +
// ** The base DN from which the search for group membership should be performed
  +
// **
  +
//grails.plugin.springsecurity.ldap.authorities.groupSearchBase = 'ou=Groups,dc=example,dc=com'
  +
  +
// **
  +
// ** Uncomment the following grails line and configure -
  +
// ** The ID of the attribute which contains the role name for a group
  +
// **
  +
//grails.plugin.springsecurity.ldap.authorities.groupRoleAttribute = 'cn'
  +
  +
// **
  +
// ** Uncomment the following grails line and configure -
  +
// ** The pattern to be used for the user search. {0} is the user's DN
  +
// **
  +
//grails.plugin.springsecurity.ldap.authorities.groupSearchFilter = 'member={0}'
  +
  +
// **
  +
// ** Uncomment the following grails line and configure -
  +
// ** Context name to search in
  +
// **
  +
//grails.plugin.springsecurity.ldap.search.base = 'dc=example,dc=com'
  +
  +
// **
  +
// ** Uncomment the following grails line and configure -
  +
// ** The filter expression used in the user search
  +
// **
  +
//grails.plugin.springsecurity.ldap.search.filter = '(uid={0})'
  +
// ************************ END OF LDAP CONFIGURATION *************************
   
  +
=== Encrypting the LDAP Password ===
// **
 
  +
To support LDAP logins, the Globalyzer Server requires an LDAP account that can connect to your LDAP server and perform reads.
// ** Uncomment the following grails line and configure -
 
  +
As of 6.3, this password may be encrypted, rather that appear in plain text.
// ** The base DN from which the search for group membership should be performed
 
  +
To encrypt the password, you must use the <b>globalyzer-encrypt-password.jar</b> that is available in the Globalyzer-Server.zip file (starting with the 6.3 release).
// **
 
//grails.plugin.springsecurity.ldap.authorities.groupSearchBase = 'ou=Groups,dc=example,dc=com'
 
   
  +
Run the jar to generate an encrypted password:
// **
 
  +
$ java -jar globalyzer-encrypt-password.jar -in "my plain password"
// ** Uncomment the following grails line and configure -
 
  +
Encrypted Password: CLCjzYV02uZaWDTDkcvK65BndTfUlH5leL00vsgWkmY=
// ** The ID of the attribute which contains the role name for a group
 
// **
 
//grails.plugin.springsecurity.ldap.authorities.groupRoleAttribute = 'cn'
 
   
  +
Then place the generated password in the GzserverConfig.groovy file within ENC():
// **
 
  +
grails.plugin.springsecurity.ldap.context.managerPassword = 'ENC(CLCjzYV02uZaWDTDkcvK65BndTfUlH5leL00vsgWkmY=)'
// ** Uncomment the following grails line and configure -
 
// ** The pattern to be used for the user search. {0} is the user's DN
 
// **
 
//grails.plugin.springsecurity.ldap.authorities.groupSearchFilter = 'member={0}'
 
 
// **
 
// ** Uncomment the following grails line and configure -
 
// ** Context name to search in
 
// **
 
//grails.plugin.springsecurity.ldap.search.base = 'dc=example,dc=com'
 
 
// **
 
// ** Uncomment the following grails line and configure -
 
// ** The filter expression used in the user search
 
// **
 
//grails.plugin.springsecurity.ldap.search.filter = '(uid={0})'
 
 
 
// ************************ END OF LDAP CONFIGURATION *************************
 
   
  +
Plain passwords are still supported and are configured like this:
  +
grails.plugin.springsecurity.ldap.context.managerPassword = 'my plain password'
   
 
== Example LDAP Configuration ==
 
== Example LDAP Configuration ==
 
As an example, let's assume that your LDAP has the following directory structure:
 
As an example, let's assume that your LDAP has the following directory structure:
   
dc=example, dc=com
+
dc=example, dc=com
 
ou=Groups
 
ou=Groups
 
cn=GlobalyzerAdmin
 
cn=GlobalyzerAdmin
Line 242: Line 171:
 
The configuration for this is shown below:
 
The configuration for this is shown below:
   
  +
grails.plugin.springsecurity.ldap.authorities.groupSearchBase = 'ou=Groups,dc=example,dc=com'
// **
 
  +
grails.plugin.springsecurity.ldap.authorities.groupRoleAttribute = 'cn'
// ** Uncomment the following grails line and configure -
 
  +
grails.plugin.springsecurity.ldap.authorities.groupSearchFilter = 'member={0}'
// ** The base DN from which the search for group membership should be performed
 
  +
grails.plugin.springsecurity.ldap.search.base = 'dc=example,dc=com'
// **
 
grails.plugin.springsecurity.ldap.authorities.groupSearchBase = 'ou=Groups,dc=example,dc=com'
+
grails.plugin.springsecurity.ldap.search.filter = '(uid={0})'
 
// **
 
// ** Uncomment the following grails line and configure -
 
// ** The ID of the attribute which contains the role name for a group
 
// **
 
grails.plugin.springsecurity.ldap.authorities.groupRoleAttribute = 'cn'
 
 
// **
 
// ** Uncomment the following grails line and configure -
 
// ** The pattern to be used for the user search. {0} is the user's DN
 
// **
 
grails.plugin.springsecurity.ldap.authorities.groupSearchFilter = 'member={0}'
 
 
// **
 
// ** Uncomment the following grails line and configure -
 
// ** Context name to search in
 
// **
 
grails.plugin.springsecurity.ldap.search.base = 'dc=example,dc=com'
 
 
// **
 
// ** Uncomment the following grails line and configure -
 
// ** The filter expression used in the user search
 
// **
 
grails.plugin.springsecurity.ldap.search.filter = '(uid={0})'
 
 
 
// ************************ END OF LDAP CONFIGURATION ***********************
 
 
Please see your LDAP administrator to correctly configure these fields.
 
   
 
== Trouble-Shooting your LDAP Configuration ==
 
== Trouble-Shooting your LDAP Configuration ==
 
If you are having difficulty logging in to your LDAP-configured Globalyzer Server (login is failing, for example), configure the Globalyzer Server to write more information to the tomcat/temp/gzserver.log file during the login process. This will help in fixing your configuration.
 
If you are having difficulty logging in to your LDAP-configured Globalyzer Server (login is failing, for example), configure the Globalyzer Server to write more information to the tomcat/temp/gzserver.log file during the login process. This will help in fixing your configuration.
   
To do this, place the logback-debug.groovy file (delivered in the Globalyzer Server zip file) to a location on your server. Then add -Dlogging.config to your JAVA_OPTS in your enterprise.sh/bat script to use this file.
+
To do this, place the logback-debug.groovy file (delivered in the Globalyzer Server zip file) to a location on your server. Then add <b>-Dlogging.config</b> to your JAVA_OPTS in your enterprise.sh/bat script to use this file.
   
For example, the modified enteprise.bat would look like this:
+
For example, the modified enterprise.bat would look like this:
   
set "JAVA_OPTS=-Xms256m -Xmx1600m -Dstringchararrayaccessor.disabled=true -Dlogging.config=C:\path\to\logback-debug.groovy"
+
<code>set "JAVA_OPTS=-Xms256m -Xmx1600m -Dstringchararrayaccessor.disabled=true -Dlogging.config=C:\path\to\logback-debug.groovy"</code>
   
 
Then stop and start your Globalyzer Server to incorporate the changes. You should now see more information written to the gzserver.log file.
 
Then stop and start your Globalyzer Server to incorporate the changes. You should now see more information written to the gzserver.log file.
   
  +
Note, if you are running Tomcat as a service rather than starting/stopping using the enterprise script, then update your JAVA_OPTS environment variable on the Server machine and then restart the Tomcat service.
   
 
== How Does LDAP Work on Globalyzer Login? ==
 
== How Does LDAP Work on Globalyzer Login? ==
When logging in to the Globalyzer Server or Client, the user will enter in their LDAP username and password. Globalyzer logs in to the LDAP server using the configured managerDN and managerPassword. A search is performed to authenticate the LDAP user as entered on the login screen. The search for this user will begin at the configured ldap.search.base and use the configured ldap.search.filter. If the user is not found, or the password is incorrect, the login will fail.
+
When logging in to the Globalyzer Server or Client, the user will enter in their LDAP username and password. Globalyzer logs in to the LDAP server using the configured <code>managerDN</code> and <code>managerPassword</code>. A search is performed to authenticate the LDAP user as entered on the login screen. The search for this user will begin at the configured <code>ldap.search.base</code> and use the configured <code>ldap.search.filter</code>. If the user is not found, or the password is incorrect, the login will fail.
   
If the user is a valid LDAP user, then a search for the groups the user belongs to is performed. This group search begins at the configured groupSearchBase. Groups are identified in LDAP by the configured groupRoleAttribute. It uses the configured groupSearchFilter to determine if the found user is a member of the group. Users may be members of several groups.
+
If the user is a valid LDAP user, then a search for the groups the user belongs to is performed. This group search begins at the configured <code>groupSearchBase</code>. Groups are identified in LDAP by the configured <code>groupRoleAttribute</code>. It uses the configured <code>groupSearchFilter</code> to determine if the found user is a member of the group. Users may be members of several groups across LDAP, but only one Globalyzer group.
   
 
If logging into the server, and the user is authenticated (user is a valid LDAP user) but the user does not belong to one of the three Globalyzer groups (admin, manager, or member), the user will be logged in, but won't be able to perform any actions, since not authorized to do so.
 
If logging into the server, and the user is authenticated (user is a valid LDAP user) but the user does not belong to one of the three Globalyzer groups (admin, manager, or member), the user will be logged in, but won't be able to perform any actions, since not authorized to do so.
Line 301: Line 202:
   
 
On subsequent logins, if the user is authenticated (user is a valid LDAP user) and authorized (user belongs to one of the three Globalyzer groups), the existing server account is then updated with the latest information in LDAP, except for the level of access. If the user was authorized to be a Globalyzer Manager when the account was created, the user will always be a Globalyzer Manager. Switching the user to a different access level requires that the Globalyzer account be deleted (by a Globalyzer Manager or Member), and then on login, the Globalyzer account will be recreated at the current access level as configured in LDAP.
 
On subsequent logins, if the user is authenticated (user is a valid LDAP user) and authorized (user belongs to one of the three Globalyzer groups), the existing server account is then updated with the latest information in LDAP, except for the level of access. If the user was authorized to be a Globalyzer Manager when the account was created, the user will always be a Globalyzer Manager. Switching the user to a different access level requires that the Globalyzer account be deleted (by a Globalyzer Manager or Member), and then on login, the Globalyzer account will be recreated at the current access level as configured in LDAP.
 
   
 
== What Differences Will I see Using LDAP? ==
 
== What Differences Will I see Using LDAP? ==
Line 314: Line 214:
 
* When an LDAP user initially logs in to the server, a server account will be created if they were authenticated by LDAP and authorized (by belonging to one of the three Globalyzer groups)
 
* When an LDAP user initially logs in to the server, a server account will be created if they were authenticated by LDAP and authorized (by belonging to one of the three Globalyzer groups)
 
* If user is NOT authenticated by LDAP, login will fail
 
* If user is NOT authenticated by LDAP, login will fail
* If user is authenticated by LDAP, but not authorized (via group membership),
+
* If user is authenticated by LDAP, but not authorized (via group membership), a screen appears saying they are not authorized to access Globalyzer
a screen appears saying they are not authorized to access Globalyzer
 
 
* On subsequent logins, the user is first authenticated (account is validated against LDAP) and authorized (if Globalyzer group member). Their existing server account is then updated with the latest information in LDAP, EXCEPT for their level of access. If they were authorized to be a Globalyzer Manager when their account was created, they will always be a Globalyzer Manager. An existing Manager account will not be switched to a Member account or an Admin account, for example. The Manager account can be deleted from the Globalyzer server (by another Manager or Admin), and then on login, the account will be recreated at the current access level as configured in LDAP.
 
* On subsequent logins, the user is first authenticated (account is validated against LDAP) and authorized (if Globalyzer group member). Their existing server account is then updated with the latest information in LDAP, EXCEPT for their level of access. If they were authorized to be a Globalyzer Manager when their account was created, they will always be a Globalyzer Manager. An existing Manager account will not be switched to a Member account or an Admin account, for example. The Manager account can be deleted from the Globalyzer server (by another Manager or Admin), and then on login, the account will be recreated at the current access level as configured in LDAP.
   

Revision as of 21:58, 7 August 2019

Overview

Many large companies use LDAP to manage user information. As new users are hired, they are entered into the company's LDAP system. When users leave the company, they are removed from the company's LDAP system. LDAP is also used to give user's authority to access certain applications within the company.

Globalyzer can be configured to use your company’s LDAP system. When users log in to Globalyzer, they will enter their LDAP username and LDAP password. If they are authenticated (exist in the LDAP system) and are authorized to use Globalyzer (belong to a Globalyzer group as configured in LDAP), then a Globalyzer account is created with information gathered from LDAP.

If the user's phone number, title, last name, etc., is modified in LDAP, then the next time the user logs in to Globalyzer, their Globalyzer account information will be updated with the latest information from LDAP. If the user leaves the company and is removed from LDAP, the user can no longer access their Globalyzer account. All Globalyzer user access and information is managed by LDAP.

How to Configure LDAP

LDAP configuration involves setting the environment variable GZSERVER_LDAP_MODE to true, and configuring GzserverConfig.groovy.

Setting GZSERVER_LDAP_MODE

If your server runs on Linux, in the enterprise.sh file, set GZSERVER_LDAP_MODE to true.

#!/bin/sh

export GZSERVER_ENTERPRISE_MODE=true
export GZSERVER_LDAP_MODE=true
export CATALINA_HOME=/usr/local/tomcat
...

If your server runs on Windows, and you are using the enterprise.bat file to start/stop your server, set GZSERVER_LDAP_MODE to true:

@echo off

if "%OS%" == "Windows_NT" setlocal

set "GZSERVER_ENTERPRISE_MODE=true"
set "GZSERVER_LDAP_MODE=true"
set "CATALINA_HOME=C:\apache-tomcat-8.5.23"
...

If your server runs on Windows and you are running Tomcat as a service, create a new GZSERVER_LDAP_MODE environment variable for the machine, and set it to true.

Configuring GzserverConfig.groovy

The bulk of the LDAP configuration takes place in the GzserverConfig.groovy file. There is a section in the file dedicated to LDAP configuration.

Your company's LDAP stores information for each LDAP user. Map the field names defined in LDAP so that Globalyzer knows how to access the user's first name, last name, etc.

// ************************    START OF LDAP CONFIGURATION     *********************
// **
// ** Uncomment the following 7 gzserver lines and map them to fields in your LDAP
// ** If your LDAP does not have the information per user, leave it as empty string
// ** NOTE: It is required that LDAP contains an email field for each LDAP user
// **
//gzserver.ldap.ctx.firstName = ""
//gzserver.ldap.ctx.lastName = ""
//gzserver.ldap.ctx.email = "mail"
//gzserver.ldap.ctx.phone = ""
//gzserver.ldap.ctx.title = ""
//gzserver.ldap.ctx.country = ""
//gzserver.ldap.ctx.timeZone = ""


For example, if the field name for phone is "telephone" in your LDAP, then change the line in GzserverConfig.groovy to this:

gzserver.ldap.ctx.phone = "telephone"

If your LDAP does not store a telephone number for LDAP users, then leave the line like this:

gzserver.ldap.ctx.phone = ""

The only required field is email. Your company's LDAP must store email information for each user, since the email field is required to create a Globalyzer account.

In addition to user information, your company's LDAP defines groups and group membership. Group membership is used to determine the applications users have access to, as well as the level of access. For Globalyzer, three new groups should be added to your company's LDAP by your company's LDAP administrator:

  • a Globalyzer admin group
  • a Globalyzer manager group
  • a Globalyzer member group

Users who have access to Globalyzer will be members of one of these three groups. Your LDAP administrator can choose the group names; below is where you map the groups names defined in LDAP.

// **
// ** Uncomment the following 3 gzserver lines and map them to groups defined in your LDAP
// ** The LDAP groups represent globalyzer admin, manager, and member access:
// **
//gzserver.ldap.admin.groupName = "GlobalyzerAdmin"
//gzserver.ldap.manager.groupName = "GlobalyzerManager"
//gzserver.ldap.member.groupName = "GlobalyzerMember"

Configure the message that displays if the user logging in is NOT a member of one of the Globalyzer groups defined above.

// **
// ** Uncomment the following gzserver line and configure
// ** This text will be displayed to users who are not members of a 
// ** Globalyzer group
// **
//gzserver.ldap.noaccess = "You are not authorized to access Globalyzer."

Next, configure the LDAP server address and then uncomment the providerNames line, as it is already configured correctly.

// **
// ** Uncomment the following grails line and set to the address of the LDAP server 
// **
//grails.plugin.springsecurity.ldap.context.server = 'ldap://localhost:389'

// **
// ** Uncomment the following grails line; it is already configured properly for LDAP
// **
//grails.plugin.springsecurity.providerNames = ['ldapAuthProvider','anonymousAuthenticationProvider']

To authenticate LDAP users, Globalyzer connects to your company's LDAP server, logging in via the information provided below. This can be a read only LDAP account and password.

// **
// ** Uncomment the following two grails lines and set to the DN to authenticate with
// ** Globalyzer; will connect the LDAP server and log in via this account
// ** See the next section for information on how to encrypt the managerPassword
// **
//grails.plugin.springsecurity.ldap.context.managerDn = 'cn=read-only-admin,dc=example,dc=com'
//grails.plugin.springsecurity.ldap.context.managerPassword = 'password'

The rest of the LDAP section of the GzserverConfig.groovy file needs to be configured to perform searches for users and groups.

// **
// ** Uncomment the following grails line and configure - 
// ** The base DN from which the search for group membership should be performed
// **
//grails.plugin.springsecurity.ldap.authorities.groupSearchBase = 'ou=Groups,dc=example,dc=com'

// **
// ** Uncomment the following grails line and configure -
// ** The ID of the attribute which contains the role name for a group
// **
//grails.plugin.springsecurity.ldap.authorities.groupRoleAttribute = 'cn'

// **
// ** Uncomment the following grails line and configure -
// ** The pattern to be used for the user search. {0} is the user's DN
// **
//grails.plugin.springsecurity.ldap.authorities.groupSearchFilter = 'member={0}' 

// **
// ** Uncomment the following grails line and configure -
// ** Context name to search in
// **
//grails.plugin.springsecurity.ldap.search.base = 'dc=example,dc=com'

// **
// ** Uncomment the following grails line and configure -
// ** The filter expression used in the user search
// **
//grails.plugin.springsecurity.ldap.search.filter = '(uid={0})'
// ************************    END OF LDAP CONFIGURATION    *************************

Encrypting the LDAP Password

To support LDAP logins, the Globalyzer Server requires an LDAP account that can connect to your LDAP server and perform reads. As of 6.3, this password may be encrypted, rather that appear in plain text. To encrypt the password, you must use the globalyzer-encrypt-password.jar that is available in the Globalyzer-Server.zip file (starting with the 6.3 release).

Run the jar to generate an encrypted password:

$ java -jar globalyzer-encrypt-password.jar -in "my plain password"
Encrypted Password: CLCjzYV02uZaWDTDkcvK65BndTfUlH5leL00vsgWkmY=

Then place the generated password in the GzserverConfig.groovy file within ENC():

grails.plugin.springsecurity.ldap.context.managerPassword = 'ENC(CLCjzYV02uZaWDTDkcvK65BndTfUlH5leL00vsgWkmY=)'

Plain passwords are still supported and are configured like this:

grails.plugin.springsecurity.ldap.context.managerPassword = 'my plain password'

Example LDAP Configuration

As an example, let's assume that your LDAP has the following directory structure:

dc=example, dc=com
    ou=Groups
         cn=GlobalyzerAdmin
         cn=GlobalyzerManager
         cn=GlobalyzerMember
         cn=SomeOtherGroup
    ou=Users
         uid=mheilner
         uid=lcameron
         uid=olibouban

The configuration for this is shown below:

grails.plugin.springsecurity.ldap.authorities.groupSearchBase = 'ou=Groups,dc=example,dc=com'
grails.plugin.springsecurity.ldap.authorities.groupRoleAttribute = 'cn'
grails.plugin.springsecurity.ldap.authorities.groupSearchFilter = 'member={0}' 
grails.plugin.springsecurity.ldap.search.base = 'dc=example,dc=com'
grails.plugin.springsecurity.ldap.search.filter = '(uid={0})'

Trouble-Shooting your LDAP Configuration

If you are having difficulty logging in to your LDAP-configured Globalyzer Server (login is failing, for example), configure the Globalyzer Server to write more information to the tomcat/temp/gzserver.log file during the login process. This will help in fixing your configuration.

To do this, place the logback-debug.groovy file (delivered in the Globalyzer Server zip file) to a location on your server. Then add -Dlogging.config to your JAVA_OPTS in your enterprise.sh/bat script to use this file.

For example, the modified enterprise.bat would look like this:

set "JAVA_OPTS=-Xms256m -Xmx1600m -Dstringchararrayaccessor.disabled=true -Dlogging.config=C:\path\to\logback-debug.groovy"

Then stop and start your Globalyzer Server to incorporate the changes. You should now see more information written to the gzserver.log file.

Note, if you are running Tomcat as a service rather than starting/stopping using the enterprise script, then update your JAVA_OPTS environment variable on the Server machine and then restart the Tomcat service.

How Does LDAP Work on Globalyzer Login?

When logging in to the Globalyzer Server or Client, the user will enter in their LDAP username and password. Globalyzer logs in to the LDAP server using the configured managerDN and managerPassword. A search is performed to authenticate the LDAP user as entered on the login screen. The search for this user will begin at the configured ldap.search.base and use the configured ldap.search.filter. If the user is not found, or the password is incorrect, the login will fail.

If the user is a valid LDAP user, then a search for the groups the user belongs to is performed. This group search begins at the configured groupSearchBase. Groups are identified in LDAP by the configured groupRoleAttribute. It uses the configured groupSearchFilter to determine if the found user is a member of the group. Users may be members of several groups across LDAP, but only one Globalyzer group.

If logging into the server, and the user is authenticated (user is a valid LDAP user) but the user does not belong to one of the three Globalyzer groups (admin, manager, or member), the user will be logged in, but won't be able to perform any actions, since not authorized to do so.

If logging into the client, and the user is authenticated (user is a valid LDAP user) but the user does not belong to one of the three Globalyzer groups, login will fail.

On initial login, if the user is authenticated (user is valid LDAP user) and authorized (user belongs to one of the three Globalyzer groups), a Globalyzer account is created at the appropriate access level.

On subsequent logins, if the user is authenticated (user is a valid LDAP user) and authorized (user belongs to one of the three Globalyzer groups), the existing server account is then updated with the latest information in LDAP, except for the level of access. If the user was authorized to be a Globalyzer Manager when the account was created, the user will always be a Globalyzer Manager. Switching the user to a different access level requires that the Globalyzer account be deleted (by a Globalyzer Manager or Member), and then on login, the Globalyzer account will be recreated at the current access level as configured in LDAP.

What Differences Will I see Using LDAP?

When an LDAP server has been successfully configured and launched, you will see these changes.

Server changes:

  • On server login screen, LDAP User and LDAP Password is displayed, rather than Email and Password
  • On server login screen, Forgot Password link is removed
  • Admin users can no longer create other Admins, Managers, or Members
  • Manager users can no longer create other Managers or Members
  • No users can edit their profile
  • When an LDAP user initially logs in to the server, a server account will be created if they were authenticated by LDAP and authorized (by belonging to one of the three Globalyzer groups)
  • If user is NOT authenticated by LDAP, login will fail
  • If user is authenticated by LDAP, but not authorized (via group membership), a screen appears saying they are not authorized to access Globalyzer
  • On subsequent logins, the user is first authenticated (account is validated against LDAP) and authorized (if Globalyzer group member). Their existing server account is then updated with the latest information in LDAP, EXCEPT for their level of access. If they were authorized to be a Globalyzer Manager when their account was created, they will always be a Globalyzer Manager. An existing Manager account will not be switched to a Member account or an Admin account, for example. The Manager account can be deleted from the Globalyzer server (by another Manager or Admin), and then on login, the account will be recreated at the current access level as configured in LDAP.

Client Workbench changes:

  • Forgot Password link still displays (since clients can connect to various servers) but if they are connected to an LDAP-configured server, a message displays saying that the password cannot be retrieved from an LDAP-configured server
  • When LDAP users initially log in to the client (haven't logged in to server yet), a server account will be created for them if they are authenticated by LDAP and authorized (by belonging to one of the three Globalyzer groups).
  • If user is NOT authenticated by LDAP, login will fail.
  • If user is authenticated by LDAP, but not authorized (via group membership), login will fail.