P4 authentication

This section provides instructions on how to:

• Set up P4 Server authentication
• Set up P4 Server extensions
• Add users and groups in P4 Server

For more information, see:

• Frequently asked questions (FAQ) about P4 authentication
• Troubleshooting P4 authentication

Set up P4 Server authentication

The following procedure walks you through setting up your Perforce TeamHub instance with P4 Server authentication.

If you need information on configuring the Git Connector, see Installation and configuration in P4 Server Administration Documentation. Before you proceed, make sure you read the P4 authentication prerequisites.

An unlicensed P4 Server is limited to 10 repos. For more information, see P4 Server Licenses, which include a license for P4 Server and a separate license for Git Connector.

To set up P4 Server authentication:

1. In a web browser, go to the TeamHub admin portal: <TeamHub-instance-URL>/admin/login

2. Enter your user name and password and click Log in.

   The default values are admin/admin.

3. When prompted, enter your license information and click Apply.

4. In the Preferences view:

   1. Enter the hostname of your TeamHub instance.
   2. Under Authentication, select Helix.

   3. Specify the P4 Server details:

      The P4 Server must have at least one graph depot created in it, and the user below must have admin access to it.

      • P4PORT value: The host (name or IP address) and port for the P4 Server, in the following format: host:port

      • Fingerprint: If you connect to P4 Server using an SSL connection, add a fingerprint of the key received for SSL connections.

        If the fingerprint changes (or expires), you can add more fingerprints and delete outdated fingerprints. This is the equivalent of running the p4 trust command in the P4 command line. For details, see the P4 CLI Reference.

        Deleting a fingerprint configured for the port removes the trust established with P4 Server. As a result, everything in TeamHub stops working against the respective SSL port.

   4. Specify details for the P4 integration user:

      • Username: The name of an existing P4 Server user with super level privileges. This user must have unlimited ticket timeout.

        You cannot change a username (or email address) in P4 Server. Instead, you need to make this change on the P4 Server side and wait for the sync.

         

        The P4 integration user does not count against your TeamHub license plan seats but each user requires a background license. Request background licenses using the Background user request form on the Perforce website.

      • Ticket/Password: The password/ticket for the existing P4 Server user with super level privileges.

      The existing P4 Server user must be a member of a group that has an unlimited timeout set for the session and password.

      To configure a group for unlimited timeouts, add the user to the group, and obtain the unlimited ticket

      Use the following commands on the P4 Server:

      1. If you already have a group with unlimited timeout go to the next step. If you do not have a group with unlimited timeouts, create one with:

      p4 group no_timeout_users

      2. Add the username of the super user to the list of Users: in the group, and set the Timeout: and PasswordTimeout: values to unlimited if not already set.

      Group:            no_timeout_users
      Timeout:          unlimited
      PasswordTimeout:  unlimited
      Subgroups:
      Owners:
      Users:
              <super_user_username>
      

      For more information about managing P4 Server groups, see P4 group in the P4 CLI Reference.

      3. Obtain the unlimited ticket value valid for all hosts for the user with the following command:

      p4 -p <my-p4-core-server:1666> -u <super_user_username> login -a -p

      4. Use the unlimited ticket for Ticket/Password.

      • Charset: The character encoding set for P4 Server, such as utf8 or none

        To find the P4 Server charset, run: p4 -ztag info

        When connecting to a non-unicode server, the charset is none by default. If the charset is not shown, select none from the list. For more information on P4 Server charsets, run: p4 help charset

      • Account and group synchronization

   5. Click Test Helix Core connection and wait for the message: Successfully connected to P4.

   6. Specify Git Connector details:

      • Hostname: The host name of the server where the Git Connector is installed
      • SSH User: The OS user of the Git Connector (default: git)
      • P4 User: The P4 Server user of the Git Connector (default: gconn-user)

      For more information, see Configure the Git Connector in P4 Server Administration Documentation .

   7. Select SSH or HTTPS as the method used to connect to the Git Connector.

      We strongly suggest enabling both.

   8. Click Save preferences.

      A warning appears because the changes have not been applied to the TeamHub server yet. Perform the following step to finalize the configuration.

5. To apply server configuration changes to the TeamHub server, connect to the server via SSH and run the following command:

   sudo hth-ctl reconfigure

6. After successfully running the reconfigure command, reload the TeamHub admin portal.

   Failure to do so may result in normal web server interruption messages, such as the HTTP Error 503. The service is unavailable. error, because the services come back online.

Set up P4 Server extensions

P4 Server provides extensions to customize server operations or invoke additional processing for specific versioning operations. Perforce TeamHub extensions notify TeamHub about activity on the P4 Server. When extensions are configured, any pushes to graph depots or any submits to stream depots are visible as events in the TeamHub Activity view.

The hth extension is required to create events for stream and classic depots. It supports the following events:

• change-commit

The hth-graph extension is required to create events for graph depots. It supports the following events:

• branch create

• branch delete

• tag create

• tag delete

• graph-push-reference-complete

See Configuring P4 Server extensions for information about configuring the extensions.

Add users and groups in P4 Server

With P4 authentication, you add users and groups through the TeamHub user interface. TeamHub then provides the information to P4 Server, where it is stored.

To create users and groups, see the following topics in the Perforce TeamHub Documentation:

• Users
• Groups

To perform these tasks on the P4 Server side, see the following sections in the P4 Server Administration Documentation:

• Managing users for information on user types, adding new licensed users, and renaming users
• Authorizing access for information on the protections table and setting permission levels for users
• Granting access to groups of users for information on creating and editing groups

Mapping TeamHub roles to graph depot permissions

Whereas in P4 Server, you grant permissions to users or groups, in TeamHub, you assign roles. The following table indicates how each TeamHub role is mapped to specific graph depot permissions in P4 Server.

TeamHub Role	Graph Depot Permission
Admin	admin
Manager	write-all
Master	force-push delete-repo create-repo
Developer	delete-ref create-ref write-all
Guest	read

For more information on P4 Server permissions, see the p4 grant-permission command in the P4 CLI Reference.

For more information on TeamHub roles, see the Roles.

Enable synchronization of P4 users in Perforce TeamHub

To automatically give all P4 Server users access to TeamHub, select the check box. To do this, either:

• In the TeamHub admin UI, go to Preferences > Helix Core Server > Account and group synchronization.

• In the /var/opt/hth/shared/hth.json configuration file, change the setting.

When the Automatically sync P4 users in Helix TeamHub check box is selected:

• You cannot give non-P4 users access to Perforce TeamHub.

• You cannot create or delete a user manually.

• You cannot create or delete a group manually.

If you do not have enough TeamHub licenses for all your P4 Server users, or if you want to exclude users and groups from accessing Perforce TeamHub, see Including and excluding P4 Server users and groups.

Including and excluding P4 Server users and groups

You may want to include users or groups, or one or more users in a group, that exist in P4 Server in the TeamHub UI, or exclude them from being displayed in the TeamHub UI. This is possible by configuring the respective keys. To do this, either:

• In the TeamHub admin UI portal, go to Preferences > P4 Server > Account and group synchronization.

• In the /var/opt/hth/shared/hth.json configuration file, change the setting.

To learn more about these keys, see Section: helix.

When synchronizing users, TeamHub proceeds in the following order. TeamHub:

1. Includes direct users and bots
2. Adds users and bots from groups
3. Excludes users and bots from groups
4. Excludes direct users and bots

When synchronizing groups, TeamHub first includes groups and then extracts any groups that are marked as excluded in the configuration.

To include or exclude P4 Server users or groups:

1. In the Preferences view, under Account and group synchronization, enter the name of users or groups as needed.

   For example:

   To include the users called user1 and user2, enter the following in the Include users field: ^(user1|user2)$

   To include users from a group called perforce-group, enter the following in the Include users from groups field: ^perforce-group$

   For details and more examples, see Section: helix.

2. Click Save preferences.

   A warning appears because the changes have not been applied to the TeamHub server yet. Perform the following step to finalize the configuration.

3. To apply server configuration changes to the TeamHub server, connect to the server via SSH and run the following command:

   sudo hth-ctl reconfigure

4. After successfully running the reconfigure command, reload the TeamHub admin portal.

   Failure to do so may result in normal web server interruption messages, such as the HTTP Error 503. The service is unavailable. error, because the services come back online.

JSON configuration examples

This section includes examples of how to exclude groups and users by editing the "helix" key in the /var/opt/hth/shared/hth.json file. Excluding groups and users works exactly the same way, so you can apply the following examples to all cases.

To exclude all groups starting with external- or test- or ending with test:

^(external-|test-).*, test$

To exclude user1 and user2, and any user starting or ending with test:

^(user1|user2)$, test$, ^test

Following is a code snippet from the hth.json file with these values included under the "helix" key:

"users_include_regex": "",
"users_exclude_regex": "^(user1|user2)$, test$, ^test",
"users_from_groups_include_regex": "",
"users_from_groups_exclude_regex": "",
"groups_include_regex": "",
"groups_exclude_regex": "^(external-|test-).*, test$"

Frequently asked questions (FAQ) about P4 authentication

This section provides answers to commonly asked questions related to P4 authentication.

Question	Answer
If I update a user or group on the P4 Server, how long does it take for TeamHub to pick up the change?	By default, TeamHub polls P4 Server every 5 minutes for updates. You can configure this interval via an environment variable.
Where can I find a list of all Git related configurables for TeamHub?	A list of environment variables is located in the following location: /opt/hth/.profile_backend
Can a TeamHub user who has different roles in different projects use the same email address?	TeamHub allows one user to have different roles in different projects, but a user can only be linked to a single email address. Vice versa, a single email address can only be linked to one user.
Why can I log into TeamHub as instance admin with two different passwords?	This may happen as the result of an internal TeamHub failsafe to prevent you from locking yourself out of misconfigured instances. You can always log in to a TeamHub instance with the credentials for the default admin user. If you have P4 authentication enabled and a user called admin also exists in P4 Server, you can also use the P4 Server password to log in to the TeamHub admin portal. See also Perforce TeamHub administrators.
If I remove a user with admin role in a TeamHub instance from P4 Server, this user is still able to log back into TeamHub with all previous admin privileges even though the user no longer exists in P4 Server. How do you revoke permissions from a user with an admin role in a TeamHub instance?	This is related to the previous question. In this scenario, the user called admin still exists in the built-in admin portal and gets authenticated because the admin user has a special authentication flow, separate from the normal authentication flow. To remove access to the TeamHub admin portal: Log in to the admin portal: <TeamHub-instance-URL>/admin/login In the Admins view, remove the user from the list of existing administrators. See also Perforce TeamHub administrators.

Troubleshooting P4 authentication

When trying to resolve a problem with TeamHub authentication, start with running the following command as an admin user on the TeamHub server:

hth-ctl tail

This command will give you an overview of what is going on in all TeamHub log files. Following is a list of log file locations and descriptions.

Folder	Description
unicorn_backend	Unicorn logs for TeamHub backend errors
mongodb	Mongo database logs for backend
redis	Redis storage logs used by backend
logrotate	logrotate logs for all log files
docker_registry	Logs for docker repositories
nginx	All HTTP requests
resque	Logs for background jobs
resque-scheduler	Logs for scheduled background jobs
streamer	Logs for streaming files from repositories
maven	Logs for Maven and Ivy repositories

In addition, the following table may assist you in troubleshooting common issues experienced with P4 Server authentication.

	Issue	Root Cause/Resolution
For administrators	Sync with P4 Server seems to fail.	Make sure the P4 Server user is a valid user in TeamHub. TeamHub only supports user names up to 100 characters while P4 Server supports longer names. This gives an error during the sync operation that only appears in the log files. The TeamHub UI does not indicate a problem.
	Authentication fails and the logs indicate Redis problems.	This may happen if Redis is configured to save snapshots but cannot persist on disk. You can either turn off snapshot saving or verify that Redis can save to the specified path.
	Git repos stored in P4 Server are unresponsive.	P4 Server may be down.
	I have added a user in P4 Server, but it is not available in the TeamHub UI.	TeamHub probably has not synced the data from P4 Server. By default, sync happens every 5 minutes.
	The Git repository type I am looking for is not available even though I enabled P4 authentication for the TeamHub instance.	Make sure you reloaded the TeamHub client page after enabling P4 authentication in the TeamHub admin portal. TeamHub fetches instances settings during the initial page load. This means that if you change instance settings in another tab or window while a TeamHub client is already open, it won't retrieve the updated instance settings until you refresh the page.
	I cannot log in to the new company I created.	With P4 authentication, TeamHub only supports one company per instance. The option to create additional companies is unavailable. It is recommended that you start from scratch with a new TeamHub instance when using P4 authentication. (Companies are not supported by P4 DAM.)
	The TeamHub trigger script (hth-trigger.pl) cannot find the required Perl libraries and fails with a 599/Internal Exception error written to the system log.	Root cause:  The TeamHub trigger script is written in Perl. In lieu of hardcoding the path to the Perl installation, the script includes the following shebang line to use the Perl installation found in the system: #!/usr/bin/env perl However, if the system includes more than one Perl installation, the script might access one that does not include the packages needed by Ubuntu to use HTTPS URL for the TeamHub API. As a result, when the SDP (Server Deployment Package) puts /p4/common/bin/perl in the perforce UNIX user's path before /usr/bin/perl, the SDP's Perl code does not know where to find the required Perl libraries. Workaround: Change the shebang line in the trigger file to the following: #!/usr/bin/perl
For users	I cannot push anything to a Git repo that is stored in P4 Server.	Make sure you have added an SSH public key through the TeamHub UI. For more information, see Configuring SSH keys. If you have added an SSH public key, TeamHub probably has not synced the data. By default, sync happens every 5 minutes. If you are using a self-signed certificate, this may happen because an SSL connection is enforced. Verify that your git configuration has the appropriate setting for http.sslVerify.