Keyfactor ACME Metadata

The Keyfactor ACME server can include metadata Metadata provides information about a piece of data. It is used to summarize basic information about data, which can make working with the data easier. In Keyfactor Command, the certificate metadata feature allows you to create custom metadata fields that allow you to tag certificates with tracking information about certificates. with its requests to Keyfactor Command through a custom extension that comes installed with the Keyfactor ACME server and is built using the ACME nuget package ICertificateRequestMetadataGenerator interface. You can utilize the included PowerShell custom extension or write your own custom extension.

Windows Installations (IIS)

To implement the Keyfactor ACME metadata custom extension:

Create a PowerShell script (see Sample ACME Metadata PowerShell Scripts).
Place the script in the desired location on the Keyfactor ACME server and note the location for step 5. The default location is:

C:\Program Files\Keyfactor\ACME\API
On the Keyfactor ACME server, locate the API An API is a set of functions to allow creation of applications. Keyfactor offers the Keyfactor API, which allows third-party software to integrate with the advanced certificate enrollment and management features of Keyfactor Command.\extensions directory within the install directory. By default, this is:

C:\Program Files\Keyfactor\ACME\API\extensions
In the extensions directory, either create a new directory with an appropriate name for your custom extension, or browse into the included PowerShellDriver subdirectory. This name is for reference only and does not need to match any names used elsewhere.
Place the files for your custom extension in the new directory, if applicable.
In the directory for your extension, locate the manifest.json file or create a new one. The manifest.json file should be placed in the same directory as the DLL(s) for the extension.
Using a text editor, edit the manifest.json file and configure it appropriately.

PowerShellDriver Extension: For the provided PowerShellDriver extension, add the name and optional path to your PowerShell script to the ScriptLocation. If you provide no path, the script will need to be in the API directory within the install directory. By default, this is:

C:\Program Files\Keyfactor\ACME\API
Copy
```
1
2
3
4
5
6
7
8
9
10
11
12
13
{
  "extensions": {
    "Keyfactor.ACME.Extensions.ICertificateRequestMetadataGenerator": {
      "PowershellExecutor": {
        "AssemblyPath": "Keyfactor.ACME.PowershellDriver.dll",
        "TypeFullName": "Keyfactor.ACME.PowershellDriver.PowershellExecutor",
        "Options": {
          "ScriptLocation": "SetMetadata.ps1"
        }
      }
    }
  }
}
```
Your Custom Extension: Create a manifest.json file similar to the one shown above referencing your extension. Things to note:
- The configuration for your extension will vary on lines 4-6 from that shown here. The other lines should be the same.
- The name you give your extension should match the name you enter in line 4.
- The AssemblyPath (line 5) points to the DLL in the extensions directory created for your extension.
- The TypeFileName (line 6) corresponds to the name of the type that resides inside of the DLL listed for the assembly path.
For information on creating a custom extension, see Create a Custom Metadata Generator Extension.
After the script finishes, any values populated in the $metadata object will be used in the Keyfactor Command enrollment Certificate enrollment refers to the process by which a user requests a digital certificate. The user must submit the request to a certificate authority (CA)..

Important: Any errors in the PowerShell script, or any errors the extension generates in Keyfactor ACME, will be written to the log and prevent the enrollment from going through.

Container Installations (Kubernetes)

There are a number of approaches to mounting a PowerShell script for populating metadata values in Keyfactor Command into the ACME container. Here we provide two examples:

ConfigMap:

A ConfigMap might be a good choice if your PowerShell script is quite simple.
PersistentVolume:

A PersistentVolume might be a good choice for a longer or more complex PowerShell script. A PersistentVolume allows you to make subsequent changes to the PowerShell script stored in the PersistentVolume location without needing to restart or upgrade the ACME container. The script updates will be loaded dynamically.

Note: If your persistent volume is stored in a network file system, additional configuration settings are required for dynamic update.

Metadata PowerShell Script Configuration with a ConfigMap

To implement a custom Keyfactor ACME metadata PowerShell script with a ConfigMap:

Create a PowerShell script (see Sample ACME Metadata PowerShell Scripts).

Create a YAML file for the ConfigMap containing data similar to the following, including your full PowerShell script:

apiVersion: v1
kind: ConfigMap
metadata:
  name: acme-powershell
  annotations:
    helm.sh/hook: pre-install
    helm.sh/hook-weight: "-1"
data:
  metadata1.ps1: |
    # Uncomment to output returned values to Keyfactor ACME log file at WARN level.
    #Write-Warning "Username: $username"
    #$identifiers | ForEach-Object -Process {Write-Warning "Identifier: $_" }
    #Write-Warning "Template: $template"
    #Write-Warning "CSR: $csr"

    # Populate the Email-Contact metadata field with one or more static values
    $metadata."Email-Contact" = "john.smith@keyexample.com;martha.jones@keyexample.com"

Create a ConfigMap containing the PowerShell configuration based on the yaml file you created. For example:

sudo kubectl apply --filename=/opt/kyf_acme/metadata.yaml --namespace keyfactor-acme

Edit your values file to add a volume and volumeMount for the ConfigMap of the PowerShell script(s) and a reference to the script in the acme section. For example, the following values file section shows the example root trusts volume (see Installing Keyfactor ACME in Containers Under Kubernetes) and the PowerShell script.

workloadDefaults:
  volumes:
    - name: root-cas
      configMap:
        name: ca-roots
        items:
          - key: ca-certificates.crt
            path: ca-certificates.crt
    - name: metadata
      configMap:
        name: acme-powershell

  volumeMounts:
    - name: root-cas
      mountPath: /etc/ssl/certs/ca-certificates.crt
      subPath: ca-certificates.crt
    - name: metadata
      mountPath: /app/powershell
      readOnly: true

acme:
  powershell:
    scriptLocations:
      - name: MetadataOne
        location: /app/powershell/metadata1.ps1

Load the new values, referencing the deployment name, namespace, your customized values file, the helm chart, and version. For example:

sudo helm upgrade Helm_Deployment_Name --namespace keyfactor-acme --values values.yaml oci://repo.keyfactor.com/charts/command/acme --version 1.0.0

Metadata PowerShell Script Configuration with a PersistentVolume

To implement a custom Keyfactor ACME metadata PowerShell script with a PersistentVolume:

Create one or more PowerShell scripts (see Sample ACME Metadata PowerShell Scripts).
Copy the PowerShell script(s) to your Kubernetes server and place it in your working directory for Keyfactor ACME. For example:

/opt/kyf_acme/metadata1.ps1

/opt/kyf_acme/metadata2.ps1
Create a PersistentVolume in Kubernetes to contain your PowerShell script. The steps for this will vary depending on your Kubernetes implementation and the intended storage location used by your PersistentVolume.
Tip: You can create a PersistentVolume in the local file system for testing purposes as follows:
1. Create a directory that your PersistentVolume will reference and which will contain the files to be mounted via the persistent volume. For example:
  mkdir /opt/files/powershell
2. Create a YAML file to define the PersistentVolume similar to the following:
```
apiVersion: v1
kind: PersistentVolume
metadata:
  name: powershell-pv
spec:
  storageClassName: manual
  capacity:
    storage: 10Gi
accessModes:
  - ReadWriteOnce
hostPath:
  path: "/opt/files/powershell"
```
3. Create the PersistentVolume based on the yaml file you created. For example:
  sudo kubectl apply --filename=/opt/kyf_acme/powershell-pv.yaml
  PersistentVolumes are cluster-scoped resources, meaning they are not associated with a specific namespace.
4. Create a YAML file to define a PersistentVolumeClaim associated with the PersistentVolume similar to the following:
```
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: powershell-pvc
spec:
  storageClassName: manual
  accessModes:
    - ReadWriteOnce
  resources:
    requests:
      storage: 10Gi
```
5. Create the PersistentVolumeClaim based on the yaml file you created. For example:
  sudo kubectl apply --filename=/opt/kyf_acme/powershell-pvc.yaml --namespace keyfactor-acme
  Unlike PersistentVolumes, PersistentVolumeClaims are associated with a specific namespace.
6. Place the files that should be mounted in the container into the directory you specified in the file system. For example:
  /opt/files/powershell/metadata1.ps1
  /opt/files/powershell/metadata2.ps1
Important: This method should not be used for a production PersistentVolume.

Edit your values file to add a volume and volumeMount for the Persistent Volume of the PowerShell script(s) and a reference to the script(s) in the acme section. For example, the following values file section shows the example root trusts volume (see Installing Keyfactor ACME in Containers Under Kubernetes) and two PowerShell scripts.

workloadDefaults:
  volumes:
    - name: root-cas
      configMap:
        name: ca-roots
        items:
          - key: ca-certificates.crt
            path: ca-certificates.crt
    - name: metadata
      persistentVolumeClaim:
        claimName: powershell-pvc

  volumeMounts:
    - name: root-cas
      mountPath: /etc/ssl/certs/ca-certificates.crt
      subPath: ca-certificates.crt
    - name: metadata
      mountPath: /app/powershell
      readOnly: true

acme:
  powershell:
    scriptLocations:
      - name: MetadataOne
        location: /app/powershell/metadata1.ps1
      - name: MetadataTwo
        location: /app/powershell/metadata2.ps1

Load the new values, referencing the deployment name, namespace, your customized values file, the helm chart, and version. For example:

sudo helm upgrade Helm_Deployment_Name --namespace keyfactor-acme --values values.yaml oci://repo.keyfactor.com/charts/command/acme --version 1.0.0

Was this page helpful? Provide Feedback

Version v25.3

On this page: