LDAP Bring Up Guide

Perforce IPLM LDAP Bring Up Guide. Steps through the stages of developing and testing a new LDAP integration script. The common issues and pitfalls are pointed out, and methods of testing the integration are provided.

UNIX Permissions

By far the most common issue in bringing up the Synch and Auth scripts in a new environment is getting the UNIX permissions correct.

The first thing to note is that when called by Perforce IPLM the Sync and Auth scripts are executed by the UNIX user account that is running piserver. For package based installs this will be the 'mdxadmin' user, for the Self Extracting .run based install it will be the user account used to start piserver.

Typically customers will begin by running the script from the command line as their own account, debug it, and get it into a working state. The next step should be to try to run the script as the user that is running piserver, either 'mdxadmin' or another custom user. When run by Perforce IPLM via 'pi user sync' in the case of the Sync script, or via 'pi login' in the case of the Auth script, some of the output is obscured as a security measure. For this reason it is usually necessary to run as the piserver user account outside of Perforce IPLM first, so that any warning or error messages can be fully seen.

Testing the Sync Script from the Command Line

The following command will execute the sync script from the command line as the 'mdxadmin' user. Please substitute the path/name of your script, and the user account you are using to run piserver.

Testing the Sync Script from the Command Line 
sudo su -s /bin/bash -c '/etc/mdx/sync.py' mdxadmin

Testing the Auth Script from the Command Line

The auth script is different from the sync script in that it requires input to fully execute. The script expects the username followed by a newline (\n), followed by the password, followed by EOF (CTRL-D). This input can be provided at the command line:

  1. <username> <return>
  2. <password> <CTL-D>

The Example Auth Script page also gives an example of (for testing purposes only) writing the username and password to a file to check that they were received properly by the script.

The following command will execute the auth script from the command line as the 'mdxadmin' user. Please substitute the path/name of your script, and the user account you are using to run piserver.

Testing the Auth Script from the Command Line 
sudo su -s /bin/bash -c '/etc/mdx/auth.py' mdxadmin

Sync Script Bring-up Steps

The following steps should be followed to bring up the Sync script. The sync script should be implemented first because when run from Perforce IPLM the auth script will only be used to authenticate external users, which are populated in the system by the sync script.

Test the Sync with the Simple Sync Test Script

  1.  Copy the Simple Sync Test Script to the path and filename you intend to use for your sync script. The standard location is in /etc/mdx but the script can be located anywhere.

  2. Run the script as the user running piserver:

    piserver Simple Sync Test Script Example 
    sudo su -s /bin/bash -c '/etc/mdx/sync.py' mdxadmin


    If there are no issues you will see JSON output from the script:

    JSON Output from Script 
    > sudo su -s /bin/bash -c '/etc/mdx/sync.py' mdxadmin 
{
	"users": [{
		"username": "john",
		"fullname": "John Doe",
		"email": "john@example.com"	}, {
		"username": "jane",
		"fullname": "Jane Doe",
		"email": "jane@example.com"	}],
	"groups": [{
		"groupname": "Blue",
		"members": ["john", "jane"]
	}]
}


    If you do see errors then work through resolving them. Typically these will be permissions related, make sure:
     - the user running piserver has at least read access all the way down the path to the sync script
     - the user running piserver has execute permissions to the sync script

  3. Edit the 'piserver.yml' file which will be in /etc/mdx for package based installs, or in the config directory under the Self-Extracting/.run install. Uncomment the 'script:' line in the 'externalSync:' section and change the value of the variable to the path and name of your script:

    Editing the piserver.yml File 
    externalSync:
    # External synchronization script
    script:  /etc/mdx/sync.py
    # External synchronization script timeout
    scriptTimeout: 30 seconds


    Restart piserver to have the piserver.yml settings take effect

  4. Log into Perforce IPLM as an admin user (note it may take up to 30 seconds for Perforce IPLM to be available after restart)

    Log Into Perforce IPLM as an Admin 
    > pi login admin Password: Successfully logged in as 'admin'

  5. Run a 'pi user sync' command to test the import into Perforce IPLM

    pi user sync Command 
    > pi user sync 
┌────────┬──────┬─────────┐ 
│ OBJECT │ NAME │ STATUS  │ 
╞════════╪══════╪═════════╡ 
│ Group  │ Blue │ Created │ 
│ User   │ john │ Created │ 
│ User.  │ jane │ Created │ 
└────────┴──────┴─────────┘ 
User Sync Successful.

  6. Once these steps are working all permission and Perforce IPLM configuration issues should be resolved. Now the contents of the sync script can be replaced with a more realistic version, perhaps based on the Example Sync Script.

Sync Script Troubleshooting

Sync Script Unicode Issues

Occasionally you might run into Unicode issues if your terminal is not setup to correctly. To resolve this you can set the shell variable "export MDX_PI_ASCII=TRUE"

For more information, see Unicode Issues.

Sync Script Buffer Issues

Large json strings can sometimes overflow the available buffer. This may result in an error such as:

Sync Script Buffer Issues 
"msg" : [ {
"name" : "UserNonzeroExitValueError",
"params" : 
{ "sync_exit_value" : "120" }} ]

This indicates that the script exited with error code 120, indicating (in python 3.6+) that some resource was exhausted. To overcome this issue the flow of data back to Perforce IPLM should be managed with a construct such as:

Construct Management 
print(json.dumps(data_dict, indent=2, sort_keys=True), flush=True)

Sync Script Timeout Issues

If the sync from the external system takes longer than allowed by Perforce IPLM, the sync script timeout can be increased. If this error occurs you will see something like the following error:

Sync Script Timeout Issues 
"msg" : [ {
"name" : "UserSyncTimeoutError",
"params" : 
{ "sync_script" : "/path/to/sync_script", "seconds_to_timeout" : "30" }} ]

Editing the /etc/mdx/piserver.yml file and and increasing the timeout limit (followed by a restart of piserver) should resolve the issue:

Editing the /etc/mdx/piserver.yml File 
externalSync:
    ...
    # External synchronization script timeout
    scriptTimeout: 60 seconds

Auth Script Bring-up Steps

The following steps should be followed to bring up the Auth script. The sync script should be implemented first because when run from Perforce IPLM the auth script will only be used to authenticate external users, which are populated in the system by the sync script.

Test the Auth with the Example Auth Script

  1.  Copy the Example Auth Script to the path and filename you intend to use for your auth script. The standard location is in /etc/mdx but the script can be located anywhere

  2. Edit the script to uncomment the test lines:

    Uncommenting the Test Lines 
    # test to verify user/password is loaded:
fl = open("/tmp/x", "w")
fl.write("username="+mylist[0]+'\n')
fl.write("password="+mylist[1]+'\n')
fl.close()
# test ends here

    These will cause the username and password passed to the script to be written to a file '/tmp/x' so that you can see the script is receiving these values correctly. Be sure to remove these lines from any production auth script.

  3. Run the script as the user running piserver:

    User Running PiServer 
    sudo su -s /bin/bash -c '/etc/mdx/auth.py' mdxadmin

    In order to run the auth script to completion it is necessary to provide it with input:

    Inputting the Auth Script 
    > sudo su -s /bin/bash -c '/etc/mdx/auth.py' mdxadmin
<username> <return><password> <CTL-D>

    Verify that the script runs without errors.

    If you do see errors then work through resolving them. Typically these will be permissions related, make sure:

    1. the user running piserver has at least read access all the way down the path to the auth script

    2. the user running piserver has execute permissions to the auth script

  4. Edit the 'piserver.yml' file which will be in /etc/mdx for package based installs, or in the config directory under the Self-Extracting/.run install
    Uncomment the 'script:' line in the 'externalSecurity:' section and change the value of the variable to the path and name of your script:

    Editing the piserver.yml File 
    externalSecurity:
    # External authentication script
    script: /etc/mdx/auth.py
  5. Restart piserver to have the piserver.yml settings take effect (note it may take up to 30 seconds for Perforce IPLM to be available after restart)

  6. Log into Perforce IPLM as an external user, i.e. one that you have previously added to they system via 'pi user sync'. They example auth script is set to always return a '0' which means that it doesn't matter what password you enter, login should be successful.

    Login to Perforce IPLM as a User 
    > pi login john
Password:
Successfully logged in as 'john'

    Check the '/tmp/x' file (if you uncommented the necessary test lines above) and check that the username and password you entered were captured by the script.

  7. Once these steps are working all permission and Perforce IPLM configuration issues should be resolved. Now the contents of the auth script can be replaced with a more realistic version, remember returning '0' indicates to Perforce IPLM that the username/password provided were correct, and anything else will indicate that the login should fail. Remember also to uncomment the test lines in any production version of the auth script.