Skip to main content

Authenticate using a Built-in Account

The Code Sign Client authenticates to Next-Gen Trust Security (NGTS) using a Built-in Account. A Built-in Account provides the credentials — a Client ID and an authentication key pair — that allow developers and automated systems (such as CI/CD pipelines) to perform signing operations. Because a Built-in Account is not tied to an interactive user login, the same approach works for both individual developers and non-interactive build environments.

Once authenticated, the client can list and use any Signing Keys within the Built-in Account's TSG scope.

Before you begin​

  • A NGTS administrator has created a Built-in Account for code signing. See the NGTS code signing product documentation for the UI steps.
  • The Built-in Account is scoped to a TSG that contains at least one Signing Key.
  • The Code Sign Client is installed on the signing machine.

How Built-in Account authentication works​

A Built-in Account is created in the NGTS UI (System Settings > Certificate Settings > Built-in Accounts) with one of two key-pair methods. The difference comes down to where the key pair is generated:

  • Auto-generate a keypair and download the private key — The key pair is generated in the UI. You copy and save the private key as a PEM file on the signing machine, then use it to authenticate the client. This is less secure because the private key is transmitted through the UI, but it lets you log out and log back in without generating a new key pair.
  • Generate your own keypair and upload the public key — The key pair is generated on the signing machine by the Code Sign Client. You paste the public key into the UI. This is more secure because the private key never leaves the signing machine, but logging out requires generating a new key pair to log in again.

Either way, NGTS issues a Client ID for the account, which you provide to the Code Sign Client.

All examples use the pkcs11config utility. If you are using the CSP/KSP client on Windows, replace pkcs11config with cspconfig. Command options are the same.

Authenticate the client​

Your --host value is your TSG endpoint, in the form <tsg-id>.ngts.paloaltonetworks.com. When you authenticate, the client automatically detects and sets the authentication, HSM, and update-service URLs from this host.

Using a downloaded private key​

If your Built-in Account was created with Auto-generate a keypair and download the private key, save the private key to a PEM file (for example, key.pem) on the signing machine, then run:

pkcs11config login --host <tsg-id>.ngts.paloaltonetworks.com --clientid <client-id> --keyfile key.pem

Generating the key pair on the signing machine​

If your Built-in Account was created with Generate your own keypair and upload the public key, generate the key pair on the signing machine first:

pkcs11config login --host <tsg-id>.ngts.paloaltonetworks.com --generate

The client displays the public key. Copy it into the NGTS UI to finish creating the account, copy the resulting Client ID, then return to the client and paste the Client ID when prompted.

Verify your configuration​

pkcs11config option show

Your result should look similar to the following:

INFO: User configuration holds 9 values:
Name                           │ Value
───────────────────────────────┼───────────────────────────────────────────────────
ACCESS EXPIRES                 │ 1765225693
AUTHENTICATION PRIVATE KEY PEM │ <redacted>
HSM SERVER URL                 │ https://<tsg-id>.ngts.paloaltonetworks.com/vedhsm/
ACCESS TOKEN                   │ <redacted>
AUTH SERVER URL                │ https://<tsg-id>.ngts.paloaltonetworks.com/
CREDENTIAL EXPIRES             │ 1765311162
CSC SERVER URL                 │ https://<tsg-id>.ngts.paloaltonetworks.com/cyberark-code-sign-client/
CLIENT ID                      │ xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

List your keys and certificates​

If the Built-in Account is scoped to a TSG that contains one or more Signing Keys, you can list those signing objects now:

pkcs11config list

Your result should look similar to the following:

Certificate 1:
Label:       Signing Key Name
Subject:     CN=Example\, Inc.
ID:          34353563356132632D333634392D343065652D616261302D306132623436326632333466
Environment: Certificate

Public Key 1:
Label:       Signing Key Name
Key-Type:    RSA 2048
ID:          34353563356132632D333634392D343065652D616261302D306132623436326632333466
Environment: Certificate

If you do not see any objects, confirm that the Built-in Account is scoped to the TSG where the Signing Keys are configured.

Troubleshooting​

"INFO: No objects available."​

This means the client authenticated successfully, but the Built-in Account cannot access any Signing Keys.

Verify that:

  • The Built-in Account is scoped to the TSG where the Signing Keys are configured. A Built-in Account can only access Signing Keys within its own TSG (and child TSGs, if it was created on a parent TSG).
  • The TSG contains at least one Signing Key.

"Authentication failed"​

Check the following:

  • Confirm you entered your TSG endpoint (<tsg-id>.ngts.paloaltonetworks.com), not a tenant UI URL.
  • Confirm the Client ID matches the value shown in the NGTS Built-in Accounts inventory.
  • Make sure the private key file (--keyfile) corresponds to the key pair for this Built-in Account.
  • Make sure the signing machine's clock is reasonably accurate. Significant time skew can cause token validation to fail.

What's next​

After authenticating with a Built-in Account, you can: