Users and Groups

Describes differences between internal and external users and groups, and the PiCLI commands used to manage users and groups.

Overview

In order to access Perforce IPLM a user must have a Perforce IPLM user account. Perforce IPLM groups are collections of users and/or other groups (subgroups). Permissions can be applied to either users or groups, with applying them to groups being the preferred method, for simplification of user management.

Perforce IPLM users and groups can be managed in two different ways, either as internal users and groups defined directly in Perforce IPLM, or as external users and groups that are synched from an external source such as LDAP or Active Directory (AD). Administrator status is required to manage users and groups.

Additional information on the requirements to access Perforce IPLM are available in Accessing Perforce IPLM in the User Guide. 

Internally vs. Externally Defined Users and Groups

Internal users and groups are configured using the 'pi user' and 'pi group' commands, detailed below. External users and groups are pulled into Perforce IPLM from an external source with the 'pi user sync' command, also shown below.

The 'pi user sync' command calls a synchronization script that is defined in the 'piserver.yml' PiServer configuration file, see: piserver.yml Configuration File for details. The script accesses the external User/Group data source, pulls out the necessary information, and formats it in a JSON string that Perforce IPLM imports. Authentication of external users is similarly done via an external authentication script defined in the same file, 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.

Internal and External users and groups function for the most part identically, but there are a few differences. The underlying principle is that any user or group configuration information provided by the external source can't be modified internally by Perforce IPLM, this keeps the external data source is the only source of truth for that information. This means that external users can be added to internal groups (which changes the internal group but not the external user) and similarly external groups can be added as sub-groups to internal groups. The opposite configuration is disallowed, no groups or users can be added to externally defined groups by Perforce IPLM, as this would change the external group.

Configuration fields of users and groups that are externally sourced also cannot be modified in Perforce IPLM, to change them modify the external source and resync them into Perforce IPLM.

User/Group Configuration Fields

The following fields are used to configure users in Perforce IPLM.

The following fields are used to configure groups in Perforce IPLM.

Users and groups are managed internally in Perforce IPLM via a UUID, so it is possible to change their names and other fields, limited by the field editing restrictions placed on external users and groups.

User Authentication

Internal users are authenticated with a password stored in Perforce IPLM, external users are authenticated against the LDAP or similar server from which they were populated. Internal users (or an admin) can use the 'pi passwd' command to change their password, both user types use the 'pi login' command to log in. See Accessing Perforce IPLM in the User Guide for details on logging in. The Security page has information on how to configure user login timeout, the setting is contained in the piserver.yml Configuration File. 

Administrator (Admin) Users and Group

Perforce IPLM maintains a special internal 'admin' group that can only be defined internally, and can't be removed or overwritten by any external source. Users added to the 'admin' group become administrators, and in addition to the capabilities of non-administrator users, have the ability to add new Libraries, edit and manage users, manage permissions, change other user's passwords, and edit all IPs and workspaces. Administrator status can be removed by removing the user from the 'admin' group. The membership of the admin group can be changed, but the name and description of the admin group cannot be changed.

In addition to the generated user accounts that may be added or removed from the special admin group, Perforce IPLM also defines a special internal-only 'admin' user account that is permanently a member of the 'admin' group. The admin user's email and password can be changed, other fields are fixed.

Enabling and Disabling Users and Groups

Internal users can be explicitly disabled and enabled using the 'pi user/group disable' and 'pi user/group enable' commands (see below). External users and groups are disabled if having been synced into Perforce IPLM from an external source (via the pi user sync command) a subsequent sync does not include their username/groupname.

Disabled users and groups have the following characteristics:

1. A disabled user/group retains the same name as when they were active.
2. No new internal users or group can be created with an identical user/groupname to any disabled user or group
3. Disabled users cannot log in
4. No user can gain any access permission from a disabled group (disabled group permissions have no effect).
5. A user/group retains all group memberships and permissions it had when enabled upon being disabled
6. An administrator can modify the fields of a disabled INTERNAL user/group while it is disabled, including user/groupname, permissions, and user/group membership
7. An administrator can edit all the non-externally defined fields of a disabled EXTERNAL user/group while the user/group is disabled, including permissions and internal group memberships
8. The event subscriptions of a disabled user/group are not processed

Obliterating Users and Groups

Disabled users and groups (either internal or external) can be obliterated, which removes the user account or group from the platform. Obliterate is an admin only capability. In order to obliterate a user or group it must be currently disabled, and users can't be the creator of any current workspaces. Obliteration attempts will fail if any of these requirements is not met. Both Internal and external users/gropus can be obliterated. The user or group permissions, group membership, and subscriptions will be removed when they are obliterated.

User/Group Name Restrictions

colon ':'

The "all" Group

Perforce IPLM maintains a builtin 'all' group that contains all the users defined in the platform. Members cannot be added or removed from the all group. Permissions granted to the all group will apply to all users defined in the platform.

Converting Internal Users and Groups to External Users and Groups

Internally defined users and groups can be converted to external Users and Groups (but not vice versa). Details of these transformations is shown below.

Allowed Transformations

• Internal users/groups may be changed to external users/groups, external users/groups cannot be changed to internal users/groups 
• The internal 'admin' group and its membership cannot be modified in any way by an external source sync 

User Transformation 

• Internal users are converted to external users based on an identical username being defined in the user sync
• Externally defined User properties overwrite the corresponding internal user properties
• Existing properties of the internal user will be retained if not defined by the external source
• The external user's 'source' will be set to 'external'

Command Line - Users

Internal and External users can be administered using the 'pi user' commands. Some commands apply to only internal users, others apply to external users.

> pi user -h
Usage: pi user [-h] SUBCOMMAND ...

Description: Commands related to Users. These subcommands are used to add,
edit, delete and list information about Users.

Optional arguments:
  -h, --help  Show this help message and exit

Available sub-commands:
  SUBCOMMAND
    add       Create a new User.
    disable   Disable an existing User.
    edit      Edit an existing User.
    enable    Enable a disabled User.
    list (ls)
              List all matching Users.
    obliterate
              Permanently delete an existing disabled User.
    sync      Sync an externally derived Users/Groups definition.

Adding an Internal User (Internal Only)

The 'pi user add' command is used to add a new internal user. 

> pi user add -h
Usage: pi user add [-h] [--template TEMPLATE | identifier]

Description: Create a new User. The command puts the User specification into a
temporary file and invokes the editor specified by the EDITOR environment
variable. Saving the file adds the User.

Positional arguments:
  identifier            The name of the User being created.

Optional arguments:
  --template TEMPLATE, -t TEMPLATE
                        Use the specified template to add the User. The
                        template is an ASCII file that defines the User. This
                        can be used to add Users with a script and avoid the
                        interactive editor. To read the template from STDIN,
                        set TEMPLATE='-'.
  -h, --help            Show this help message and exit

Examples:
# Invoke the editor to create User john.
  pi user add john

# Create User using the john.info template.
  pi user add -t john.info

# Create User using redirected STDOUT from script new_user.py as template.
  new_user.py | pi user add --template -

The 'pi user add' command supports a '–template' option which will take a template file as an argument, for non-interactive or scripted user generation.

Editing an Existing User  (Internal Only)

Existing users can be modified via the 'pi user edit' command. 

> pi user edit -h
Usage: pi user edit [-h] [--template TEMPLATE] identifier

Description: Edit an existing User. The command puts the User specification
into a temporary file and invokes the editor specified by the EDITOR
environment variable. Saving the file edits the User.

Positional arguments:
  identifier            The name of the User being edited.

Optional arguments:
  --template TEMPLATE, -t TEMPLATE
                        Use the specified template to edit the User. The
                        template is an ASCII file that defines the User. This
                        can be used to edit Users with a script and avoid the
                        interactive editor. To read the template from STDIN,
                        set TEMPLATE='-'.
  -h, --help            Show this help message and exit

Examples:
# Invoke the editor to modify User john.
  pi user edit john

# Modify User john using the john.info template.
  pi user edit -t john.info john

# Modify User john using redirected STDOUT from script as template.
  edit_user.py | pi user edit -t - john

This command will bring up the user template for editing.

Listing Users

The 'pi user list' command is used to list both internal and external users in Perforce IPLM.

> pi user list -h
Usage: pi user list [-h] [--format {csv,json,long,table,template} | --verbose]
                    [--model MODEL] [--disabled]
                    [identifier [identifier ...]]

Description: List all matching Users. A variety of format and filtering
options are supported.

Positional arguments:
  identifier            Filter Users by name.

Optional arguments:
  --disabled            Only list disabled Users.
  --format {csv,json,long,table,template}
                        Return the results using the specified data structure.
                        The template format produces files that can be used by
                        the pi add|edit commands with the --template option.
  --model MODEL         Use the specified report model (table report only).
  --verbose, -v         Alias for --format long.
  -h, --help            Show this help message and exit

Configuring the Output Format

Perforce IPLM can display the list output in a number of different formats

Listing Only Disabled Users

To list only disabled users use the --disabled option.

Disabling Users (Internal Only)

Internal Perforce IPLM users can be disabled with the 'pi user disable' command. External users are disabled if they don't appear in the latest 'pi user sync' data, and are not affected by this command.

> pi user disable -h
Usage: pi user disable [-h] identifier

Description: Disable an existing User. This command will mark a User as
inactive

Positional arguments:
  identifier  The name of the User to disable.

Optional arguments:
  -h, --help  Show this help message and exit

Enabling Users (Internal Only)

Previously disabled internal Perforce IPLM users can be enabled with the 'pi user enable' command. External users are enabled if they appear in the latest 'pi user sync' data, and are not affected by this command.

> pi user enable -h
Usage: pi user enable [-h] identifier

Description: Enable a disabled User. This command will mark a User as active
again. The disabled identifier must be provided. Thisidentifier can be
obtained by calling 'pi user list --disabled'

Positional arguments:
  identifier  The name of the User to enable.

Optional arguments:
  -h, --help  Show this help message and exit

Obliterating Users

Obliterating a user permanently removes the user from the database. Users must already be disabled before they can be obliterated.

> pi user obliterate -h
Usage: pi user obliterate [-h] [--yes] identifier

Description: Permanently delete an existing disabled User. This command will
remove a disabled User from the system, it can not be recovered. By default
obliterate will run in dry-run mode only.

Positional arguments:
  identifier  The name of the User to obliterate.

Optional arguments:
  --yes, -y   Confirm that we want to run the command.
  -h, --help  Show this help message and exit

Syncing Users (and Groups)

The 'pi user sync' command imports user and group definitions from an external source into Perforce IPLM. See the Configuring External Users and Groups (LDAP) page for more details.

> pi user sync -h
Usage: pi user sync [-h] [--verbose]

Description: Sync an externally derived Users/Groups definition. Note that the
location of the script that generates Users/Groups definition is defined in
the piserver configuration. pi user sync will read that directly from STDOUT.

Optional arguments:
  --verbose, -v  Report full output of sync, by default only changes are
                 reported.
  -h, --help     Show this help message and exit

Command Line - Groups

Internal and External groups can be managed by administrator users using the 'pi group' commands. Some commands only apply to internal groups, others apply to external groups.

> pi group -h
Usage: pi group [-h] SUBCOMMAND ...

Description: Commands related to Groups. These subcommands are used to add,
edit, delete and list information about Groups.

Optional arguments:
  -h, --help  Show this help message and exit

Available sub-commands:
  SUBCOMMAND
    add       Create a new Group.
    disable   Disable an existing Group.
    edit      Edit an existing Group.
    enable    Enable a disabled Group.
    list (ls)
              List all matching Groups.
    obliterate
              Permanently delete an existing disabled Group.

Adding Groups (Internal Only)

Internal groups can be added by administrators with the 'pi group add' command:

> pi group add -h
Usage: pi group add [-h] [--template TEMPLATE | identifier]

Description: Create a new Group. The command puts the Group specification into
a temporary file and invokes the editor specified by the EDITOR environment
variable. Saving the file adds the Group.

Positional arguments:
  identifier            The name of the Group being created.

Optional arguments:
  --template TEMPLATE, -t TEMPLATE
                        Use the specified template to add the Group. The
                        template is an ASCII file that defines the Group. This
                        can be used to add Groups with a script and avoid the
                        interactive editor. To read the template from STDIN,
                        set TEMPLATE='-'.
  -h, --help            Show this help message and exit

Examples:
# Invoke the editor to create Group staff.
  pi group add staff

# Create Group using the staff.info template.
  pi group add -t staff.info

# Create Group using redirected STDOUT from script new_group.py as template.
  new_group.py | pi group add --template -

The command will bring up a template that can be filled out to define the group. The template defines the name & description of the group, as well as defining any parent groups of the group (higher level groups this group belongs to). User membership in a group is defined in the user template, as user names have to be space separated; or one user per line (newlines require a leading space).

[GROUP]
# Name is required
name = designers

# Description is optional
description =

# Sub groups
sub_groups =
 
# Members of the group
users = adam 
        andy 
        bob 

Editing Groups (Internal Only)

Groups may be edited by administrators with the 'pi group edit' command. 

> pi group edit -h
Usage: pi group edit [-h] [--template TEMPLATE] identifier

Description: Edit an existing Group. The command puts the Group specification
into a temporary file and invokes the editor specified by the EDITOR
environment variable. Saving the file edits the Group.

Positional arguments:
  identifier            The name of the Group being edited.

Optional arguments:
  --template TEMPLATE, -t TEMPLATE
                        Use the specified template to edit the Group. The
                        template is an ASCII file that defines the Group. This
                        can be used to edit Groups with a script and avoid the
                        interactive editor. To read the template from STDIN,
                        set TEMPLATE='-'.
  -h, --help            Show this help message and exit

Examples:
# Invoke the editor to modify Group staff.
  pi group edit staff

# Modify Group staff using the staff.info template.
  pi group edit -t staff.info staff

# Modify Group staff using redirected STDOUT from script as template.
  edit_group.py | pi group edit -t - staff

Listing Groups

The 'pi group list' command is used to list both internal and external groups in Perforce IPLM.

> pi group list -h
Usage: pi group list [-h]
                     [--format {csv,json,long,table,template} | --verbose]
                     [--model MODEL] [--disabled]
                     [identifier [identifier ...]]

Description: List all matching Groups. A variety of format and filtering
options are supported.

Positional arguments:
  identifier            Filter Groups by name.

Optional arguments:
  --disabled            Only list disabled Groups.
  --format {csv,json,long,table,template}
                        Return the results using the specified data structure.
                        The template format produces files that can be used by
                        the pi add|edit commands with the --template option.
  --model MODEL         Use the specified report model (table report only).
  --verbose, -v         Alias for --format long.
  -h, --help            Show this help message and exit

Configuring the Output Format

Perforce IPLM can display the list output in a number of different formats

Listing only Disabled Groups

To list only disabled groups use the --disabled option.

Disabling Groups (Internal Only)

Internal Perforce IPLM groups can be disabled with the 'pi group disable' command. External groups are disabled if they don't appear in the latest 'pi user sync' data, and are not affected by this command.

> pi group disable -h
Usage: pi group disable [-h] identifier

Description: Disable an existing Group. This command will mark a Group as
inactive

Positional arguments:
  identifier  The name of the Group to disable.

Optional arguments:
  -h, --help  Show this help message and exit

Enabling Groups (Internal Only)

Previously disabled internal Perforce IPLM groups can be enabled with the 'pi group enable' command. External groups are enabled if they appear in the latest 'pi user sync' data, and are not affected by this command.

> pi group enable -h
Usage: pi group enable [-h] identifier

Description: Enable a disabled Group. This command will mark a Group as active
again. The disabled identifier must be provided. Thisidentifier can be
obtained by calling 'pi group list --disabled'

Positional arguments:
  identifier  The name of the Group to enable.

Optional arguments:
  -h, --help  Show this help message and exit

Obliterating Groups

Obliterating a group permanently removes the group from the database. Groups must already be disabled before they can be obliterated.

> pi group obliterate -h
Usage: pi group obliterate [-h] [--yes] identifier

Description: Permanently delete an existing disabled Group. This command will
remove a disabled Group from the system, it can not be recovered.By default
obliterate will run in dry-run mode only.

Positional arguments:
  identifier  The name of the Group to obliterate.

Optional arguments:
  --yes, -y   Confirm that we want to run the command.
  -h, --help  Show this help message and exit