Issuer configuration¶

The Issuer configuration consists of two parts: the security configuration, which is centrally managed in TLS Protect Datacenter by the security team, and the local configuration, which is managed per Issuer instance by Kubernetes platform administrators.

• Local configuration:

  The local configuration contains information on how Issuer will connect to TLS Protect Datacenter and retrieve the security configuration, along with the services that Issuer exposes for clients to request certificates. This configuration is managed by the teams responsible for the environment where Issuer is deployed, such as the Kubernetes platform team. For more information, see the Issuer configuration YAML reference page.

• Security configuration:

  The security configuration is centrally managed in TLS Protect Datacenter and strictly controlled by the security team. The Issuer security configuration cannot be overridden by configurations set locally on the Issuer instance.

Managing Issuer security configuration¶

To manage the Issuer security configuration, you can use the CLI tool for CyberArk Certificate Manager, also known as venctl. This CLI utility allows you to generate a sample security configuration and push or pull security configurations to TLS Protect Datacenter. In TLS Protect Datacenter, the created security configurations exist as objects within a policy folder, but without the ability to view or modify their content. To do this, you need to use the CLI tool for CyberArk Certificate Manager.

To learn more about the CLI tool for CyberArk Certificate Manager and how to install it, see the CLI tool for CyberArk Certificate Manager overview page.

Usually, a member of the security team performs the following operations to create a security configuration, which can then be consumed by the Issuer instance.

1. Generate a sample security configuration.

2. Modify the configuration according to corporate security policies.

3. Validate the modified configuration.

4. Push the configuration to TLS Protect Datacenter.

5. Prepare the information you need to share with your platform team.

Once the security configuration is pushed to TLS Protect Datacenter, information about it and the authentication details can be shared with the team responsible for the environment where Issuer will be deployed, such as the Kubernetes platform team.

Step 1: Generate a sample security configuration¶

CLI tool for CyberArk Certificate Manager includes the subcommand venctl configuration firefly generate, which allows users to generate a sample security configuration. By default, the output is displayed in the terminal. You can use the --output-file flag to redirect the output to a file.

To generate and save the security configuration to a file, run:

venctl configuration firefly generate --output-file "security-config.yaml"

By default, the generated security configuration contains sample information about the most commonly used configuration options. Using the --profile flag, you can choose profiles that include configuration options for advanced use cases, such as when an HSM is required to protect the private key for the subordinate CA certificate that will be used by Issuer.

The next step is to modify it according to the corporate security policies.

Step 2: Modify the security configuration¶

The security configuration is stored in YAML format. To modify it, use your preferred text editor.

To learn more about the data in the security configuration file, see security configuration nodes.

Step 3: Validate the modified security configuration¶

Once the security configuration file has been modified according to your corporate policies, you can use the CLI tool for CyberArk Certificate Manager to validate it. Validation can be performed using the push subcommand with the--dry-run flag.

There are two validation options: basic and extended.

Basic validation¶

Basic (also known as local) validation requires access to TLS Protect Datacenter and performs the following checks:

• The file has valid YAML syntax.

• The configuration options have values that are within the expected boundaries.

To perform basic validation of an Issuer security configuration file without pushing it, run:

venctl configuration firefly push --dry-run --file "security-config.yaml"

Extended validation¶

Extended validation requires access to TLS Protect Datacenter. In addition to the basic validation, it ensures that the security configuration includes a policy folder (defined as subCaProvider.tppPolicyFolderDN), which is properly configured for the issuance of the subordinate CA certificate. The policy folder must comply with the requirements defined in Policy folder for the subordinate CA certificates used by Issuer. Note that this validation does not include the validation of the permissions for the identities configured in the policy.

To perform extended validation that includes remote checks, the API URL of the TLS Protect Datacenter must be specified. Run:

venctl configuration firefly push --dry-run --file "security-config.yaml" --api-url "https://tpp.example.com/"

You will be prompted for credentials to access TLS Protect Datacenter.

Step 4: Push the configuration¶

Once the security configuration is modified and validated, it can be pushed to TLS Protect Datacenter.

To push an Issuer security configuration to a TLS Protect Datacenter, run:

venctl configuration firefly push "firefly\\security-config" --file "security-config.yaml" --api-url "https://tpp.example.com/"

You will be prompted for credentials to access TLS Protect Datacenter.

Note that you can use the push subcommand to overwrite an existing security configuration that is already stored in TLS Protect Datacenter.

(Optional) Pull a configuration¶

If you want to validate that the security configuration is properly stored in TLS Protect Datacenter, you can use the venctl configuration firefly pull subcommand.

To pull an Issuer security configuration from a TLS Protect Datacenter, run:

venctl configuration firefly pull "firefly\\security-config" --output-file "security-config.yaml" --api-url "https://tpp.example.com/"

Step 5: Prepare the information you need to share with your platform team¶

You need to share the following information with the platform team responsible for the environment where Issuer will be deployed, such as the Kubernetes platform team.

• TLS Protect Datacenter URL: This is the base URL of the TLS Protect Datacenter instance that you have configured to manage Issuer.

• Authentication type: This is the authentication method that Issuer will use to authenticate with TLS Protect Datacenter. In this example, it is OIDC authentication. For username & password authentication, you will also need to share the credentials.

• Naming pattern for the Issuer instances: The Issuer instances have names that are included in the common name of the required subordinate CA certificates. This naming pattern can be used to distinguish between different Issuer instances.

• Name of the Issuer security configuration: This is the name or the full DN of the security configuration that was pushed in the previous section to TLS Protect Datacenter. In our example, this is firefly\security-config.

• Usage of HSM: This indicates whether a Hardware Security Module (HSM) will be required to generate and store the private key for the subordinate CA certificate of Issuer.

What's next?¶

• Deploy Issuer in Kubernetes.