Skip to content

Authenticating to TLS Protect Datacenter

In order for Firefly to operate with TLS Protect Datacenter, 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 Firefly, and set up API integration that this user identity can use.

To simplify this example, you can create a local user identity in TLS Protect Datacenter for Firefly, but other identity providers can also be used. For more information about user identities, see Managing local identities directly in Trust Protection Platform.

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 TLS Protect Datacenter is used, meaning the password set for the newly created user is not used by Firefly.

For more information about other authentication methods for Firefly, see Firefly authentication methods with TLS Protect Datacenter.

The administrator responsible for managing the Firefly’s security configuration will have the username security-admin and will be a member of the security-team group. To manage the Firefly security configuration, the administrator must use the Venafi CLI, also known as venctl. This utility enables administrators to generate sample security configurations and push or pull them to the TLS Protect Datacenter. To learn more about the Venafi CLI and how to install it, see the Venafi CLI overview page.

API integration configuration for pre-25.1 TLS Protect Datacenter installations

Every API client needs to register with TLS Protect Datacenter. Firefly and Venafi CLI are not exceptions.

For TLS Protect Datacenter 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 Firefly and Venafi CLI instances to operate with your TLS Protect Datacenter system.

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

Import the Venafi CLI API integration configuration

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

The configuration and security:delete,manage scopes are required by the Venafi CLI to manage the Firefly security configurations in TLS Protect Datacenter. Additionally, the certificate:manage scope is necessary for the validation performed by Venafi CLI before pushing the Firefly's configuration in TLS Protect Datacenter. 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 Venafi CLI to manage the security configuration of Firefly stored in TLS Protect Datacenter. In our example this is the security-team group.

Import the Firefly 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 Firefly 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 Firefly to retrieve the security configuration from TLS Protect Datacenter.

Once successfully imported, you must configure the user identities that can use this API integration. In this case, this is the identity which Firefly will use to pull the security configuration from TLS Protect Datacenter. 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 - Firefly and Venafi CLI -according to your corporate policies. Firefly and Venafi CLI authenticate with the TLS Protect Datacenter to request access grants, which include validity, access and refresh tokens. Once a grant expires, clients must reauthenticate.

To adjust the access settings:

  1. In the TLS Protect Datacenter UI, click the icon and then Platform > API > Integrations.
  2. Locate the integration you want to update using searches or filtering, if desired.
  3. Click the name of the integration you want to modify.
  4. Update the fields on the tabs as required, then click Save.

Firefly access settings

Firefly supports both JSON Web Token (JWT) authentication and username & password authentication. In both cases, Firefly 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.

Venafi CLI access settings

Venafi CLI supports authentication to the TLS Protect Datacenter using access tokens or username & password. When username & password are used, Venafi CLI requests a new grant with an access token each time an operation needs to be performed in the TLS Protect Datacenter. 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 Venafi CLI authenticate with a username and password, the expiration can be set to just a few minutes.

Firefly authentication

In this scenario, authentication between Firefly and the TLS Protect Datacenter will use OIDC, where the Kubernetes cluster hosting Firefly issues short-lived JSON web token (JWT) credentials, which are then validated by the TLS Protect Datacenter.

The next step in connecting Firefly to TLS Protect Datacenter is to enable JSON web token (JWT) authentication:

  1. In the TLS Protect Datacenter UI, click the icon and then Platform > API > Integrations.
  2. Select the JSON web token (JWT) checkbox.

Create JWT mappings

Firefly authenticates to the TLS Protect Datacenter by using a signed JWT token associated with its Kubernetes ServiceAccount. In this step, you will configure the TLS Protect Datacenter to map Kubernetes ServiceAccount tokens to a TLS Protect Datacenter user account.

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

Additionally, you will need to ask your Kubernetes platform team for the name and namespace of the Firefly ServiceAccount. This information will be used to configure the TLS Protect Datacenter 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 TLS Protect Datacenter 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 Firefly Network requirements for the TLS Protect Datacenter.

  1. In the TLS Protect Datacenter 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.

  1. In the Venafi Configuration Console:

  2. Navigate to Access Management and select JWT Mapping.

  3. Click on the Add New Mapping….
  4. Enter a Name.
  5. Enter Issuer URI. In this example, it is https://kubernetes.cluster.example.com/, and click the Verify button to confirm that the TLS Protect Datacenter can access the Issuer URI.
  6. Set the Audience field to aud and the Must match field to tpp. You need to set this same value when you configure the Venafi Connection.
  7. Set the Subject Field to sub. The value of Match must be the name of the Kubernetes service account used in the Venafi Connection. The format is system:serviceaccount:<namespace>:<service-account-name>. In this example, it is system:serviceaccount:venafi:prod-firefly.

  8. Select the user identity that will be used by Firefly in the Map To field. In this example, it is firefly.

    Firefly JWT mapping

What's next?