Reference: Certificate Manager - Self-Hosted configuration¶

For more information about its use, see Push an Workload Identity Manager configuration to Certificate Manager - Self-Hosted.

The Workload Identity Manager security configuration enables security teams to define policies that align with corporate security requirements. These policies govern the SubCA certificate used to sign certificates requested by clients, the policies applied to the requested leaf certificates, as well as the authentication and authorization configuration for the client.

The Workload Identity Manager security configuration is structured in YAML format. A typical workflow begins with a sample configuration generated by the CLI tool for CyberArk Certificate Manager, which serves as a template. Security teams can then modify this template to align with corporate security requirements. The configuration can be validated for syntax errors and common misconfigurations before being imported into the Certificate Manager - Self-Hosted. Once imported, Workload Identity Manager instances can retrieve the configuration during startup to become operational.

Learn more about YAML

A YAML format primarily uses three node types:

Mappings (aka Maps or Dictionaries) The content of a mapping node is an unordered set of key/value node pairs, with the restriction that each of the keys is unique. YAML places no further restrictions on the nodes.
Sequences (aka Arrays or Lists) The content of a sequence node is an ordered series of zero or more nodes. In particular, a sequence may contain the same node more than once. It could even contain itself.
Literals (Strings, numbers, boolean, etc.) The content of a scalar node is an opaque datum that can be presented as a series of zero or more Unicode characters.

Important

The format of the configuration file below is not compatible with versions of the CLI tool for CyberArk Certificate Manager earlier than v1.22.0.

To upgrade your old configuration file to the new format, push it to Certificate Manager - Self-Hosted, and then pull the new configuration file from Certificate Manager - Self-Hosted.

Sample configuration file:

Issuer.yaml

subCaProvider:
  validityPeriod: P60D
  commonName: subca.example.com
  keyAlgorithm: RSA_4096
  tppPolicyFolderDN: "firefly\\SubCA"
clientAuthentication:
  audience: firefly.example.com
  clients:
  - issuer: https://example.com
    subjects:
    - sub-claim-value
    - system:serviceaccount:test-app-namespace:test-app-sa
    allowedPolicyIds:
    - Policy
  - issuer: "^https://.*\\.example\\.com$"
    jwksURI: https://example.com/.well-known/jwks.json
    subjects:
    - ^system:serviceaccount:test-app-namespace:.*$
    allowedPolicyIds:
    - Policy
  type: JWT_STANDARD_CLAIMS
policyDefinitions:
- name: Policy
  validityPeriod: P7D
  subject:
    commonName:
      type: REQUIRED
      allowedValues:
      - example.com
      minOccurrences: 1
      maxOccurrences: 1
    organization:
      type: OPTIONAL
      allowedValues:
      - ^(example|acme)$
      defaultValues:
      - example
      maxOccurrences: 1
  sans:
    dnsNames:
      type: REQUIRED
      allowedValues:
      - "^[A-Za-z0-9][A-Za-z0-9-]*\\.example\\.com$"
      minOccurrences: 1
      maxOccurrences: 10
  keyUsages:
  - digitalSignature
  - keyEncipherment
  - keyAgreement
  extendedKeyUsages:
  - CLIENT_AUTH
  - SERVER_AUTH
  keyAlgorithm:
    allowedValues:
    - RSA_2048
    - RSA_3072
    - RSA_4096
    - EC_P256
    - EC_P384
    - EC_P521
    - EC_ED25519
    defaultValue: EC_P256
allowedPolicies:
- Policy
minTlsVersion: TLS13
advancedSettings:
  enableIssuanceAuditLog: false
  includeRawCertDataInAuditLog: false

Security configuration nodes¶

Field	Type	Description	Required
`subCaProvider`		Configuration options for the subordinate certificate that Workload Identity Manager will use to sign leaf certificates. This includes details about the policy folder in the Certificate Manager - Self-Hosted for enrollment, subordinate certificate request information, and specifications for the HSM used to generate and store the private key material, if required.	Yes
`clientAuthentication`		Configuration options for authenticating clients requesting certificates over TCP-based protocols. This includes details about the OIDC Discovery URL and the JWKS URI.	No
`clientAuthorization`		Configuration options for authorizing clients requesting certificates over TCP-based protocols. This including details about the names of custom claims validated during client authorization.	No
`policies`		Configuration options for certificate issuance policies enforced by Workload Identity Manager when clients request certificates.	Yes
`minTlsVersion`	string	The minimum TLS protocol version that Workload Identity Manager will use when serving clients over HTTP-based protocols. Possible values: `TLS13` and `TLS12`.	No

`subCaProvider` node¶

Field	Type	Description	Valid options	Required Field
`validityPeriod`	string	The validity period for the requested subordinate certificate should be in ISO8601 period format. For example, for a 6-day validity period, you can use P6D, and for a 90-day period, you can use P90D.		Yes
`commonName`	string	The common name (CN) for the requested subordinate certificate will be used by Workload Identity Manager for signing.	max 64 chars	Yes
`organization`	string	The organization (O) for the requested subordinate certificate will be used by Workload Identity Manager for signing.	max 64 chars	No
`organizationalUnit`	string	The organization unit (OU) for the requested subordinate certificate will be used by Workload Identity Manager for signing.	max 64 chars	No
`locality`	string	The locality or city (L) for the requested subordinate certificate will be used by Workload Identity Manager for signing.	max 64 chars	No
`stateOrProvince`	string	The state or province (ST) for the requested subordinate certificate will be used by Workload Identity Manager for signing.	max 64 chars	No
`country`	string	The country (C) for the requested subordinate certificate will be used by Workload Identity Manager for signing.	max 64 chars	No
`keyAlgorithm`	string	The key algorithm and size used to generate the private key for the requested subordinate certificate will be used by Workload Identity Manager for signing.	RSA_2048, RSA_3072, RSA_4096, EC_P256, EC_P384, EC_P521 and EC_ED25519	Yes
`pkcs11`	PKCS11Configuration	Configuration options for using the PKCS11 interface, which is used to interact with HSM devices for generating and storing the private key material for the subordinate certificate.		No
`tppPolicyFolderDN`	string	The Distinguished Name (DN) of the policy folder in the TLS Protect Datacenter, which will be used when requesting a subordinate certificate. For example, `firefly\\SubCA` or `\\VED\\Policy\\firefly\\SubCA` Note that the `\\VED\\Policy\\` prefix can be omitted.	max 128 chars	Yes

Sample subCaProvidernode:

subCaProvider:
  validityPeriod: P60D
  commonName: My Common Name
  organization: My Organization
  organizationalUnit: My Organizational Unit
  locality: My Locality
  stateOrProvince: My State
  country: US
  keyAlgorithm: EC_P521
  tppPolicyFolderDN: "firefly\\SubCA"

`pkcs11` node¶

Field	Type	Description	Valid options	Required Field
`signingEnabled`	bool	Specify whether the use of an HSM is required for generating and storing the private key material for the subordinate certificate.	true or false	No
`partitionLabel`	String	Partition label on the HSM which will be used for generating and storing the private key material for the subordinate certificate.	max 32 chars	Yes, if signingEnabled is true
`partitionSerialNumber`	String	Partition Serial Number if the HSM has more than one partition with the same label.	String matching ^[A-Fa-fx0-9]{0,18}$	No
`pin`	String	PIN for the partition on the HSM.		Yes, if signingEnabled is true
`allowedClientLibraries`	String Sequence	SHA256 checksums of the client libraries that Workload Identity Manager is permitted to use when interacting with HSM devices via the PKCS11 interface. If not specified, any client library can be used.	String matching ^[a-fA-F0-9]{64}$	No

Sample pkcs11 node:

pkcs11:
  signingEnabled: true
  partitionLabel: partition1
  partitionSerialNumber: "1234567890234"
  pin: hsm-pin
  allowedClientLibraries:
  - 10a1eac382af5e320d24da6ac76996316df8d3a25b1bc92574cb71b20706efdf

`clientAuthentication` node¶

Workload Identity Manager will authenticate and authorize its clients when requesting certificates. Authentication methods include JWT_JWKS, JWT_OIDC, JWT_STANDARD_CLAIMS, or None. If you wish to prevent clients from requesting certificates via TCP-based protocols, simply omit this section. Note that clients will still be able to request certificates over non-TCP-based protocols, such as when Workload Identity Manager acts as a cert-manager issuer or through a Unix Domain Socket (UDS).

For custom claims JWKS authentication, set the fields below:

Field	Type	Description	Valid options	Required Field
`urls`	String Sequence	JWKS URIs that will be used by Workload Identity Manager to retrieve the JWKS containing the public keys used to validate the JWTs used by clients.	At least one URI, with a maximum length of 256 characters	Yes
`type`	String	The authentication type.	Must be JWT_JWKS	Yes

Sample clientAuthentication with JWKS:

clientAuthentication:
  urls:
  - https://idp.example.com/.well-known/jwks.json
  type: JWT_JWKS

For custom claims OIDC authentication, set the fields below:

Field	Type	Description	Valid options	Required Field
`baseUrl`	String	The base URL of the OIDC endpoint, for example, `https://idp.example.com`. This base URL is used to retrieve additional information required during client authentication. Note that the suffix `/.well-known/openid-configuration` should be omitted.	Valid URL; max 256 chars	Yes
`audience`	String	The value of the audience field that will be used when validating the JWTs used by clients.	max 256 chars	Yes
`type`	String	The authentication type.	Must be JWT_OIDC	Yes

Sample clientAuthentication with OIDC:

clientAuthentication:
  baseUrl: https://example.com/.well-known/openid-configuration
  audience: Workload Identity Manager
  type: JWT_OIDC

For standard claims authentication, set the fields below:

Field	Type	Description	Valid options	Required Field
`audience`	String	The value of the audience field that will be used when validating the JWTs used by clients.	Maximum 256 characters	Yes
`type`	String	The authentication type.	Use `JWT_STANDARD_CLAIMS`.	Yes
`clients[.].issuer`	String	The value to compare the `iss` claim against. A value starting with `^` is seen as a regular expression.		Yes
`clients[.].jwksUri`	String	The JWKS URI used by Workload Identity Manager to fetch public keys for verifying client JWTs.	The URI must start with `https://`.	No
`clients[.].subjects`	[]String	The value to compare the `sub` claim against. A value starting with `^` is seen as a regular expression.		Yes
`clients[.].allowedPolicyIds`	[]String	The set of policies the authenticated client is allowed to use.	The value must match one of the policy names.	Yes

Sample clientAuthentication with standard claims authentication:

clientAuthentication:
  audience: firefly.example.com
  clients:
  - issuer: https://example.com
    subjects:
    - sub-claim-value
    - system:serviceaccount:test-app-namespace:test-app-sa
    allowedPolicyIds:
    - Policy
  - issuer: "^https://.*\\.example\\.com$"
    jwksURI: https://example.com/.well-known/jwks.json
    subjects:
    - ^system:serviceaccount:test-app-namespace:.*$
    allowedPolicyIds:
    - Policy
  type: JWT_STANDARD_CLAIMS

clientAuthorization node¶

This section is only supported in combination with the JWT_JWKS or JWT_OIDC authentication option.

Field	Type	Description	Valid options	Required Field
`customClaimsAliases`	customClaimsAliasesSpec	You may want to configure your IdP to include custom claims in the JWTs issued for clients. In that case, you don't need to specify custom names for the claims. If you can't use the default claim names, you may be able to use claims that are already defined by your IdP. Specify the names of those claims, which Workload Identity Manager will use for authorizing clients via JWKS or OIDC Discovery.		No

customClaimsAliasesSpec node¶

Field	Type	Description	Valid options	Required Field
`configuration`	String	The name of the claim to be used instead of the default name, `venafi-firefly.configuration`, when validating the JWTs used by clients.	max 128 chars	No
`allowAllPolicies`	String	The name of the claim to be used instead of the default name, `venafi-firefly.allowAllPolicies`, when validating the JWTs used by clients.	max 128 chars	No
`allowedPolicies`	String	The name of the claim to be used instead of the default name, `venafi-firefly.allowedPolicies`, when validating the JWTs used by clients.	max 128 chars	No

Sample clientAuthorization node:

clientAuthorization:
  customClaimsAliases:
    configuration: claim.configuration
    allowAllPolicies: claim.allowAllPolicies
    allowedPolicies: claim.allowedPolicies

`policyDefinitions` node¶

Field	Type	Description	Valid options	Required Field
`name`		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.	max 64 chars	Yes
`validityPeriod`		The maximum validity period for the certificate requested by clients, as well as the default validity period if they do not specify one in their request. It is specified in ISO8601 period format. For example, for a 6-day validity period, use P6D, and for a 90-day period, use P90D.		Yes
`subject`				Yes
`sans`				Yes
`keyUsages`	String Sequence	The Key Usages that will be included in any certificate issued under this policy.	At least one of digitalSignature, contentCommitment, nonRepudiation, keyEncipherment, dataEncipherment, keyAgreement, keyCertSign, cRLSign, encipherOnly or decipherOnly	Yes
`extendedKeyUsages`	String Sequence	The Extended Key Usages that will be included in any certificate issued under this policy.	At least one of ANY, SERVER_AUTH, CLIENT_AUTH, CODE_SIGNING, EMAIL_PROTECTION, IPSEC_ENDSYSTEM, IPSEC_TUNNEL, IPSEC_USER, TIME_STAMPING or OCSP_SIGNING	Yes
`keyAlgorithm`	keyAlgorithmSpec	The allowed and default key algorithms that will be used for certificates issued under this policy.		Yes

`allowedPolicies` node¶

Field	Type	Description	Valid options	Required Field
allowedPolicies	string sequence	Issuance policies that clients are permitted to use when requesting certificates. This setting applies to local clients, clients authenticated with Instance Metadata, and clients authenticated using custom JWT claims. It does not apply to clients authenticated with registered JWT claims.	The values must match one of the policy names.

`subject` node¶

Field	Type	Required Field
`commonName`	attributeSpec
`organization`	attributeSpec
`organizationalUnit`	attributeSpec
`locality`	attributeSpec	Yes
`stateOrProvince`	attributeSpec
`country`	attributeSpec

`sans` node¶

Field	Type	Required Field
`dnsNames`	attributeSpec	Yes
`ipAddresses`	attributeSpec
`rfc822Names`	attributeSpec
`uniformResourceIdentifiers`	attributeSpec

`attributeSpec` node¶

Field	Type	Required Field
`type`	String	One of the IGNORED, FORBIDDEN, OPTIONAL, REQUIRED or LOCKED
`allowedValues`	String Sequence
`defaultValues`	String Sequence	Yes
`minOccurrences`	int
`maxOccurrences`	int

`keyAlgorithm` node¶

Field	Type	Description	Valid options	Required Field
`allowedValues`	String Sequence	The key algorithm and size that are allowed when clients specify them in their request or when a CSR is submitted.	At least one of RSA_2048, RSA_3072, RSA_4096, EC_P256, EC_P384, EC_P521, and EC_ED25519	Yes
`defaultValue`	String	The key algorithm and size that will be used when a client does not specify them in their request.	One of RSA_2048, RSA_3072, RSA_4096, EC_P256, EC_P384, EC_P521, and EC_ED25519.	Yes

Sample policies node:

policies:
- name: Policy
  validityPeriod: P7D
  subject:
    commonName:
      type: REQUIRED
      allowedValues:
      - example.com
      minOccurrences: 1
      maxOccurrences: 1
    organization:
      type: OPTIONAL
      allowedValues:
      - ^(example|acme)$
      defaultValues:
      - example
      maxOccurrences: 1
  sans:
    dnsNames:
      type: REQUIRED
      allowedValues:
      - "^[A-Za-z0-9][A-Za-z0-9-]*\\.example\\.com$"
      minOccurrences: 1
      maxOccurrences: 10
  keyUsages:
  - digitalSignature
  - keyEncipherment
  - keyAgreement
  extendedKeyUsages:
  - CLIENT_AUTH
  - SERVER_AUTH
  keyAlgorithm:
    allowedValues:
    - RSA_2048
    - RSA_3072
    - RSA_4096
    - EC_P256
    - EC_P384
    - EC_P521
    - EC_ED25519
    defaultValue: EC_P256

minTLSversion node¶

Parameter	Type	Description	Required?
`minTLSversion`	string	The minimum TLS protocol version that Workload Identity Manager will use when serving clients over HTTP-based protocols. Possible values: `TLS13` and `TLS12`.	No

advancedSettings node¶

Parameter	Type	Description	Required?
`enableIssuanceAuditLog`	boolean	Enable detailed certificate issuance logging.	No
`includeRawCertDataInAuditLog`	boolean	Include raw certificate data in the detailed certificate issuance log. Requires `enableIssuanceAuditLog` to be set to `true`.	No

Sample advancedSettings node:

advancedSettings:
  enableIssuanceAuditLog: true
  includeRawCertDataInAuditLog: true

Reference: Certificate Manager - Self-Hosted configuration¶

Security configuration nodes¶

subCaProvider node¶

pkcs11 node¶

clientAuthentication node¶

clientAuthorization node¶

customClaimsAliasesSpec node¶

policyDefinitions node¶

allowedPolicies node¶

subject node¶

sans node¶

attributeSpec node¶

keyAlgorithm node¶