Configuring External Users and Groups (LDAP)
Describes Importing externally defined users and groups into Perforce IPLM. External Users and Groups are configured through a synchronization script and an authorization script. Details on these scripts and their return values is also provided.
External Users and Groups
Users and Groups configured the the 'pi user sync' command and the sync script configured in the piserver.yml file are classified as external in Perforce IPLM. These users are sourced from definitions in systems like LDAP or AD (Active Directory).
The import of external user and group data into Perforce IPLM is accomplished with an external synchronization script. This script retrieves user information from the external source (LDAP, Active Directory), and returns a JSON formatted string to Perforce IPLM. Authentication of external users is similarly done via an external authentication script which takes in a user name and password, checks them against the external source, and returns success or failure to Perforce IPLM. Details on the requirements for both scripts, as well as sample scripts, are shown below.
External user data can only be changed in the external source, it can't be modified in Perforce IPLM after the user sync command brings it in.
The best practice is usually to limit the number of externally sourced users to the number of users that actually need access to the Perforce IPLM data. This improves overall system security.
Synchronization Script details
External Users and groups are imported into Perforce IPLM via the 'pi user sync' command. Running the 'pi user sync' command causes a predefined user supplied script to run, access the external data source, and return the external user and group definition data required by Perforce IPLM. An example External Synchronization script can be found on the Example External User Sync Script page.
> pi user sync
The Synchronization script must take no inputs and returns a JSON string with the following format:
{
"users": [
{
"username": "john",
"fullname": "John Doe",
"email": "john@example.com" },
{
"username": "jane",
"fullname": "Jane Doe",
"email": "jane@example.com" },
{
"username": "ian",
"fullname": "Ian Smith",
"email": "ian@example.com" },
{
"username": "mary",
"fullname": "Mary Smith",
"email": "mary@example.com" },
{
"username": "fanny",
"fullname": "Fanny Smith",
"email": "fanny@example.com" },
{
"username": "may",
"fullname": "May Smith",
"email": "may@example.com" }
],
"groups": [
{
"groupname": "Blue",
"members": ["john", "jane"]
},
{
"groupname": "Green",
"members": ["ian", "mary"]
},
{
"groupname": "Colors",
"subgroups": ["Blue", "Green"],
"members": ["fanny", "may"]
}
]
}
If a user or group is present in the synchronization script it will be added to Perforce IPLM and identified as an external user (use the command 'pi user list v' to identify if a user is internal or externally defined). If in a subsequent run of 'pi user sync' the existing external user or group is not present, that user or group will be 'disabled' in Perforce IPLM. All user data, group membership, and permissions information will be retained, but the user or group will be unavailable for login/use. Later, if another 'pi user sync' command includes the user or group, the disabled user or group will again be enabled for login/use. Disabled users or groups can be listed via the 'pi user list --disabled' command' or the 'pi group list --disabled' command.
Scheduled syncing (running 'pi user sync') with the external user source can be set up with a cron job external to Perforce IPLM.
Authorization Script details
External users are authenticated by the external data source, rather than internally by Perforce IPLM. The authentication script is customer implemented, it receives the username and password, separated by a newline character "\n" as a string on stdin. The authentication script mush return exit code 0 for success and exit code other than 0 for failure. An example External Authorization script can be found on the Example External Authorization Script page.
External Script Configuration
The Synchronization and Authentication scripts are configured in the '/etc/mdx/piserver.yml' file (See the piserver.yml Configuration File page).
# --------------------------------------------------
# Security
# --------------------------------------------------
security:
# Time an access token can be idle before it is invalidated
# If set to 0, access tokens never expire
accessTokenExpirationTime: 0 seconds
externalSecurity:
# External authentication script
script: /path/to/authentication/SCRIPT
# External authentication script timeout
scriptTimeout: 10 seconds
externalSync:
# External synchronization script
script: /path/to/synchronization/SCRIPT
# External synchronization script timeout
scriptTimeout: 30 seconds
The path to each script, as well as the timeout for each is configured in the configuration file.
Note that the piserver must be restarted for changes to the authentication and synchronization scripts to take effect:
> service neo4j restart; systemctl restart piserver # for Debian
> service piserver restart # for Redhat, CentOS
Implementing the Scripts
The LDAP Bring Up Guide has detailed information on bringing the synchronization and authentication scripts online.
Internal to External User and Group Conversion
If the external sync script returns users or groups that have identical names to existing internal users or groups, those internal users or groups will be converted into external users or groups. Any internal group membership that doesn't conflict with the external source, and any permissions the internal user/group may have had will be carried over to the now external user or group. After the conversion the converted user or group will be managed as an external user or group, and external users will authenticate with the external authentication script. See the Users and Groups page for more information.