Helix Core user and group provisioning

The advantage of Helix Core user and group provisioning is that users you create in your cloud service provider (such as Okta, Azure, OneLogin) can automatically be provisioned as Helix Core users. In addition, these users can authenticate with HAS.

This functionality is an implementation of the System for Cross-domain Identity Management (SCIM).

Provisioning is independent of HAS

Although we encourage customers using HAS to also take advantage of this service for user and group provisioning, it is optional and independent. That means:

  • you can use HAS with or without using this service for user and group provisioning

  • you can use this service for user and group provisioning with or without using HAS

Limitations

This implementation of SCIM does not support deprovisioning.

Any attempt by the cloud service provider to rename a user is rejected with a “mutability” error. Although the ALLOW_USER_RENAME setting can be set to true, renaming a user in Helix Core can have adverse effects.

Okta permits renaming a user, and removing the renamed user from Okta, but the renamed user remains active in HAS.

Configuring users and groups

Prerequisites

Make sure that the HAS service is visible on the public internet so that the cloud service provider can connect to it.

Configure P4TRUST and P4TICKETS

  1. On the HAS system, use the p4 user account with the super access level to run p4 trust and p4 login See p4 trust and p4 login in Helix Core Command-Line (P4) Reference.

  2. Make sure the ticket is a long-lived one. To create a ticket that does not expire after the default of 12 hours, see Ticket-based authentication in Helix Core Server Administrator Guide.

  3. Make sure that the .p4tickets and .p4trust files are readable by the system user that is running the HAS process. This system user is probably the perforce user if you installed HAS using a package.

  4. Set P4TICKETS and P4TRUST in the HAS .env file to reference the .p4tickets and .p4trust files you created in Step 1.

Configuration steps

  1. In your cloud service provider:

    1. Make sure that you have Helix Core groups. The most basic arrangement is a group for Helix Core administrators and a group of regular users, but you can have any number of groups and control access in many ways. See Setting protections with p4 protect in Helix Core Server Administrator Guide.

    2. Create Helix Core users and assign them to the appropriate Helix Core groups.

    3. Assign passwords to the users, and best practice is to tell the users to change their password upon login.

  2. Edit the .env file you use for Configuring to include the following settings:

    1. BEARER_TOKEN='your-password-to-HAS'

      2. Note

      Some cloud server providers might require the BEARER_TOKEN value to be encoded in base64 format, which you can do at https://www.base64encode.org/

    2. P4PORT=192.168.1.3:1666 with the IP address and port number to connect to the Helix Core server.

    3. P4USER=super
      This is the user with super Permission levels and access rights to the Helix Core server.

    4. P4PASSWD=password-or-ticket-for-P4USER

  3. In the form for configuring the cloud service provider's provisioning feature, provide:

    1. the URL of the HAS service with /scim/v2 appended as a suffix. For example: https://has.example.com/scim/v2

    2. the BEARER_TOKEN you configured in Step 2.

You can now create Helix Core groups and users with the provisioning service of your cloud service provider.

Note

This provisioning service follows the standard of System for Cross-domain Identity Management (SCIM) to automate the following Helix Core commands:

  • p4 group to create groups, change the users in a group, and delete groups

  • p4 user to create and delete users

You can set user passwords in your Helix Core client, or set user passwords in your cloud service provider. If you set user passwords in your cloud service provider, the HAS-based provisioning sets those same user passwords in the Helix Core server. Similarly, you can find out through your cloud service provider the list of Helix Core users and groups.

If you use the HAS-based provisioning service to assign a user or a group to HAS (and/or HAS-based provisioning), you are responsible for setting the appropriate Helix Core protections (see p4 protect in Helix Core Command-Line (P4) Reference).

Similarly, you are responsible for making sure the groups and users in your Helix Core server and your cloud service provider are sync with each other. The cloud service provider might be able to do a sync and discover any groups or users created directly in Helix Core, but the Helix Core server cannot query the cloud service provider.

How to re-activative a user

If you make a user inactive, that user is logged out and that user's password loses validity.

Suppose you want to restore that user as an active user:

  • If the user authenticates with SSO, enable the user within the cloud service provider, such as Azure AD

  • If that user has a Helix Core Server password:

    • reset the password in the cloud service provider's provisioning feature

    • If the cloud service provider is not managing user passwords, reset the password with the Helix Core Server p4 passwd command

Multiple Helix Core servers

If you want to allow one HAS instance to connect to multiple Helix Core servers, configure the provisioning setting for each server. This example shows two servers, one in the United States (p4port = "ssl:chicago:1666") and one in Japan (p4port = "ssl:tokyo:1666").

[provisioning]
[[provisioning.providers]]
bearer_token_file = "feline-token.txt"
domain = "feline"

[[provisioning.providers]]
bearer_token_file = "canine-token.txt"
domain = "canine"

[[provisioning.servers]]
p4port = "ssl:chicago:1666"
p4user = "super"
p4passwd = "2E7092CC2CA6BCAC74EB364BF4C4AD99"
domains = [ "feline", "canine" ]
leader = [ "canine" ]

[[provisioning.servers]]
p4port = "ssl:tokyo:1666"
p4user = "super"
p4passwd = "C8478F3F32B62A84731ADDB5A2443E68"
domains = [ "canine" ]

where:

  • Each Cloud service provider is defined in its own provider section.

  • Incoming requests are assigned to a domain based on the bearer token that is used by the client.

  • Each Helix Core Server instance is defined in its own [[provisioning.servers]] section and each server can belong to one or domains.

The configuration example above uses the TOML file format for HAS.

Constraints:

  • Each provider must have its own bearer_token_file

  • If multiple servers are assigned to a particular domain, exactly one of them must have that domain listed in their leader list. In this example, the server associated with Chicago is the leader.

  • Each domain name must be unique. The name can contain letters and numerals. Except for underscores, no special characters or blank spaces are allowed in domain names.