Helix authentication

This section provides instructions on how to:

• Set up Helix Server authentication
• Set up Helix Core Server extensions
• Add users and groups in Helix Server

For more information, see:

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

Set up Helix Server authentication

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

If you need information on configuring the Git Connector, see Installation and configuration in Helix Core Server Administrator Guide. Before you proceed, make sure you read the Helix authentication prerequisites .

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

To set up Helix 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 Helix Server details:

      The Helix 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 Helix server, in the following format: host:port

      • Fingerprint: If you connect to Helix 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 Helix Core Command-Line (P4) Reference.

        Warning

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

   4. Specify details for the Helix integration user:

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

        Note

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

         

        The Helix 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 Helix Server user with super level privileges.

      The existing Helix 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 Helix 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>
      

      Tip

      For more information about managing Helix Server groups, see P4 group in the Helix Core Command-Line (P4) Reference.

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

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

      4. Use the unlimited ticket for Ticket/Password.

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

        To find the Helix 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 Helix Server charsets, run: p4 help charset

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

   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)
      • Helix User: The Helix Server user of the Git Connector (default: gconn-user)

      For more information, see Configure the Git Connector in Helix Core Server Administrator Guide .

   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.

   Warning

   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 Helix Core Server extensions

Helix Core Server provides extensions to customize server operations or invoke additional processing for specific versioning operations. Helix TeamHub extensions notify TeamHub about activity on the Helix Core 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 Helix Core Server extensions for information about configuring the extensions.

Add users and groups in Helix Server

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

To create users and groups, see the following topics in the Helix TeamHub User Guide:

• Users
• Groups

To perform these tasks on the Helix Server side, see the following sections in the Helix Core Server Administrator Guide:

• 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 of TeamHub roles to graph depot permissions

Whereas in Helix 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 Helix 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 Helix Server permissions, see the p4 grant-permission command in the Helix Core Command-Line (P4) Reference.

For more information on TeamHub roles, see the Roles chapter in the Helix TeamHub User Guide.

Including and excluding of Helix Server users and groups

You may want to include users or groups, or one or more users in a group, that exist in Helix Server in the TeamHub UI, or exclude them from being displayed in the TeamHub UI. This is possible by configuring the respective keys, either in the TeamHub Admin portal, under Preferences > Helix Server > Account and group synchronization, or in the /var/opt/hth/shared/hth.json configuration file. For details on these keys, see Section: pilsner in the TeamHub configuration section. 

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 Helix 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: pilsner.

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.

   Warning

   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 pilsner key in the /var/opt/hth/shared/hth.json file. Including or excluding users, users from groups, and groups 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 "pilsner" key:

"helix_users_include_regex": "",
"helix_users_exclude_regex": "^(user1|user2)$, test$, ^test",
"helix_users_from_groups_include_regex": "",
"helix_users_from_groups_exclude_regex": "",
"helix_groups_include_regex": "",
"helix_groups_exclude_regex": "^(external-|test-).*, test$"

Frequently asked questions (FAQ) about Helix authentication

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

Question	Answer
If I update a user or group on the Helix Server, how long does it take for TeamHub to pick up the change?	By default, TeamHub polls Helix 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 Helix authentication enabled and a user called admin also exists in Helix Server, you can also use the Helix Server password to log in to the TeamHub admin portal. See also Helix TeamHub administrators.
If I remove a user with admin role in a TeamHub instance from Helix Server, this user is still able to log back into TeamHub with all previous admin privileges even though the user no longer exists in Helix 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 Helix TeamHub administrators.

Troubleshooting Helix authentication

When trying to resolving 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
puma_pilsner	TeamHub to Helix Server adapter logs
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
puma	Logs for websockets
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 Helix Server authentication.

	Issue	Root Cause/Resolution
For administrators	Sync with Helix Server seems to fail.	Make sure the Helix Server user is a valid user in TeamHub. TeamHub only supports user names up to 100 characters while Helix 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 Helix Server are unresponsive.	Helix Server may be down.
	I have added a user in Helix Server, but it is not available in the TeamHub UI.	TeamHub probably has not synced the data from Helix Server. By default, sync happens every 5 minutes.
	The Git repository type I am looking for is not available even though I enabled Helix authentication for the TeamHub instance.	Make sure you reloaded the TeamHub client page after enabling Helix 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 Helix 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 Helix authentication. (Companies are not supported by Helix 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 Helix Server.	Make sure you have added an SSH public key through the TeamHub UI. For more information, see the Configuring SSH keys section in the Helix TeamHub User Guide. 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.