Local configuration reference

Introduction

In order for CyberArk Workload Identity Manager (formerly known as Firefly) to start it must be given a config.yaml file that provides it with settings that specify how it will behave.

Operational Modes

Name	Description
Developer	An unmanaged and not-for-production mode that is well-suited for development and evaluation purposes. Developer Mode offers the same deployment and client experience but is untrusted and insecure by design. Workload Identity Manager Developer Mode is free to use and not accompanied by any support from CyberArk.
SaaS Control Plane	A secure, production-ready mode that is managed by the CyberArk Machine Identity Security Control Plane. SaaS Control Plane Mode allows security teams to be responsible for machine identity policies, distribute enterprise trust, and have visibility into Workload Identity Manager issuance activity while allowing platform engineers and developers to be responsible for Workload Identity Manager deployments and their availability to clients. Workload Identity Manager SaaS Control Plane Mode is as an add-on to CyberArk Certificate Manager. Click here to sign-up for a free trial.
Self-Hosted Control Plane	A secure, production-ready mode that is managed by the CyberArk Machine Identity Security Control Plane. Like SaaS Control Plane Mode, Self-Hosted Control Plane Mode allows security teams to be responsible for machine identity policies and distribute enterprise trust while allowing platform engineers and developers to be responsible for Workload Identity Manager deployments and their availability to clients. This mode is intended for customers who have CyberArk Certificate Manager, Self-Hosted (formerly known as Venafi TLS Protect DataCenter, and as Venafi Trust Protection Platform) and who are unable to benefit from the SaaS Control Plane. Workload Identity Manager Self-Hosted Control Plane Mode is as an add-on to CyberArk Certificate Manager.

Bootstrap Section

Workload Identity Manager can obtain its CA certificate four ways, two that are production-ready and two that are not. SaaS Control Plane Mode (vaas) and Self-Hosted Control Plane Mode (tpp) support enterprise trusted certificates and governance by security teams. Developer Mode can either generate an untrusted CA (selfSigned) or load an insecure CA from files (file).

bootstrap:
  vaas:
    auth:
      privateKeyFile: /etc/firefly/svc-acct.key
      clientID: aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee
    csr:
      instanceNaming: My Enterprise Firefly
    pkcs11:
      clientLibraryPath: /path/to/hsm-client-pkcs11-lib.so
    url: https://api.venafi.cloud

bootstrap:
  tpp:
    configurationDN: \VED\Policy\Firefly\Configuration
    connection:
      inline:
        url: https://tpp.example.com
        accessToken:
        - file:
            path: /etc/firefly/tpp-creds.yaml
            fields: [ "username", "password" ]
        - tppOAuth:
            authInputType: UsernamePassword
            clientId: firefly
#     reference:
#       name: tpp-connection
#       namespace: venafi
    csr:
      instanceNaming: My Enterprise Firefly
    pkcs11:
      clientLibraryPath: /path/to/hsm-client-pkcs11-lib.so

bootstrap:
  selfSigned:
    csr:
      commonName: My Firefly
      subject:
        organizations:
        - Example, Inc.
      privateKey:
        algorithm: ECDSA
        size: 256
      duration: 720h
    trustRootDirectory: /etc/firefly/trust

bootstrap:
  file:
    privateKeyFile: /etc/firefly/ca.key
    certificateFile: /etc/firefly/ca.crt

Parameter details for CA issued via SaaS Control Plane

Parameter	Description
`auth`
`privateKeyFile`	(Required) The full path within the Workload Identity Manager container to the file that contains the private key corresponding to the public key provided to the Control Plane for the service account.
`clientID`	(Required) The Client ID of the service account obtained from the Control Plane.
`csr`
`instanceNaming`	(Required) A name for the Workload Identity Manager instance (should be unique). This, plus a suffix defined by the Control Plane SubCA provider, will be the common name of the Workload Identity Manager CA certificate. Supports environment variable substitution using `{ENV_VAR_NAME}` syntax. If the specified environment variable is set (has a value), that value will be substituted.
`pkcs11`
`clientLibraryPath`	The full path of the HSM client PKCS#11 library file Firefly will use when generating its key pair for signing certificates. This requires the firefly-pkcs11 binary. It also requires that the SubCA Provider of the configuration associated with the service account is set to "Require HSM" and that it specifies the Slot and PIN required for Firefly to access the HSM.
`url`	The base URL of the Control Plane with which the Workload Identity Manager instance will interact. Defaults to `https://api.venafi.cloud` (United States) if not specified. Set to `https://api.venafi.eu` (European Union), `https://api.uk.venafi.cloud` (United Kingdom), or `https://api.au.venafi.cloud` (Australia) for tenants hosted in other regions.

Parameter details for CA issued via Self-Hosted Control Plane

Parameter	Description
`configurationDN`	The distinguished name (DN) of the Generic Credential object in the Control Plane that contains the security configuration for Workload Identity Manager to bootstrap.
`connection`
`inline`	(Required if `reference` is not specified)
`accessToken`
`file`
`path`	The full path to the YAML file containing the username/password the Workload Identity Manager instance will use to get an access token from the Control Plane.
`fields`	Value must be `[ "username", "password" ]` for username/password authentication.
`tppOAuth`
`authInputType`	Value must be `UsernamePassword` for username/password authentication.
`clientId`	The Client ID of the API integration obtained from the Control Plane.
`url`	The base URL of the Control Plane with which the Workload Identity Manager instance will interact.
`reference`	(Required if `inline` is not specified)
`name`	The name of the VenafiConnection Kubernetes resource the Workload Identity Manager pod will use to connect with the Control Plane.
`namespace`	The namespace in which the VenafiConnection Kubernetes resource resides.
`csr`
`instanceNaming`	(Required) A name for the Workload Identity Manager instance (should be unique). This, plus a suffix defined by the Control Plane SubCA provider, will be the common name of the Workload Identity Manager CA certificate. Supports environment variable substitution using `{ENV_VAR_NAME}` syntax. If the specified environment variable is set (has a value), that value will be substituted.
`pkcs11`
`clientLibraryPath`	The full path of the HSM client PKCS#11 library file Workload Identity Manager will use when generating its key pair for signing certificates. This requires the firefly-pkcs11 binary. It also requires that the SubCA Provider of the configuration associated with the service account is set to "Require HSM" and that it specifies the Slot and PIN required for Workload Identity Manager to access the HSM.

Parameter details for Self-Signed CA

Parameter	Description
`csr`
`commonName`	(Required) The common name of the Workload Identity Manager CA certificate.
`subject`
`organizations`	One or more organization (O) values to appear in the Workload Identity Manager CA certificate.
`organizationalUnits`	One or more organizational unit (OU) values to appear in the Workload Identity Manager CA certificate.
`localities`	One or more locality/city (L) values to appear in the Workload Identity Manager CA certificate.
`provinces`	One or more state/province (ST) values to appear in the Workload Identity Manager CA certificate.
`countries`	One or more country (C) values to appear in the Workload Identity Manager CA certificate.
`privateKey`
`algorithm`	Either "RSA" or "ECDSA" representing the algorithm for the keypair Workload Identity Manager will generate for its CA certificate.
`size`	One of the following: 2048, 3072, 4096, 256 (for EC_P256), 384 (for EC_P384), or 521 (for EC_P521).
`duration`	Validity of the Workload Identity Manager CA certificate expressed in hours (e.g., 90 day validity is "2160h").
`trustRootDirectory`	A writeable directory within the Workload Identity Manager container where it will create a file containing the root CA certificate it generates which can be used to enable trust for certificates it issues to clients.

Parameter details for CA from Certificate and Private Key files

Parameter	Description
`file`
`privateKeyFile`	(Required) The full path within the Workload Identity Manager container to the file that contains a pre-generated CA private key.
`certificateFile`	(Required) The full path within the Workload Identity Manager container to the file that contains a pre-generated CA certificate.

Signer Section

The signer section must be included for Developer Mode. For either Control Plane Mode, inMemory: true is the required behavior. This means the CA signing key always resides in memory, is never swapped to disk, and only exists for the lifespan of the Workload Identity Manager instance unless Workload Identity Manager is configured to require an HSM. In that case, the signing key always resides in the HSM.

signer:
  inMemory: true

Server Section

The server section specifies which, if any, of the Workload Identity Manager application programming interfaces (APIs) are available for clients to request certificates. These server interfaces include: grpc and rest. Each TLS interface requires a listening port to be specified as well as either a dnsName or ipAddress for Workload Identity Manager to use when self-issuing server certificates for the interface.

Logically at least one API should be specified in the config.yaml or the Workload Identity Manager cannot service any clients (unless Workload Identity Manager is only acting as a cert-manager issuer, see Controller Section).

server:
  grpc:
    port: 8001
    tls:
      dnsNames:
      - firefly.example.com
      ipAddress: 10.20.30.40
  rest:
    port: 8002
    tls:
      dnsNames:
      - firefly.example.com
      ipAddress: 10.20.30.40

Additionally, for Developer Mode the server section must also specify how Workload Identity Manager will authenticate and authorize its clients. Authentication can be either oidc or jwks. Authorization specifies the configuration name that must be in the venafi-firefly.configuration custom claim of JWTs clients present to Workload Identity Manager when requesting a certificate. For OIDC, you should be able to append .well-known/openid-configuration to the baseUrl and access the OIDC Discovery data for the Identity Provider (e.g., https://idp.example.com/.well-known/openid-configuration).

  authentication:
    jwt:
      oidc:
        baseUrl: https://idp.example.com/
        audience: api://firefly
  authorization:
    configuration: Demo Config

  authentication:
    jwt:
      jwks:
        urls:
        - https://idp.example.com/.well-known/jwks.json
  authorization:
    configuration: Demo Config

Workload Identity Manager's gRPC and REST endpoints can be made available over Unix Domain Sockets (UDS) instead of TCP by specifying a socketPath whose value represents the local socket "file" that Workload Identity Manager will create at startup. UDS is intended for deployments where Workload Identity Manager shares a single pod with an application like SPIRE so it shouldn't need network access to request certificates from it. UDS is preferred over TCP in such cases for its performance and simplicity.

server:
  grpc:
    uds:
      socketPath: /opt/firefly/grpc.sock
  rest:
    uds:
      socketPath: /opt/firefly/rest.sock

Implementing Workload Identity Manager's default custom authorization claims can pose a challenge for some organizations and their IdPs. In version 1.4.1, Workload Identity Manager added the option to specify aliases for the "venafi-firefly" claims in the config.yaml when running in Developer Mode (and configuration and security.yaml when running in SaaS Control Plane Mode and Self-Hosted Control Plane Mode, respectively). In the following example, JWTs presented to Workload Identity Manager by API clients must have a "role" claim with a value of "Demo Config" and a "groups" claim with a value that specifies the policies for which the client is allowed to request certificates (for example, "Demo Policy" if you were using the example in the Policies Section below).

  authorization:
    configuration: Demo Config
    customClaimsAliases:
      venafi-firefly.configuration: role
      venafi-firefly.allowedPolicies: groups
      venafi-firefly.allowAllPolicies: notUsed

Identity Documents Section

Workload Identity Manager supports a special form of authentication based on Instance Identity Documents (IIDs). When enabled, cloud workloads can request certificates using IIDs issued and signed by a public cloud provider without any other authentication. When Workload Identity Manager receives such a request, it verifies the signature of the IID and, if valid, issues a policy compliant certificate (and private key) with the instance ID as the Common Name of the certificate. In Control Plane Mode, Workload Identity Manager also verifies that the IID belongs to an approved AWS account, Azure subscription, or Google project and optionally that it is located in an approved geographic region (AWS and Google).

When present, the identityDocument section must include server which specifies the port on which the IID REST service will listen as well as either a dnsName or ipAddress for Workload Identity Manager to use when self-issuing server certificates for the interface.

identityDocument:
  server:
    port: 8004
    tls:
      dnsNames:
      - firefly.example.com
      ipAddress: 10.20.30.40

Additionally, for Developer Mode the identityDocument section must also specify the cloud providers for which Workload Identity Manager will accept IIDs in exchange for a certificate. Amazon Web Services (aws), Microsoft Azure (azure), and Google Cloud (google) are currently supported. cloudProviders must be omitted for Control Plane Mode because the Control Plane and the configuration it provides dictates the whether any of the cloud providers are allowed.

  cloudProviders:
    aws:
      enabled: true
    azure:
      enabled: true
    google:
      enabled: true

Policies Section

The policies section defines the policies for which Workload Identity Manager clients can request certificates. At least one policy is required for Developer Mode.

When Workload Identity Manager runs in either Control Plane Mode, no policies are permitted in the config.yaml because policies are managed by and retrieved from the CyberArk Machine Identity Security Control Plane when Workload Identity Manager starts up. Unlike locally defined policies of Developer Mode, policies managed by the SaaS Control Plane and Self-Hosted Control Plane have rich support for constraining certificate Subject and Subject Alternative Names.

policies:
- name: Demo Policy
  keyUsages: 
  - digitalSignature
  - keyEncipherment
  extendedKeyUsages:
  - SERVER_AUTH
  - CLIENT_AUTH
  keyAlgorithm:
    allowedValues:
    - RSA_2048
    - EC_P256
    defaultValue: EC_P256
  validityPeriod: P7D

Parameter	Description
`name`	(Required) The policy name a client can specify when requesting a certificate. The policy name must also be in the `venafi-firefly.allowedPolicies` custom claim of JWTs clients present to Workload Identity Manager when requesting a certificate unless the `venafi-firefly.allowAllPolicies` claim is true.
`keyUsages`	(Required) At least one of the following Key Usage values. These Key Usages will be present in any certificate issued using this policy: digitalSignature, contentCommitment, nonRepudiation, keyEncipherment, dataEncipherment, keyAgreement, keyCertSign, cRLSign, encipherOnly, decipherOnly
`extendedKeyUsages`	(Required) At least one of the following Extended Key Usage values. These Extended Key Usages will be present in any certificate issued using this policy: SERVER_AUTH, CLIENT_AUTH, CODE_SIGNING, EMAIL_PROTECTION, IPSEC_ENDSYSTEM, IPSEC_TUNNEL, IPSEC_USER, TIME_STAMPING, OCSP_SIGNING
`keyAlgorithm`
`allowedValues`	(Required) At least one of the following key types: RSA_2048, RSA_3072, RSA_4096, EC_P256, EC_P384, EC_P521, EC_ED25519
`defaultValue`	(Required) The key type that will be used when a client does not specify a key type in their request.
`validityPeriod`	(Required) An ISO 8601 duration that specifies the maximum validity period a client can request and also the default validity period if they do not specify one in their request.

Controller Section

The controller section is used to launch Workload Identity Manager as a cert-manager issuer for a Kubernetes cluster.

controller:
  kubeconfigFile: /etc/firefly/kubeconfig.yaml
  leaderElectionNamespace: kube-system
  cert-manager:
    groupName: firefly.venafi.com
    checkApproval: true
    caRootChainPopulation: false

Parameter	Description
`kubeConfigFile`	Required when Workload Identity Manager is not running in the same cluster as cert-manager. Provides cluster details and credentials necessary for Workload Identity Manager to interact with cert-manager.
`leaderElectionNamespace`	Namespace that will hold the leader election lease for the Workload Identity Manager replica group.
`cert-manager`
`groupName`	The name of the group to which the Workload Identity Manager Issuer or Cluster Issuer belongs and that `CertificateRequest` resources will reference.
`checkApproval`	Boolean indicating whether certificate requests will wait for approval before being evaluated by Workload Identity Manager.
`caRootChainPopulation`	Boolean indicating whether to include the trust anchor (root CA) certificate in the `status.ca` field of the CertificateRequest resource.

Introduction​

Operational Modes​

Bootstrap Section​

Signer Section​

Server Section​

Identity Documents Section​

Policies Section​

Controller Section​