Helix TeamHub Administrator Guide (2020.1 Enterprise)

Helix authentication

This section provides instructions on how to:

For more information, see:

Set up Helix server authentication

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

Important

If Helix is the selected method of authentication and Helix server uses LDAP authentication, there is no need to use LDAP authentication in TeamHub. Authentication requests from TeamHub are parsed to Helix server, which then connects to the LDAP/AD server to perform the authentication for the user. Note that LDAP authentication on the Helix server side must be established using the LDAP specification method (for details, see Authenticating against Active Directory and LDAP servers section in the Helix Core Server Administrator Guide).

Note

Some options are dependent on others and only display if required. For example, the option to add fingerprints only displays if TeamHub detects a P4PORT value that starts with SSL.

If you need information on configuring the Git Connector, see the Helix4Git Administrator Guide, section Installation and configuration. 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 Helix4Git.

Warning

Once you have configured Helix authentication and the TeamHub instance is in use, it is not possible to revert back to a different authentication method.

To set up Helix server authentication:

  1. In a web browser, go to the Helix 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 Helix TeamHub instance.
    2. Under Authentication, select Helix.
    3. Specify 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 P4 Command 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 TeamHub. Instead, you need to make this change on the Helix server side and wait for the sync.

      • Ticket/Password: The password/ticket for the existing Helix serversuper user
      • 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 the Helix4Git 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 trigger scripts for TeamHub

Helix server provides triggers to customize the operation of the server, or to invoke additional processing for specific kinds of versioning operations. Helix TeamHub provides a trigger script written in Perl that notifies TeamHub about activity within the Helix server. When configured, any pushes you do to your graph depots are visible as events in the Helix TeamHub activity stream in the Activity view.

For TeamHub to display push events in the UI, you need to configure the TeamHub trigger in the Helix server. The trigger supports the following events:

  • branch create
  • branch delete
  • tag create
  • tag delete
  • push

The trigger script is part of the installation package you downloaded earlier (see Combo Setup).

For more information about triggers, see the section Using triggers to customize behavior in the Helix Core Server Administrator Guide.

Configuring the trigger requires that you already have an admin bot account. For more information on setting up an admin bot account, see the Helix TeamHub User Guide, section Bots & programmatic repository access.

Note

Creating bots is not part of the TeamHub admin portal. You need to log out of <TeamHub-instance-URL>/admin/login and log on to <TeamHub-instance-URL>/login as company admin.

To set up the TeamHub trigger, you have the following options:

Important

Make sure that the following required trigger dependencies have been installed on the machine hosting Helix server:

  • Perl 5.08+
  • Perl Core on CentOS
  • On Ubuntu Xenial (16.04) only, packages libnet-ssleay-perl and libio-socket-ssl-perl

Filesystem installation

  1. Copy the TeamHub trigger file from the TeamHub instance to the server hosting Helix server. The trigger file lives on the TeamHub instance at the following location: /opt/hth/external/helix/triggers/hth-trigger.pl
  2. If your Helix server deployment uses the commit-edge architecture, you must also copy the script to all edge servers. In this case, make sure the script location has the same path on all servers.
  3. Copy the configuration file (/opt/hth/external/helix/triggers/hth-trigger.conf) to the same directory in Helix server as the trigger file. If you copied the trigger script to the commit server and all edge servers in the previous step, also copy the configuration to the same directory on all servers.
  4. Follow steps for trigger configuration.
  5. To make sure that the script has execute permissions, run:

    chmod +x ./hth-trigger.pl
  6. In the filesystem location of your trigger script, run the following command to invoke it:

    ./hth-trigger.pl -o
    Note

    To see additional usage information, run the trigger script without any arguments.

  7. As a Helix server user with super privileges, edit the Helix server trigger table by running the p4 triggers command (P4 Command Reference) and adding the output lines from the previous command (including the initial tab character).

    Update the trigger script and configuration file paths in each line to reflect the actual paths on your Helix server.

    Provided that you have copied the trigger script and configuration file to common paths on all servers, the trigger line will resemble the following:

    hth.push-ref-complete graph-push-reference-complete //... "%quote%/path/to/hth-trigger.pl%quote% -t graph-push-reference-complete -d %depotName% -n %repo% -N %repoName% -p %pusher% -r %quote%%reference%%quote% -O %oldValue% -v %newValue%"

Depot installation

  1. Copy the TeamHub trigger file from the TeamHub instance to the server hosting Helix server. The trigger file lives on the TeamHub instance at the following location: /opt/hth/external/helix/triggers/hth-trigger.pl
  2. (Recommended) Submit the trigger script (hth-trigger.pl) to Helix server and run it from the following location in the depot: //.hth/triggers/hth-trigger.pl

    Note

    Helix TeamHub does not create this depot. You either need to create it yourself or specify another depot that the TeamHub admin user can write to.

    To create a //.hth depot, run the following as a user with admin-level privileges:

    $ p4 depot .hth

    Ensure that the TeamHub admin user can write to //.hth depot.

    For more information on creating and working with depots, see Working with depots in Helix Core Server Administrator Guide.

  3. Copy the configuration file (/opt/hth/external/helix/triggers/hth-trigger.conf) to the same directory in Helix server as the trigger file.
  4. Submit the configuration file to the depot. The recommended depot location is: //.hth/triggers/hth-trigger.conf
  5. Follow steps for trigger configuration.
  6. Invoke the trigger script by running the following command:

    p4 print -q //.hth/triggers/hth-trigger.pl | perl - -o
    Note

    To see additional usage information, run the trigger script without any arguments.

  7. Provided you have copied the script and the configuration file to common paths on all servers, the trigger line will resemble the following:

    hth.push-ref-complete graph-push-reference-complete //... "%//.hth/triggers/hth-trigger.pl% -c %//.hth/triggers/hth-trigger.conf% -t graph-push-reference-complete -d %depotName% -n %repo% -N %repoName% -p %pusher% -r %quote%%reference%%quote% -O %oldValue% -v %newValue%"

    The trigger line is also available in the hth-triggers file in the same directory from which you copied the trigger and configuration scripts. However, the line might not resemble your actual setup. Therefore, we suggest that you use the -o flag mentioned in step 6.

    Important

    If your output does not use the depot location, you should update this line to reflect the depot location of the trigger file and the trigger configuration file in your installation.

Trigger configuration

The trigger by itself cannot run without connection to Helix TeamHub. Edit the configuration file by specifying the values for the following variables:

  • HTH_HOST = Hostname of your Helix TeamHub instance accessible from Helix server (in the form of https://hostname or http://hostname)
  • HTH_COMPANY_KEY = Company key from your company admin bot settings in Helix TeamHub.
  • HTH_ACCOUNT_KEY = Account key for an admin bot account.
  • VERIFY_SSL = Verification of the SSL certificate for Helix TeamHub if running in SSL mode. Enabled by default.

Add users and groups in Helix server

With Helix authentication, you add users and groups through the Helix 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:

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

Warning

In Helix server, do not alter or edit groups with a name following any of these conventions in any way:

HTH-//<depot-path>/<repo-path>-<HTH_ACCESS_LEVEL>

HTH-<depotname>-<hth_access_level>

HTH-<company-admin>

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 P4 Command Reference.

For more information on Helix 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 Helix TeamHub UI, or exclude them from being displayed in the Helix 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 Helix TeamHub configuration section. 

From the resulting list of users, TeamHub first synchronizes existing bots and then synchronizes all other users.

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

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

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 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:

  1. Log in to the admin portal: <TeamHub-instance-URL>/admin/login
  2. In the Admins view, remove the user from the list of existing administrators.

See also TeamHub Administrators.

Troubleshooting Helix authentication

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

hth-ctl tail

This command will give you an overview of what is going on in all Helix 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 Helix 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.

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 on Ubunty Xenial 16.04 (libnet-ssleay-perl and libio-socket-ssl-perl) 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 Helix 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.