Authenticating to Certificate Manager - Self-Hosted¶

In order for CyberArk Workload Identity Manager (formerly known as Firefly) to operate with Certificate Manager - Self-Hosted, it needs to be represented as a user identity on the system. This identity can then authenticate to the system using different methods, such as JSON web token (JWT), or username and password. Before configuring the authentication method, you must create a user identity for Workload Identity Manager, and set up API integration that this user identity can use.

To simplify this example, you can create a local user identity in Certificate Manager - Self-Hosted for Workload Identity Manager, but other identity providers can also be used. For more information about user identities, see Managing local identities directly in Certificate Manager - Self-Hosted.

To create a new local user identity, follow the instructions outlined in Creating local user identities.

In the example here, a user identity with username firefly is created. Additionally, JSON Web Token (JWT) authentication to Certificate Manager - Self-Hosted is used, meaning the password set for the newly created user is not used by Workload Identity Manager.

For more information about other authentication methods for Workload Identity Manager, see Workload Identity Manager authentication methods with Certificate Manager - Self-Hosted.

The administrator responsible for managing the Workload Identity Manager’s security configuration will have the username security-admin and will be a member of the security-team group. To manage the Workload Identity Manager security configuration, the administrator must use the CLI tool for CyberArk Certificate Manager, also known as venctl. This utility enables administrators to generate sample security configurations and push or pull them to the Certificate Manager - Self-Hosted. 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.

API integration configuration for pre-25.1 Certificate Manager - Self-Hosted installations¶

Every API client needs to register with Certificate Manager - Self-Hosted. Workload Identity Manager and CLI tool for CyberArk Certificate Manager are not exceptions.

For Certificate Manager - Self-Hosted version 25.1 or later, this registration is already done by default, so this step can be skipped if you are using one of these versions. For previous versions, you need to register your Workload Identity Manager and CLI tool for CyberArk Certificate Manager instances to operate with your Certificate Manager - Self-Hosted system.

Follow the steps described in Integrating other systems with CyberArk products and import the two API integration configurations below.

Import the CLI tool for CyberArk Certificate Manager API integration configuration¶

{
  "id": "venctl",
  "name": "Venafi CLI",
  "vendor": "CyberArk Software Ltd.",
  "description": "CLI utility for managing Workload Identity Manager configurations",
  "scope": "configuration;security:delete,manage;certificate:manage"
}

The configuration and security:delete,manage scopes are required by the CLI tool for CyberArk Certificate Manager to manage the Workload Identity Manager security configurations in Certificate Manager - Self-Hosted. Additionally, the certificate:manage scope is necessary for the validation performed by CLI tool for CyberArk Certificate Manager before pushing the Workload Identity Manager's configuration in Certificate Manager - Self-Hosted. The validation involves ensuring that the policy folder intended for the issuance of the Subordinate CA certificate is correctly configured.

Once successfully imported, you must configure the user identities that can use this API integration. In this case, these are the administrators who will use the CLI tool for CyberArk Certificate Manager to manage the security configuration of Workload Identity Manager stored in Certificate Manager - Self-Hosted. In our example this is the security-team group.

Import the Workload Identity Manager API integration configuration¶

{
  "id": "firefly",
  "name": "Firefly",
  "vendor": "CyberArk Software Ltd.",
  "description": "Decentralized workload identity issuance governed by a control plane",
  "scope": "certificate:manage;security:manage"
}

The certificate:manage scope is required for Workload Identity Manager to enroll and renew the Sub-CA certificate, which is used to sign client-requested leaf certificates. Additionally, the security:manage scope is necessary for Workload Identity Manager to retrieve the security configuration from Certificate Manager - Self-Hosted.

Once successfully imported, you must configure the user identities that can use this API integration. In this case, this is the identity which Workload Identity Manager will use to pull the security configuration from Certificate Manager - Self-Hosted. This is the firefly user identity created in the previous step.

Adjust the access settings¶

It is recommended to adjust the access settings for both integrations - Workload Identity Manager and CLI tool for CyberArk Certificate Manager - according to your corporate policies. Workload Identity Manager and CLI tool for CyberArk Certificate Manager authenticate with the Certificate Manager - Self-Hosted to request access grants, which include validity, access and refresh tokens. Once a grant expires, clients must reauthenticate.

To adjust the access settings:

In the Certificate Manager - Self-Hosted UI, click the icon and then Platform > API > Integrations.
Locate the integration you want to update using searches or filtering, if desired.
Click the name of the integration you want to modify.
Update the fields on the tabs as required, then click Save.

Workload Identity Manager access settings¶

Workload Identity Manager supports both JSON Web Token (JWT) authentication and username & password authentication. In both cases, Workload Identity Manager requests a new grant whenever the access token becomes invalid, as renewing the access token using the refresh token is not supported. Therefore, we recommend the following configuration:

Disable the Use global default option.
Disable the Token refresh option.
Set the access token and grants to expire in 15 minutes.

CLI tool for CyberArk Certificate Manager access settings¶

The CLI tool for CyberArk Certificate Manager supports authentication to the Certificate Manager - Self-Hosted using access tokens or username & password. When username & password are used, the CLI tool for CyberArk Certificate Manager requests a new grant with an access token each time an operation needs to be performed in the Certificate Manager - Self-Hosted. At the end of the command execution, the access token is revoked. Therefore, we recommend the following configuration:

Disable the Use global default option.
Disable the Token refresh option.
Adjust the access token and grant expiration according to your security policies. If administrators using the CLI tool for CyberArk Certificate Manager authenticate with a username and password, the expiration can be set to just a few minutes.

Workload Identity Manager authentication¶

In this scenario, authentication between Workload Identity Manager and the Certificate Manager - Self-Hosted will use OIDC, where the Kubernetes cluster hosting Workload Identity Manager issues short-lived JSON web token (JWT) credentials, which are then validated by the Certificate Manager - Self-Hosted.

The next step in connecting Workload Identity Manager to Certificate Manager - Self-Hosted is to enable JSON web token (JWT) authentication:

In the Certificate Manager - Self-Hosted UI, click the icon and then Platform > API > Integrations.
Select the JSON web token (JWT) checkbox.

Create JWT mappings¶

Workload Identity Manager authenticates to the Certificate Manager - Self-Hosted by using a signed JWT token associated with its Kubernetes ServiceAccount. In this step, you will configure the Certificate Manager - Self-Hosted to map Kubernetes ServiceAccount tokens to a Certificate Manager - Self-Hosted user account.

You will need to request the OIDC discovery document URL from your Kubernetes platform team for the cluster where Workload Identity Manager will be deployed.

Additionally, you will need to ask your Kubernetes platform team for the name and namespace of the Workload Identity Manager ServiceAccount. This information will be used to configure the Certificate Manager - Self-Hosted JWT mapping in the following format: system:serviceaccount:<namespace>:<service-account-name>. For example, if the namespace is venafi and the service account name is prod-firefly, you would enter system:serviceaccount:venafi:prod-firefly.

Kubernetes platform administrators can find the issuer URL by executing the command below:

kubectl get --raw /.well-known/openid-configuration | jq .issuer -r
  https://kubernetes.cluster.example.com

In this scenario, the Issuer URI is https://kubernetes.cluster.example.com.

The Issuer URI must be accessible from the Certificate Manager - Self-Hosted instance. To validate this, you can open a browser and append /.well-known/openid-configuration to the end of the Issuer URI. In our scenario, this results in https://kubernetes.cluster.example.com/.well-known/openid-configuration. The browser should return a successful JSON response containing information about the issuer. If this is not the case, see Workload Identity Manager Network requirements for the Certificate Manager - Self-Hosted.

In the Certificate Manager - Self-Hosted UI, go to Platform > API > Default Settings, and click the JSON web token (JWT) checkbox.

You need to create one JWT Mapping for each user account and per Kubernetes cluster. You need to know the issuer URL of the given Kubernetes cluster.

In the CyberArk Configuration Console:
Navigate to Access Management and select JWT Mapping.
Click on the Add New Mapping….
Enter a Name.
Enter Issuer URI. In this example, it is https://kubernetes.cluster.example.com/, and click the Verify button to confirm that the Certificate Manager - Self-Hosted can access the Issuer URI.
Set the Audience field to aud and the Must match field to tpp. You need to set this same value when you configure the Connection resource.
Set the Subject Field to sub. The value of Match must be the name of the Kubernetes service account used in the Connection resource. The format is system:serviceaccount:<namespace>:<service-account-name>. In this example, it is system:serviceaccount:venafi:prod-firefly.
Select the user identity that will be used by Workload Identity Manager in the Map To field. In this example, it is firefly.

What's next?¶

Create a CA template in Certificate Manager - Self-Hosted