Helix authentication
This section provides instructions on how to:
- Set up Helix server authentication
- Set up Helix trigger scripts for TeamHub
- Add users and groups in Helix server
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.
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).
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.
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:
- In a web browser, go to the Helix TeamHub admin portal:
<TeamHub-instance-URL>/admin/login
-
Enter your user name and password and click Log in.
The default values are
admin
/admin
. - When prompted, enter your license information and click Apply.
-
In the Preferences view:
- Enter the hostname of your Helix TeamHub instance.
- Under Authentication, select Helix.
-
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
-
[HTH-688] 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.WarningDeleting 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.
-
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.
NoteYou 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 server
super
user -
Charset: The character encoding set for Helix server, such as
utf8
or noneTo find the Helix server charset, run:
p4 -ztag info
When connecting to a non-unicode server, the charset is none by default [HTH-1048]. If the charset is not shown, select
none
from the list. For more information on Helix server charsets, run:p4 help charset
-
- Click Test Helix Core connection and wait for the message:
Successfully connected to Helix.
-
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.
-
Select SSH or HTTPS as the method used to connect to the Git Connector.
We strongly suggest enabling both.
-
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.
-
To apply server configuration changes to the TeamHub server, connect to the server via SSH and run the following command:
sudo hth-ctl reconfigure
-
After successfully running the reconfigure command, reload the TeamHub admin portal.
WarningFailure 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.
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:
- Filesystem installation
- Depot installation (recommended)
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
andlibio-socket-ssl-perl
Filesystem installation
- 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
- 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.
- 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. - Follow steps for trigger configuration.
-
To make sure that the script has execute permissions, run:
chmod +x ./hth-trigger.pl
-
In the filesystem location of your trigger script, run the following command to invoke it:
./hth-trigger.pl -o
NoteTo see additional usage information, run the trigger script without any arguments.
-
As a Helix server user with
super
privileges, edit the Helix server trigger table by running thep4 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
- 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
-
(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
NoteHelix 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.
- Copy the configuration file (
/opt/hth/external/helix/triggers/hth-trigger.conf
) to the same directory in Helix server as the trigger file. - Submit the configuration file to the depot. The recommended depot location is:
//.hth/triggers/hth-trigger.conf
- Follow steps for trigger configuration.
-
Invoke the trigger script by running the following command:
p4 print -q //.hth/triggers/hth-trigger.pl | perl - -o
NoteTo see additional usage information, run the trigger script without any arguments.
-
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.
ImportantIf 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:
- 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
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 |
|
Manager |
|
Master |
|
Developer |
|
Guest |
|
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:
- Includes direct users
- Adds users from groups
- Excludes users from groups
- 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:
-
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.
-
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.
-
To apply server configuration changes to the TeamHub server, connect to the server via SSH and run the following command:
sudo hth-ctl reconfigure
-
After successfully running the reconfigure command, reload the TeamHub admin portal.
WarningFailure 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: |
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 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 |
This is related to the previous question. In this scenario, the user called
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 |
Your search for returned result(s).