Major Release 11.0 Notes

New Security Permission Model

For release 11.0 of Keyfactor Command, a new permission structure has been introduced. Users of Keyfactor Command through the Management Portal will see some changes, including:

• The permissions tabs on the Security Roles Role Information For: Role Name page have a new look and method for setting permissions using check boxes in a tree structure.
• The Security Identities page has been removed.
• A new page for Claims has been added. This page allows the user to see the roles a claim is in.
• The security permissions for PKI A public key infrastructure (PKI) is a set of roles, policies, and procedures needed to create, manage, distribute, use, store and revoke digital certificates and manage public-key encryption. Administration (PKI Management: Read and PKI Management: Modify) have been replaced with two new security permissions: Certificate Authorities (Read and Modify) and Certificate Templates (Read and Modify). The upgrade process will appropriately translate the old security permission to the new ones.

Users of Keyfactor Command through the Keyfactor API 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. will need to understand the new model.

On upgrade, existing security roles will be converted to the new permission structure.

The version one permission model was largely replaced in Keyfactor Command version 11.0, but is retained for backwards compatibility for use with select Keyfactor API endpoints.

Support for OAuth 2.0

Release 11.0 of Keyfactor Command introduces support for open authorization (OAuth) 2.0 compliant identity providers as an alternative to Microsoft Active Directory. Keyfactor offers the Keyfactor Identity Provider, which is a lightweight application that is easily installed in the same environment as Keyfactor Command and can be used to provide standalone authentication with user and group management for Keyfactor Command. It may be used directly or federated to another open authorization (OAuth) 2.0 compliant identity provider (e.g. Okta, Ping Identity). Keyfactor Identity Provider runs in a Linux-based container (e.g. Docker).

The Management Portal has been updated to include a new system setting, Identity Providers, that provides the ability to view and edit the identity provider configured for your Keyfactor Command implementation. Active Directory as an identity provider cannot be edited. New identity providers should be added through the Keyfactor Command Configuration Wizard. Authentication with only one identity provider at a time for a given Keyfactor Command server is supported.

When using Keyfactor Identity Provider, there is now a login page to present the user with a login prompt where he or she can choose to login directly to Keyfactor Identity Provider or click a link that will redirect to the login page of the federated identity provider.

The logout functionality for users authenticated with Keyfactor Identity Provider will log the user out and redirect them to the login page. Users authenticated via Active Directory will receive a message instructing them to “Close your browser to sign out” as per earlier versions of Keyfactor Command.

Identity provider secrets can be managed by a PAM provider, if desired.

Certificate Renewal Tracking

When certificates are renewed in Keyfactor Command via the Management Portal or Keyfactor API, a new Keyfactor Renewal record is created. This can be used as a filter for Ignore Renewed Certificates in certificate collections. A history record will now show on the original and renewed certificates showing the thumbprint it was renewed from/to.

Keyfactor Universal Orchestrator in a Container

The Keyfactor Universal Orchestrator The Keyfactor Universal Orchestrator, one of Keyfactor's suite of orchestrators, is used to interact with servers and devices for certificate management, run SSL discovery and management tasks, and manage synchronization of certificate authorities in remote forests. With the addition of custom extensions, it can provide certificate management capabilities on a variety of platforms and devices (e.g. Amazon Web Services (AWS) resources, Citrix\NetScaler devices, F5 devices, IIS stores, JKS keystores, PEM stores, and PKCS#12 stores) and execute tasks outside the standard list of certificate management functions. It runs on either Windows or Linux servers or Linux containers. can now be deployed as a Linux container using a containerization platform such as Docker or Kubernetes. This will make deployments faster and less error prone and can fit into the CI/CD pipeline.

Changes & Improvements

• Script/Handler Library in Command DB

  • POST Extension/Script API endpoint An endpoint is a URL that enables the API to gain access to resources on a server. added for registering PowerShell scripts for alerts for certificate requests, SSH The SSH (secure shell) protocol provides for secure connections between computers. It provides several options for authentication, including public key, and protects the communications with strong encryption. and workflow, that results in their storage in the Keyfactor Command database (there is no Management Portal equivalent for security reasons). Alert and custom workflow scripts are now loaded from the Keyfactor Command database instead of the file system and available from dropdowns on any dialogs that use scripts, so users can select from the list of registered scripts. The upgrade process will retrieve scripts from the extension library folder and import into Keyfactor Command DB.

  • When configuring alerts and workflows, script selection now appears as a dropdown in the Management Portal. Only those scripts that have been defined in the Keyfactor Command database and configured for the selected category appear in the dropdown.

  • When upgrading from a version of Keyfactor Command prior to version 11, the upgrade process will search the file location defined in the Application Settings > Console Tab > Extension Handler Path setting and add all the files found in that directory to the database with the naming convention of foldername (_subfolder name, if applicable)_filenname so it is clear which scripts were imported from which location. The upgrade process will also identify which, if any, of the categories the script is configured for and add that information to the database with the script so that existing scripts will work upon upgrade. The extension library directory has an added file called Migration-<date>.txt that informs the user that this directory has had its scripts migrated to the database.

• System Alert Bar Design Change

  System alerts are now indicated by a bell icon in the header. Clicking on the bell will open a menu of alerts:

  

  Figure 501: System Alerts

• One-Click Renewal Enhancements

  More control was added for allowing one-click renewal on certificates. If you wish to use One-Click Renewal for certificates, the Allow One-Click Renewals option must be enabled in both the templates and CAs to which you want One-Click Renewal to apply (see Certificate Template Operations and Adding or Modifying a CA Record). For more information about one-click renewals, see Renew.

• Enrollment Enhancements

  Added an information message on the PFX A PFX file (personal information exchange format), also known as a PKCS#12 archive, is a single, password-protected certificate archive that contains both the public and matching private key and, optionally, the certificate chain. It is a common format for Windows servers. 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). page to let the user know the required password length.

  Added three new download options to PFX Enrollment: PEM A PEM format certificate file is a base64-encoded certificate. Since it's presented in ASCII, you can open it in any text editor. PEM certificates always begin and end with entries like ---- BEGIN CERTIFICATE---- and ----END CERTIFICATE----. PEM certificates can contain a single certificate or a full certifiate chain and may contain a private key. Usually, extensions of .cer and .crt are certificate files with no private key, .key is a separate private key file, and .pem is both a certificate and private key., DER A DER format certificate file is a DER-encoded binary certificate. It contains a single certificate and does not support storage of private keys. It sometimes has an extension of .der but is often seen with .cer or .crt., and P7B A PKCS #7 format certificate file is a base64-encoded certificate. Since it's presented in ASCII, you can open it in any text editor. PKCS #7 certificates always begin and end with entries that look something like ---- BEGIN CERTIFICATE---- and ----END CERTIFICATE----. Unlike PEM files, PKCS #7 files can contain only a certificate and its certifiate chain but NOT its private key. Extensions of .p7b or .p7c are usually seen on certificate files of this format..

  Added the option to select an algorithm and key size The key size or key length is the number of bits in a key used by a cryptographic algorithm. when using CSR A CSR or certificate signing request is a block of encoded text that is submitted to a CA when enrolling for a certificate. When you generate a CSR within Keyfactor Command, the matching private key for it is stored in Keyfactor Command in encrypted format and will be married with the certificate once returned from the CA. Generation and PFX Enrollment.

  Added an auto-select option to the enrollment pages. When a template is selected that has 2 or more available CAs, the default option in the CA drop down will be auto-select, which will use the first eligible and reachable CA to do the enrollment.

  PFX Enrollment, CSR Enrollment, and CSR Generation now support RSA key size 3072.

• New Email Metadata Type

  For new databases the standard Email-Contact metadata field will be created as the new email metadata type field. For existing databases, any Email-Contact data will be unaffected, but the new metadata type will be available.

• Alerts

  Expiration alerts will no longer determine the time range based on the LastExpiration service settings field. Instead, each expiration alert will have its own last execution time. When created, the value will be set to the current UTC time. The next time it is executed, the time span will be from the time in the LastExecution field and the current UTC time. After execution, the time will update to the current UTC time. Previously, alerts would update the LastRun field in the service settings. This no longer happens. The LastRun field was removed. Users can still see when alerts were last run by looking at the event logs.

• Supported Browsers

  The supported browsers for Keyfactor Command have been updated to:

  • Chrome: 99.0.4844.74

  • Firefox: 98.0

  • Microsoft Edge: 99.0.1150.30

• Certificate Search Updates

  Added download options to the Certificate Search page. The options are now: PEM, DER, P7B, PFX, ZIP PEM, and JKS A Java KeyStore (JKS) is a file containing security certificates with matching private keys. They are often used by Java-based applications for authentication and encryption.. (Previously, the options were PEM, SER, P7B, and PFX.)

  Users without renew certificate permission will no longer see the Renew button.

  On the Certificate Store - View Inventory dialog when you click Query Certificate on a selected inventory item, Keyfactor Command will include the Revoked and Expired check boxes if either condition is true for that certificate.

  When a certificate collection The certificate search function allows you to query the Keyfactor Command database for certificates from any available source based on any criteria of the certificates and save the results as a collection that will be availble in other places in the Management Portal (e.g. expiration alerts and certain reports). is saved, the collection record will include the Revoked and Expired check box state and these will load in the appropriate state when the collection is loaded.

• Certificate Templates

  On the Certificate Templates grid, the Key Type The key type identifies the type of key to create when creating a symmetric or asymmetric key. It references the signing algorithm and often key size (e.g. AES-256, RSA-2048, Ed25519). column is renamed to Key Types and displays all the template's key algorithms and key sizes in a comma-separated list with format KeyType KeySize. For example, a template that supports all key types would look like this: RSA 2048, RSA 4096 and ECC Elliptical curve cryptography (ECC) is a public key encryption technique based on elliptic curve theory that can be used to create faster, smaller, and more efficient cryptographic keys. ECC generates keys through the properties of the elliptic curve equation instead of the traditional method of generation as the product of very large prime numbers. p-256, ECC p-384. Currently, the supported key types are RSA, ECC, ECDSA, Ed448, Ed25519. There is also a new section Key Types and Sizes on the Template > Details tab which list all key type and size information for the template.

  Support is now provided in Keyfactor Command for a single certificate template containing multiple key types, sizes and/or curves.

• Certificate Store Types

  Certificate Store Type Entry Parameters can now be added, edited, or deleted regardless of whether the certificate store type is in use or not. It should be noted that the parameter A parameter or argument is a value that is passed into a function in an application. type (String, Bool, Multiple Choice, or Secret) cannot be changed.

  Certificate Store Type Custom Fields can be added, edited, and deleted even if the type is in use. The custom field's type, however, cannot be changed after it is created. If you want to change that, you must delete the property and add it back with a different type.

  Certificate Store Type Short Name and Name fields can be edited. The Custom Capability field length has been expanded to 64 characters.

• Keyfactor Command Service

  New Keyfactor Command Service related application settings have been added around lock acquisition for ensuring that only one Keyfactor Command Service job runs at a time across multiple servers. On the Console > General tab:

  • Lock Timeout (seconds) - The amount of time to attempt to acquire a lock.

  • Lock Heartbeat Interval (seconds) - How often to update the lock to keep it alive while running a long running Keyfactor Command Service job.

  • LockHoldTimeout (seconds) - How long to wait after the last successful heartbeat interval before the lock is considered to be lost and can be acquired by another machine.

• Certificate Stores

  The maximum length for certificate store reenrollment jobs has been increased from 256 chars to 850 chars.

• Logging

  Improved logging for EJBCA Gateway configuration connection errors.

  Correlation IDs are now returned in the API ‘s HTTP response header as X-Keyfactor-Correlation-Id. These match the correlation GUID tracked in the log files.

• Improved CA Synchronization Performance

  Improved performance for synchronizing CAs that have a large number of duplicate keys.

• Dashboard

  The ability to authenticate to the Dashboards and Reports Engine, Logi Analytics, no longer requires IP addresses.

  The error message that displays in the case of an error condition has been simplified to remove any sensitive information that might reveal inappropriate information to an attacker (e.g. server hostname The unique identifier that serves as name of a computer. It is sometimes presented as a fully qualified domain name (e.g. servername.keyexample.com) and sometimes just as a short name (e.g. servername). or IP address). The message will be displayed as: Your logon credentials failed. Please contact Keyfactor support at support@keyfactor.com for assistance with report customization or migration to the new platform.

• PAM

  Added an optional capability to the Universal Orchestrator to ignore certificate store passwords from Keyfactor Command and obtain them from a client-side PAM provider instead. For more information, see Installing Custom PAM Provider Extensions.

  In previous versions of Keyfactor Command, once a PAM provider had been associated with an orchestrator whose certificate stores were configured to retrieve their secrets from a PAM provider, it was not possible to edit the PAM provider configuration. In Keyfactor Command v11, the PAM configuration can be edited even if the configuration is in use. Note that the PAM configuration can not be deleted if it is in use.

  PAM provider role based access controls have been updated. Previously, certificate store containers were used to provide the security for PAM providers. Since PAM is now being leveraged across Keyfactor Command, this has been removed and replaced with a new security role permission for PAM providers.

• Workflow

  Added a new REST API step in the workflows to support the use of an OAuth bearer token.

  In addition to the tokens in the dropdown in Workflows, any data in the current data bucket can be referenced by entering an appropriate reference string. For example, to return the CSR for an enrollment request you can use $(CSR). Refer to the CurrentStateData field in the response to the GET /Workflow/Instances/{instanceId} API method for information on all the data found in the current (as opposed to initial) data bucket (see GET Workflow Instances Instance ID).

  The PowerShell Set Variable Data workflow step now allows support for the ConvertFrom and ConvertTo cmdlets.

  The Set Variable Data and Use Custom PowerShell workflow steps now use PowerShell 7 to run. Some cmdlets that run in earlier versions of PowerShell are not compatible with PowerShell 7.

Fixes

• Denied alerts configured with metadata fields as substitutable special text tokens in the message were not getting the metadata values inserted on alert generation.

• The GET /OrchestratorJobs/JobStatus/Data endpoint was returning a 404 error even with a valid jobHistoryId.

• Template names were being treated as case sensitive during enrollment API calls. In addition resolution this issue, logging improvements were made to assist in troubleshooting similar items in the future.

• The CSR generation page would not allow input of subject information if the RFC 2818 compliance policy was turned on at either the template or system-wide settings level.

• Deleting a CA and then re-adding it was causing the CA sync to get stuck.

• OCSP files could not be uploaded in the Management Portal.

• Editing certificate metadata caused the certificate import date to change.

• Metadata fields could not be deleted if they had custom settings defined on a template.

• Pending certificate requests without CNs could not be approved.

• The dashboard was not accurately reflecting the counts of certificate collections that included the revoked and expired certificates.
• The certificate store type “Depends On” radio button would not display the available fields when selected.

• The Metadata, Enrollment RegExes, and Enrollment Defaults tabs on Certificate Templates were incorrectly displaying multi-select checkboxes.

• The Dashboard could hang when trying to remove a widget.

• An LDAP CRL A Certificate Revocation List (CRL) is a list of digital certificates that have been revoked by the issuing Certificate Authority (CA) before their scheduled expiration date and should no longer be trusted. could hang when loading the Dashboard Revocation Monitoring widget.

• Reports that have templates as parameters were not allowing the template parameter to be selected.

• When saving an HTTPS CA, on the Authorization methods tab, there is a database field length limit that applies to the secret supplied for the authentication certificate. Errors encountered with a lengthy secret for the certificate have been resolved by saving only the end-entity certificate to the database, rather than the whole chain.
• Certificates that were part of a certificate renewal chain could not be deleted. Now, whenever a certificate is deleted that is a part of a certificate renewal chain, the certificates on either end of the deleted certificate(s) will have their certificate histories updated to show that either a certificate before or after the certificate was deleted in the renewal chain of that certificate.
• Enrollment/PFX: 400 is not returned when a Custom Friendly Name is provided with a PFX enrollment, but the application setting is not enabled.

• Prior to Command v11, it was possible to create a Keyfactor schedule via the API that was impossible to display via the Management Portal schedule picker. For example, an interval that is not on the interval dropdown (e.g., every 107 minutes). Now, the API will also not allow interval values to be saved that cannot be represented in the Management Portal. Previously saved schedules that don't meet these restrictions can still be parsed and used, but not edited and re-saved, as a result errors may be encountered on re-saving invalid schedules that were created via the API.

Deprecation

Important:  The Classic API, also known as the CMS API or CMSAPI, was removed in Keyfactor Command version 11.0. Customers should migrate all uses of the Classic API to the Keyfactor API prior to upgrading to Keyfactor Command versions 11.0 or later.

• The Keyfactor Java Agent The Java Agent, one of Keyfactor's suite of orchestrators, is used to perform discovery of Java keystores and PEM certificate stores, to inventory discovered stores, and to push certificates out to stores as needed. will be deprecated in a future release of Keyfactor Command. Customers are encouraged to begin planning a migration to the Keyfactor Universal Orchestrator with the Remote File custom extension publicly available at: https://github.com/Keyfactor/remote-file-orchestrator.

For more information, see Installing Custom-Built Extensions.

• The following store types have been deprecated and will no longer be shipped with Keyfactor Command:

  • All F5 store types
  • AWS
  • NetScaler
  • IIS certificate store types

  These store types will not be created with new databases. Upon upgrading, they will be removed if the customer does not have any stores or containers defined for the type (per type. i.e. if an AWS store or container is defined and the other types are not, the AWS type will not be removed on upgrade, but the other types will be removed). If you would like to manage these types of stores, you will create new certificate store types as per the appropriate Keyfactor-built custom extension for managing the selected store type (see Installing Custom-Built Extensions).

• The built-in functions for IIS and FTP certificate store management in the Keyfactor Universal Orchestrator have been deprecated in Keyfactor Command version 11.0.

  Customers should migrate all uses of IIS certificate store management to the Keyfactor Universal Orchestrator with the IIS custom extension publicly available at: https://github.com/Keyfactor/iis-orchestrator.

  For more information, see Installing Custom-Built Extensions.

  For customers who have FTP certificate store type, when you upgrade Keyfactor Command to version 11 your FTP stores and related data will not be removed on upgrade. In order to manage the FTP certificate store, you will need to use an older version of the UO that still has the FTP extension.

• The prescript and postscript functionality of the Keyfactor Universal Orchestrator has been replaced by other functionality in Keyfactor Command such as that provided by Keyfactor Command workflows (see Workflow Definitions). As a result, prescript and postscript functionality has been deprecated and will be removed from a future release.

• Windows Orchestrator The Windows Orchestrator, one of Keyfactor's suite of orchestrators, is used to manage synchronization of certificate authorities in remote forests, run SSL discovery and management tasks, and interact with Windows servers as well as F5 devices, NetScaler devices, Amazon Web Services (AWS) resources, and FTP capable devices, for certificate management. In addition, the AnyAgent capability of the Windows Orchestrator allows it to be extended to create custom certificate store types and management capabilities regardless of source platform or location. has been deprecated in v11. The reason for this change is that there has not been a new version since Keyfactor Command v8 and our policy is to support orchestrators for the latest two (2) versions of the products. Additionally, all Windows Orchestrator functionality is available in the new Universal Orchestrator and it's associated extensions.

• In preparation for separating the vSCEP web application into its own solution, the configuration wizard no longer provides the option to install vSCEP. Customers wishing to upgrade and also still use vSCEP should install vSCEP on a separate server. The separate vSCEP application will be released at some point in the future.

• Updating a workflow step's type without changing the unique name will result in an error. To get around this issue, when changing a workflow step's type also change the step's unique name. Another work-around is to delete the step you no longer want and add the new step you do want.

• Updating a workflow step's type without changing the unique name will result in an error. To get around this issue, when changing a workflow step's type also change the step's unique name. Another work-around is to delete the step you no longer want and add the new step you do want.

• Although permissions for a container can be viewed or modified using the permission option on the certificate store containers tab, Keyfactor recommends best practice is to manage permissions as part of the overall permission configuration (see Security Roles and Claims), as additional system-wide configuration settings are available there that cannot be viewed or modified from certificate store containers - permissions page.

• Any renewal instances that were in-flight within the workflows that have been started in version 10 will not create a new renewal link in the certificate’s renewal chain unless the workflow instance was created after an upgrade.

• In Keyfactor Command v11, the v1 security role endpoints only work for Active Directory users. If you move to OAuth and have any integrations against certain security roles APIs, they will not work. Security API endpoints that support OAuth have been added as version v2 of the endpoints.

• The Management Portal and the Keyfactor API do not display duplicate SANs. For certificates that have duplicate SANs, the Management Portal and Keyfactor API only show the unique list and count of the certificate SANs. For example, a certificate with four SANs, of which three are the same (duplicates), would only show two unique SANS on the Certificate Details page and the GET Certificates Keyfactor API method.

• SSH management in Keyfactor Command with the Keyfactor Bash Orchestrator The Bash Orchestrator, one of Keyfactor's suite of orchestrators, is used to discover and manage SSH keys across an enterprise. is only supported when using Active Directory as an identity provider. The SSH option in the Management Portal will only appear when Keyfactor Command is installed using Active Directory as an identity provider (and with a license that supports SSH).

• Orchestrator auto-registration in Keyfactor Command is only supported when using Active Directory as an identity provider. If you need auto-registration with Keyfactor Identity Provider authentication, see Custom Auto-Registration Handlers.

• The configuration options on the Keyfactor Universal Orchestrator for remote CA management require that the AdditionalCertificateAuthoritiesAllowed value be set to true regardless of whether you populate the CertificateAuthorities section with your CA information.

• In version 11, if you attempt to access the Management Portal when the SQL server is offline, you will get a blank page with a 503 unavailable error. Note that an IIS reset will be needed to connect to the Management Portal when you restart the SQL server. In version 10 and prior, you would get a screen that said that there was an issue.

• When using Keyfactor Command on a non-domain-joined server, there are some areas in the Keyfactor Command Management Portal that may cause confusion since they reference Active Directory. These places are not going to be addressed for 11:

• Certificate authority A certificate authority (CA) is an entity that issues digital certificates. Within Keyfactor Command, a CA may be a Microsoft CA or a Keyfactor gateway to a cloud-based or remote CA. import may show an empty dropdown.

• The orchestrator auto-registration Validate Users function will return a could not be resolved error.

• When querying a workflow by ID with the contains or starts with operators and a partial id value an error is reported that it is an Invalid Id value.

• In the configuration wizard under Authentication, there is a field for Identity Provider Hint. This field has been deprecated and will be removed in a future version of Keyfactor Command.

• Keyfactor API requests that feature a query in the URL of type QueryString, such as the following example, will only function with the parameter QueryString. In versions of the Keyfactor API prior to 11.0, either QueryString or Query was supported. This will be corrected in a future release.

  https://keyfactor.keyexample.com/KeyfactorAPI/Certificates?IncludeRevoked=true&QueryString=CN%20-startswith%20%22test%22&collectionId=0&includeLocations=false&includeMetadata=false&includeHasPrivateKey=false&verbose=0

Please review the information in the API Change Log for this release carefully if you have implemented any integration using these endpoints:

To reflect the changes made during the .NET 6 migration, in Keyfactor Command version 11, the Keyfactor API Reference and Utility (Swagger) link from the Management Portal is changed as follows:

• The URL for the Keyfactor API Reference and Utility changed from https:/keyfactor.keyexample.com/KeyfactorAPI/ref/index#

  to https://keyfactor.keyexample.com/KeyfactorAPI/swagger/index.html

  Tip:  Where keyfactor.keyexample.com is the Keyfactor Command Management Portal server and KeyfactorAPI is the virtual directory assigned to the Keyfactor Command Management Portal in the configuration wizard.

• There is no longer an individual URL link to each API endpoint within the Keyfactor API Reference and Utility (such as https://keyfactor.keyexample.com/KeyfactorAPI/ref/index#!/Certificate/Certificate_QueryCertificates) at the bottom of each Keyfactor API Reference Guide documentation page—just the one link to the main page of the Keyfactor API Reference and Utility.

• At the top of the Keyfactor API Reference and Utility under the title there is a link to allow easy access to the raw OpenAPI JSON.