Tutorial: Setting up Code Sign Manager - SaaS with a service account¶

This tutorial shows you how to configure Code Sign Manager - SaaS for a service account, such as one used by a CI or build system. Unlike API keys, which are tied to individual users, service accounts allow the Code Sign Client to authenticate independently of any specific person, making them suitable for automated or non-interactive signing workflows.

This tutorial does not cover all available configuration options. Instead, it provides a focused, end-to-end workflow that demonstrates how automated systems authenticate and perform signing operations through Code Sign Manager - SaaS.

What you'll do¶

This tutorial includes steps performed in both the Code Sign Manager - SaaS UI and in the Code Sign Client running on the signing machine. In many environments, the same person completes all of these steps, but they can also be split between administrative and DevOps teams depending on your workflow.

You will complete the following tasks:

• In the Code Sign Manager - SaaS UI, create a Project with no authorized signers.
• Create a Signing Key and add it to the Project.
• Download and install the Code Sign Client on the signing machine.
• In the UI, create a team to assign to the service account.
• Create a service account in the UI and generate its key pair on the signing machine.
• Assign the service account as the Authorized Signer for the Project.
• On the signing machine, perform a sample signing operation and verify the signature.

Before you begin¶

To complete this tutorial, you will need the following:

• An account with administrative permissions (either the System Administrator or PKI Administrator role in Certificate Manager - SaaS).
• A signing workstation where you can install the Code Sign Client. This can be a Windows, Linux, or macOS workstation. See system requirements.

Step 1: Create a Code Sign Project¶

Start by creating a Code Sign Project. This project will hold the Signing Key that the service account will use later in the tutorial.

1. Click Configurations > Code Sign Projects.
2. Click New.

3. In Project name, enter Tutorial service account project.

   Note

   This exact name will be used in a command later in this tutorial.

4. From Owners, select any administrators who should be able to manage this Project.

5. In Description, enter This is my tutorial service account project.
6. Click Continue.
7. Leave Authorized signers empty for now. You will return to this field after the service account is created.
8. Click Finish.

Step 2: Create a Signing Key¶

Next, create a Signing Key and add it to the Project. The service account will later act as the Authorized Signer and use this Signing Key.

1. Click Inventory > Signing Keys.
2. From the Projects drop-down, ensure that Tutorial service account project is selected.
3. Click New.

4. In Signing key name, enter Tutorial service account key.

   Note

   This exact name will be used in a command later in this tutorial.

5. In Description, enter This is my tutorial service account signing key.

6. Click Continue.
7. In Key pair properties, do the following:
   • Leave Key storage type and Key storage location unchanged.
   • Set the validity period to 24 hours.
   • Select any Key algorithm.
8. Click Continue.
9. In Certificate properties, do the following:
   • Leave Certificate authority set to Built-in CA.
   • Leave Product option set to Default product.
   • For Common name, enter Tutorial Service Account, Inc.
   • All other fields are optional.
10. Click Continue.
11. In Cryptographic object creation, select Create cryptographic objects now, and then click Finish.

After the key and certificate are created, the details drawer for the Signing Key opens automatically.

Step 3: Download and install the Code Sign Client¶

With the Project and Signing Key created, install the Code Sign Client on the signing machine so automated signing operations can be performed.

1. Sign in to Certificate Manager - SaaS.
2. Click Inventory > Signing Keys.
3. From the Projects drop-down, select Tutorial service account project.
4. Select Tutorial service account key to open its details drawer.
5. Select the Client installation tab.
6. Select the appropriate platform for the signing machine, and then either download and install the client or follow the on-screen installation instructions.

Step 4: Create a Team¶

Next, return to the Code Sign Manager - SaaS UI to create a Team. This Team will later become the owning team for the service account.

1. Click Settings > Teams.
2. Click New to create a new Team.
3. In Team, enter Tutorial service manager team.
4. Select one or more Owners. Owners can edit the Team’s membership and settings.

5. In Members, select any users you want to include, or leave the field blank.

   Tip

   Leaving this field blank means that only the service account will be allowed to use the Signing Keys associated with the Project. Adding users allows those individuals to use the keys when they authenticate with their own API keys.

6. For Role, select Resource Owner.

7. Click Next.
8. For this tutorial, you do not need to set up membership rules, so click Save.

Step 5: Create and authenticate a Service Account¶

Now create a service account and associate it with the Team. You will use the Code Sign Client on the signing machine during this process. Information must be copied between the UI and the Client to authenticate the service account.

1. Click Settings > Service Accounts.

2. Click New.

3. In the Use case section, select Code Sign Manager, and then click Continue.

4. In the Details section, do the following:

   1. For Name, enter Tutorial service account.
   2. For Owning team, select Tutorial service manager team.
   3. For Validity, enter 1 day.

   4. For Authentication method, select Generate your own keypair and upload the public key.

      What are the implications of each method?

      The difference between the two authentication methods is where the key pair is generated.

      • Auto-generate a keypair and download the private key — The key pair is generated in the UI. You must copy and save the private key as a PEM file on the signing machine and use it to authenticate the Code Sign Client.

      • Generate your own keypair and upload the public key — The key pair is generated on the signing machine by the Code Sign Client. You then paste the public key into the UI. This method keeps the private key on the signing machine and never exposes it through the UI.

   5. For Scope, select Codesign Service Account Authorized Signer Scope.

   6. Click Continue.

5. Complete the Credentials section.

   Note

   The command examples in this section use the pkcs11config utility and the U.S. region hostname. If you are using a different utility or working in a different region, adjust the commands accordingly.

   1. On the signing machine, run the following to authenticate and generate a key pair:

      pkcs11config login --host api.venafi.cloud --generate
      

      This sets your hostname URLs, generates a key pair, and displays the public key.

      Note

      If the command fails because a previous authentication exists, rerun it with --force to overwrite the existing configuration.

      1. If you have not already added the Certificate Manager - SaaS certificates to your trust store, select y to add them.
      2. Copy the displayed public key.
      3. Return to the UI. In Credentials, paste the public key, and then click Finish. The Service Accounts inventory page opens.
      4. Copy the Client ID for this service account.
      5. Return to the Code Sign Client and press Enter.
      6. Paste the Client ID, and then press Enter.

6. (Optional) 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 │ <365 characters redacted>
   HSM SERVER URL                 │ https://api.venafi.cloud/vedhsm/
   ACCESS TOKEN                   │ <24 characters redacted>
   SUPPORTS API KEY               │ true
   AUTH SERVER URL                │ https://api.venafi.cloud/
   CREDENTIAL EXPIRES             │ 1765311162
   CSC SERVER URL                 │ https://dl.venafi.cloud/cyberark-code-sign-client/
   CLIENT ID                      │ xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
   

Step 6: Assign the service account as the Authorized Signer¶

Now that the service account is configured and authenticated, you can assign it as the Authorized Signer for the Project.

1. Sign in to Certificate Manager - SaaS.
2. Click Configurations > Code Sign Projects.
3. Select Tutorial service account project.
4. Select the Signing key properties tab.
5. From Authorized signers, select Tutorial service account.
6. Click Save.

Step 7: Sign a file and verify the signature¶

With the service account now acting as the Authorized Signer, use the signing machine to perform a signing operation and verification.

1. On the signing machine, list your available Signing Keys:

   pkcs11config list
   

   If you have followed this tutorial, the output should look similar to the following:

   Certificate 1:
   Label:       Tutorial service account project-Tutorial service account key
   Subject:     CN=Tutorial Service Account\, Inc
   ID:          64346264333165662D326333662D346539662D393665322D663461396561643138386331
   Environment: Certificate
   
   Public Key 1:
   Label:       Tutorial service account project-Tutorial service account key
   Key-Type:    RSA 2048
   ID:          64346264333165662D326333662D346539662D393665322D663461396561643138386331
   Environment: Certificate
   

2. In a temporary directory, create a file called signme.txt:

   echo "This is my test file" > signme.txt
   

3. Sign the file:

   pkcs11config sign --filename signme.txt --label "Tutorial service account project-Tutorial service account key" --output signme.txt.sig
   

   Note

   The --label value is <Project name>-<Signing Key name>. If you used different names, update the example command to match your values.

   If the signing succeeds, you will see a message similar to:

   SUCCESS: Signed file 'signme.txt', signature written to 'signme.txt.sig'.
   

   Note

   If the signing fails, try running pkcs11config sign without arguments to use the interactive signing wizard.

4. Verify the signature:

   pkcs11config verify --filename signme.txt --label "Tutorial service account project-Tutorial service account key" --output signme.txt.sig
   

Step 8: View signing statistics and event Event Log¶

After the Signing Key is used, its activity appears in both the usage counts and the Event Log.

In the Code Sign Manager - SaaS UI, return to the Signing Keys page to confirm that the key now shows signing activity.

Administrators can view detailed events by opening the Event Log under Settings > Event Log and filtering for Signing succeeded events.

Conclusion¶

You have successfully signed a file using Code Sign Manager - SaaS. The private key used for signing was generated and stored securely on a remote HSM and never had to be present on the signing machine.

What's next¶

• Continue creating Projects and Signing Keys as needed for your use cases.
• Review the CLI documentation to learn more about all available options.
• Explore sample integrations for common code signing applications.