Creating service accounts dynamically¶

In automated systems, such as CI/CD pipelines, you may need to generate service accounts dynamically for the Discovery Agent deployed on your Kubernetes cluster.

To do this, you must first create a master service account with the svcaccount-write scope using the CLI tool for CyberArk Certificate Manager. A master service account enables API clients and the CLI tool for CyberArk Certificate Manager to then create other service accounts with different scopes as required.

Follow the steps below to create a master service account, and then use it to create another service account dynamically.

Step 1: Create a master service account with the svcaccount-write scope¶

1. If you haven't done so yet, download and install the CLI tool for CyberArk Certificate Manager.

2. Use the following command to create a master service account and store the service account credentials in a master-sa.json file.

   venctl iam service-account custom-integration create --api-key XYZ --name "my-master-sa" --scopes svcaccount-write --output-file master-sa.json
   

   Info

   For instructions on how to get hold of your API key, see Obtaining your API key.

Step 2: Use the master service account to create other service accounts¶

Once you have a master service account created using the method shown above, you can then create other accounts by passing the master service account credentials to the --auth.key-file flag in the relevant CLI tool for CyberArk Certificate Manager venctl iam service-account create command, as in the following example:

venctl iam service-account agent create --name "my-agent-sa" --output secret --output-file agent-credentials.json --owning-team XYZ --auth.key-file master-sa.json

Update a service account¶

If you have a service account that has expired, or is about to expire, you can update it.

1. In order for a service account to be updated, it must have been created by a master account (see the section above).

   Note

   There can be only one "parent" for each service account, and one master service account cannot become the parent of a child service account it did not create. If the master service account isn't the "parent", you will see the following error message:

   The service account used to authenticate is not the parent of the service account that
   you are trying to update. Only its parent service account can be used to update it.
   

2. You can then use the venctl iam service-accounts update command to update the account. You can do this either by extending the validity period of account or by replacing the public key:

   Which approach should I use?

   Extending service account validity is applicable only to service accounts that expire. If a service account has no expiration, then a validity-extension operation is not relevant.

   Replacing the public key is applicable only to service accounts that use the key-pair authentication method. If the service account is configured for a different authentication method, public key rotation does not apply.

   Extending account validityReplacing the public key

   There are two ways to do this: using a JSON file that contains the client_id and private_key fields, or by using a PEM-encoded private key file.

   Once you have a master service account created, you can then extend the lifespan of its pre-existing child service accounts by passing the master service account credentials to the --auth.key-file flag in the relevant venctl iam service-accounts update command and adding the --validity flag, as in the following examples:

   venctl iam service-accounts update SERVICE_ACCOUNT_ID \
     --auth.key-file agent-credentials.json \
     --validity 365
   

   Sample JSON file:

   agent-credentials.json

   {
       "client_id": "MASTER_SERVICE_ACCOUNT_ID",
       "private_key": "-----BEGIN PRIVATE KEY-----\n< some private key string >\n-----END PRIVATE KEY-----\n"
   }
   

   Alternatively, you can also use a private key file:

   venctl iam service-accounts update SERVICE_ACCOUNT_ID \
     --auth.key-file master.key \
     --auth.client-id MASTER_SERVICE_ACCOUNT_ID \
     --validity 365
   

   Key-pair public key rotation is disruptive and must be planned

   Rotating (replacing) the public key for a service account configured for key-pair authentication is an inherently disruptive change.

   After the update, clients using the old private key will fail authentication until they are updated. Plan this activity carefully (typically as part of a coordinated rollout or maintenance window).

   If you want to avoid client disruption, consider using the Workloads Identity Federation authentication method instead of key-pair authentication, as it removes the dependency on a static client-side private key.

   1. Generate a new key pair. Your new private key should be stored securely and access to it limited.

   2. Roll out the new private key to the client that authenticates with this service account (for example, Discovery Agent, Workload Identity Manager, etc.).

      You must restart or reload clients/services for configuration changes to take effect.

   3. Update the service account with the new public key. You should perform this step only after confirming the new private key is deployed during a coordinated maintenance window:

      venctl iam service-accounts update SERVICE_ACCOUNT_ID \
         --auth.key-file master.key \
         --public-key-file new-pub-key.pem
      

   4. Finally, verify that the client can authenticate successfully by using health checks, logs, or functional tests. Investigate any failures — these typically indicate a client still using the old private key.