- Introduction
- Lab Environment
- Orchestrator Communication Overview
- Orchestrator Certificates: Purpose and Characteristics
- Managing the Orchestrator Certificates
- Certificate Keys and Stores
- Orchestrator Server Java KeyStore (jssacacerts)
- Overview of SSL Communication, Keys, and Stores
- Orchestrator Certificates: Purpose and Characteristics
- Final Step
Introduction
In this article we will look into the different types of VMware vRealize Orchestrator certificates and their purpose. We will discuss the most common uses cases that might require you to change an Orchestrator certificate and how to accomplish this. Although we will focus on VMware vRealize Orchestrator 7.0 server most of the article is generally applicable for previous product versions.
Explaining how a Public Key Infrastructure (PKI) is very extensive topic. Although we will not be able to explain it in this article we will explain some basics which will be enough to give you the knowledge and ability to change your Orchestrator certificates according to your needs.
Lab Environment
The full lab logical design can be seen HERE.
Orchestrator Communication Overview
Now let’s take a look and see how we communicate with the Orchestrator server.
Orchestrator is a Client-Server application.
A user client communicate with Orchestrator API either via the Orchestrator Client or a web browser using HTTPS and port 8281.
A user client communicate with the Orchestrator Control Center either via a web browser using HTTPS and port 8283.
An application client communicating with Orchestrator using HTTPS and port 8281. For example this can be vCenter or vRealize Automation Center.
This is represented by the following diagram:
Orchestrator Certificates: Purpose and Characteristics
Certificate for HTTPS 5480
Orchestrator uses a certificate for the virtual appliance management interface (VAMI). This certificate has the following characteristics:
- Accessibility: You access this interface by navigating to https://<Orchestrator_Server>:5480.
- Purpose: Access to virtual appliance Web management interface. The certificate is used for the VAMI interface. It not user to secure any communication from or to the Orchestrator server.
- KeyStore Location: Certificate is stored in Orchestrator server in the following location:
- /opt/vmware/etc/lighttpd/server.pem
- Certificate Type (by Issuer): Self-signed certificate.
- Certificate Signature Algorithm: SHA1RSA
- Certificate Private Key (length): RSA 2048 (bits)
Note that this might vary depending on the version of the Orchestrator server.
- Certificate Private Key (Issuer): Orchestrator Server.
Note that this might vary depending on the version of the Orchestrator server.
The following is a screenshot of the VAMI interface certificate:
The following diagram roughly resents the client-server HTTPS communication over port 5480:
Certificate for HTTPS 8281 & 8283
Orchestrator uses a certificate for the Orchestrator appliance page and Orchestrator Control Center (Previously Orchestrator Configuration) page. This certificate has the following characteristics:
- Accessible at: You can access the Orchestrator appliance page by navigating to https://<Orchestrator_Server>:8281. You can access the Orchestrator Control Center page by navigating to https://<Orchestrator_Server>:8283/vco-controlcenter.
- Manageable from: You can manage the certificate by navigating to the Orchestrator Control Center, Certificates, and then Orchestrator Server SSL Certificate page. Depending on the use case you might also need to use the keytool to manage the certificate.
- Purpose: HTTPS server port 8281 is used to connect to the Web view front end and to communicate with the vRealize Orchestrator API. HTTPS server port 8283 is used for Web configuration HTTPS access port. The SSL access port for the Web UI of Orchestrator configuration.
- KeyStore Location: Certificate is stored in Orchestrator server in the following Java keystore: /etc/vco/app-server/security/jssecacerts.
- Note that this path might vary depending on the version of the Orchestrator server.
- KeyStore Type: JKS
- Certificate Type (by Issuer): Self-signed certificate.
- Certificate Signature Algorithm: SHA1RSA
Note that this might vary depending on the version of the Orchestrator server.
- Certificate Private Key (length): RSA 2048 (bits)
Note that this might vary depending on the version of the Orchestrator server.
- Certificate Private Key (Issuer): Orchestrator Server.
Screenshot shows the Orchestrator appliance certificate.
The following diagram roughly represents the client-server HTTPS communication over port 8281/8283:
Certificate for Package Signing
Orchestrator uses a certificate to digitally sign workflow packages that are exported form the Orchestrator server. This certificate has the following characteristics:
- Accessible at: You can access the package signing certificate by navigating to the Orchestrator Control Center, Certificates, and then the Package Signing Certificates page. You can also access this via the Orchestrator Certificates Manager which is accessible form the Tools menu within the Orchestrator Client.
- Manageable from: You can manage the certificate using the same tools you use to access it.
- Purpose: This certificate is used to digitally sign any workflow packages that are exported from Orchestrator server. . It not user to secure any communication from or to the Orchestrator server.
- KeyStore Location: Certificate is stored in Orchestrator server database.
- KeyStore Type: JCEKS
- KeyStore Secret Key: Yes
- Certificate Type (by Issuer): Self-signed certificate.
- Certificate Signature Algorithm: SHA512RSA
Note that this might vary depending on the version of the Orchestrator server.
- Certificate Private Key (length): RSA 2048 (bits)
Note that this might vary depending on the version of the Orchestrator server.
Screenshot shows the package signing certificate in the Orchestrator Certificates Manager.
The following diagram roughly represents the relation between vRO clients, vRO Server and the package signing certificate:
Managing the Orchestrator Certificates
Now that we have looked into the different Orchestrator certificates and their purpose, let’s see how we can manage the Orchestrator certificates. VMware vRealize Orchestrator 7.0 now offers a brand new Control Center page that replaces the Orchestrator Configuration page.
This page is accessible by navigating to : https://<Orchestrator_Server>:8283/vco-controlcenter.
You can access the primary tool for managing certificates by navigating to the Control Center and then the Certificates page.
Screenshot shows the Certificates page.
On the Certificates page you will find the following tabs:
- Trusted Certificates. You can use this tab to import certificates into the Orchestrator certificate trust store. Upon import these certificates are placed in the following Java KeyStore: /etc/vco/app-server/security/jssecacerts .
- Orchestrator Server SSL Certificate. You can use this tab to generate new Self-signed Orchestrator Server SSL Certificate. You can also import a certificate from a Java KeyStore or a PEM-encoded certificate file. Upon import these certificates are placed in the following Java KeyStore: /etc/vco/app-server/security/jssecacerts.
- Package Signing Certificate. You can use this tab generate new Self-signed Orchestrator Package Signing Certificate. You can also import a certificate from a Java KeyStore or export the current certificate to a Java KeyStore. Upon import this certificate is stored in the Orchestrator database.
You have one more tool that you use when managing the Orchestrator Package Signing Certificate. This is the Orchestrator Certificate Manager. To access this you log-in to Orchestrator using the Orchestrator Client and then access the Certificate Manager from the Tools menu.
In some use cases, as we will see shortly, these tools do not provide all the necessary functionality that we might need. To satisfy those use cases we also use the keytool tool to manage certificates.
Certificate Keys and Stores
As with any other Client-Server application that users SSL to communicate, all participants in the communication (the server and the user\application client) must trust the certificate used to encrypt the communication. In order to trust the certificate used for communication, all participants must trust all the certificates from the certificate chain.
Consider the following example:
- You have a Root Certification Authority called RootCA
- You have a Subordinate/Issuing Certification Authority called SubCA
- You have a Server certificate issued from the SubCA Certification Authority.
- You want to use this certificate to encrypt the communication between the client and the server.
Screenshot shows the certificate:
In order for this certificate to be trusted from all participants in the communication the server certificate, the RootCA certificate, and the SubCA certificate must be imported in the appropriate certificate stores.
Certificates that need to be present on the Orchestrator server:
- The SubCA certificate must be imported in the Orchestrator server trust store (Java KeyStore).
- The RootCA certificate must be imported in the Orchestrator server trust store (Java KeyStore).
- The server certificate must be replaced in the Orchestrator server (Java KeyStore).
If using the Orchestrator client to communicate with Orchestrator server, the following certificates need to be present on the Orchestrator client:
- The SubCA certificate must be imported in the Orchestrator client trust store (Java KeyStore).
- The RootCA certificate must be imported in the Orchestrator client trust store (Java KeyStore).
- The server certificate must be imported in the Orchestrator client trust store (Java KeyStore).
If using a web browser to communicate with Orchestrator server, the following certificates need to be present in the web browser:
- The SubCA certificate must be imported in the web browser’s Intermediate Certificate Authorities trust store (Browser or OS keystore).
- The RootCA certificate must be imported in the web browser’s Trusted Root Certification Authorities trust store (Browser or OS keystore).
- The server certificate must be imported in the web browser’s Personal trust store (Browser or OS keystore).
Note: Some browsers inherit (share) the certificate trust store of the underlying operating system. If this is the case, the above certificates must be imported into the operating system certificate store.
If using an application to communicate with Orchestrator server, the following certificates need to be trusted by the application:
- The SubCA certificate must be imported in the application’s Intermediate Certificate Authorities trust store.
- The RootCA certificate must be imported in the application’s Trusted Root Certification Authorities trust store.
- The server certificate must be imported in the application’s Personal trust store.
Orchestrator Server Java KeyStore (jssacacerts)
Before we continue with the use cases there is one more important thing you need to know.
Java Keytool is a key and certificate management utility. It allows users to manage their own public/private key pairs and certificates. Java Keytool stores the keys and certificates in what is called a keystore. By default the Java keystore is implemented as a file. It protects private keys with a password. A Keytool keystore contains the private key and any certificates necessary to complete a chain of trust and establish the trustworthiness of the primary certificate.
Each certificate in a Java keystore is associated with a unique alias. When creating a Java keystore you will first create the .jks file that will initially only contain the private key. You will then generate a CSR and have a certificate generated from it. Then you will import the certificate to the keystore including any Root and Intermediate/Issueing Certification Authority certificates.
Orchestrator stores the Orchestrator Server SSL Certificate in a Java KeyStore called jssecacerts.
This Java KeyStore is created using a Private key (SHA1RSA 2048 bit) during Orchestrator deployment. Any When you generate a certificate request , the request will be signed by the private key of the Orchestrator Java KeyStore (jssecacerts). This means that after a certificate is generated from that certificate request it will be signed with the private key of the Orchestrator Java KeyStore (jssecacerts). This also means that the generated certificate will (in this example) be signed using SHA1RSA as an encryption algorithm and 2048 bit as a key length.
You can verify this by examining the default Orchestrator Server SSL Certificate.
Screenshot shows the Orchestrator Server SSL Certificate.
As we will see later, some company security polices might enforce the use of a different certificate signature algorithm, like: SHA256 or SHA521.
If this is the case , in order to be able to use an Orchestrator Server SSL certificate which uses a SHA512 or SHA512 certificate signature algorithm , we must recreate the Orchestrator Java KeyStore with a private key which uses SHA256 or SHA512 as certificate signature algorithm.
Orchestrator has algorithm restrictions for certification path (CertPath) processing. In some environments, certain algorithms or key lengths may be undesirable for certification path building and validation. For example, "MD2" is generally no longer considered to be a secure hash algorithm.
vRealize Orchestrator 7.0 does not support MD2 or RSA with key length smaller then 1024
There are also some algorithm restrictions for Secure Socket Layer/Transport Layer Security (SSL/TLS) processing In some environments, certain algorithms or key lengths may be undesirable when using SSL/TLS.
vRealize Orchestrator 7.0 does not support SSLv3, RC4, DH with key length smaller then 768
Another thing worth noticing is that after importing the Orchestrator Server SSL Certificate into the Java KeyStore, you need to change the alias of that certificate to dunes . Orchestrator is looking for a certificate with that alias and will fail to start if it cannot find it.
Screenshot shows the contents of the Java keyStore
Overview of SSL Communication, Keys, and Stores
The following diagram roughly represents the SSL communication between the Orchestrator server , Orchestrator Client, web browser and other applications. It also illustrates the different turst stores (keystores) and their usage.
Use Cases
Concider a software development company that is planning to implement VMware vRealize Orchestrator to provide orchestration and automation capabilities in their infrastructure. The company has strict security policies that need to be applied to the Orchestrator server.
Use Case 1(VAMI 5480)
The company has identified the following security requirements that need to be applied to the Orchestrator server:
- UC1-R1: Change the certificate used by the VAMI interface on port 5480 (HTTPS) with a certificate issued by the company’s certificate authority.
- UC1-R2: Use a certificate signature algorithm and key length that meet the company’s security policies. The default certificate signature algorithm SHA1RSA and ley length of 2048 do not meet the company’s security policies.
- UC1-R3: The browser used for accessing the Orchestrator server must trust the new certificate and it’s chain.
To accomplish this one would generally perform the following steps:
- Issue a Server certificate to be used by the VAMI interface. Select appropriate certificate signature algorithm and key length for the certificate.
- Back up the existing certificate used by the VAMI interface on port 5480 (HTTPS). The certificate is located under /opt/vmware/etc/lighttpd/server.pem
- Replace the server.pem certificate with the one issued from a certificate authority.
- Restart the Orchestrator appliance.
- Use the Internet browser to import any Root or Intermediate/Issuing Certificate Authority certificates.
Use Case 2 (Package Signing Certificate)
The company has identified the following security requirements that need to be applied to the Orchestrator server:
- UC2-R1: The default Package Signing Certificate which uses an SHA512RSA certificate signature algorithm and key length of 2048 is considered secure enough according to the company’s security policies.
- UC2-R2: A second orchestrator appliance must be able to read all digitally signed Orchestrator workflow packages.
To accomplish this one would generally perform the following steps:
- Use the Control Center interface on the first Orchestrator server to export the Package Signing Certificate keystore.
- Use the Control Center interface on the second Orchestrator server to import the Package Signing Certificate keystore.
- Use the Control Center interface to restart the second Orchestrator server.
Use Case 3 (Package Signing Certificate)
The company has identified the following security requirements that need to be applied to the Orchestrator server:
- UC3-R1: The default Package Signing Certificate which uses an SHA512RSA certificate signature algorithm and key length of 2048 is not considered secure enough according to the company’s security policies. This certificate must be changed to meet the company’s security policies.
- UC3-R2: A second orchestrator appliance must be able to read all digitally signed Orchestrator workflow packages.
To accomplish this one would generally perform the following steps:
- Issue a server certificate to meet the company’s requirement. The certificate must have the DigitalSignature and Key_Encipherment Key Usage attributes. It must also have the Server Authentication Extended Key Usage attribute. Ensure the certificate has a private key.
- Use the keytool to create new keystore. The keystore type must be JCEKS.
- Use the keytool to import the server certificate into the keystore.
- Use the keytool to change the alias of the certificate to _dunesrsa_alias_
- Use the keytool to generate a Security Key and place it in the keystore.
- Use the keytool to change the alias of the Security Key to _dunessk_alias_
- Use the Control Center interface on the first Orchestrator server to import the keystore you created.
- Use the Control Center interface to restart the first Orchestrator server
- Use the Orchestrator Certificate Manager tool on the first Orchestrator server to import any Root or Intermediate/Issuing Certificate Authority’s certificates.
- Use the Control Center interface on the second Orchestrator server to import the keystore you created.
- Use the Control Center interface to restart the second Orchestrator server.
- Use the Orchestrator Certificate Manager tool on the second Orchestrator server to import any Root or Intermediate/Issuing Certificate Authority’s certificates.
Use Case 4 (Server SSL Certificate 8281 & 8283)
The company has identified the following security requirements that need to be applied to the Orchestrator server:
- UC4-R1: The default Orchestrator Server SSL Certificate uses an SHA1RSA certificate signature algorithm and key length of 2048 which is considered secure enough according to the company’s security policies. The certificate must be issued from the company’s certificate authority. This certificate must be changed to meet the company’s security policies.
- UC4-R2: The Orchestrator client must trust the new certificate and it’s chain.
- UC4-R3: The browser used for accessing the Orchestrator server must trust the new certificate and it’s chain.
To accomplish this one would generally perform the following steps:
- Issue a server certificate to meet the company’s requirement. The certificate must have the DigitalSignature and Key_Encipherment Key Usage attributes. It must also have the Server Authentication Extended Key Usage attribute. Ensure the certificate has a private key.
- Use the keytool to generate a certificate request file. Specify the certificate with alias dunes during the request. This way you will use the private key of the existing certificate to sign the request.
- Issue a server certificate from the company’s certificate authority based on this certificate request file.
- Use the keytool to import the server certificate into the keystore.
- Use the keytool to change the alias of the certificate to dunes.
- Use the Trusted Certificates tab of the Control Center interface to import any Root and Intermediate/Issuing Certificate authority certificates.
- Use the Control Center interface to restart the Orchestrator server.
- Use the Orchestrator client to connect to the Orchestrator server and import the new certificate when asked.
- Use the Internet browser to import any Root or Intermediate/Issuing Certificate Authority certificates.
If you want to learn more on how to change the SSL certificate of a vCO 7.x Appliance, visit
How to change the SSL certificate of a vRO Appliance (7.x)
If you want to learn more on how to change the SSL certificate of a vCO 6.x Appliance, visit
How to change the SSL certificate of a vRO Appliance (6.x)
UsCase 5e (Server SSL Certificate 8281 & 8283)
The company has identified the following security requirements that need to be applied to the Orchestrator server:
- UC5-R1: The default Orchestrator Server SSL Certificate uses an SHA1RSA certificate signature algorithm and key length of 2048 which is not considered secure enough according to the company’s security policies. The certificate must be issued from the company’s certificate authority. This certificate must be changed to meet the company’s security policies.
- UC5-R2: The Orchestrator client must trust the new certificate and it’s chain.
- UC5-R3: The browser used for accessing the Orchestrator server must trust the new certificate and it’s chain.
To accomplish this one would generally perform the following steps:
- Issue a server certificate to meet the company’s requirement. The certificate must have the DigitalSignature and Key_Encipherment Key Usage attributes. It must also have the Server Authentication Extended Key Usage attribute. Ensure the certificate has a private key.
- Use the keytool to create a new keystore and import the server certificate.
- Use the keytool to change the alias of the certificate to dunes.
- Use the Trusted Certificates tab of the Control Center interface to import any Root and Intermediate/Issuing Certificate authority certificates.
- Use the Control Center interface to restart the Orchestrator server.
- Use the Orchestrator client to connect to the Orchestrator server and import the new certificate when asked.
- Use the Internet browser to import any Root or Intermediate/Issuing Certificate Authority certificates.
If you want to learn more on how to change the SSL certificate of a vCO 7.x Appliance, visit
How to change the SSL certificate of a vRO Appliance (7.x)
If you want to learn more on how to change the SSL certificate of a vCO 6.x Appliance, visit
How to change the SSL certificate of a vRO Appliance (6.x)
Final Step
If all went well, go grab a beer.
include TEMPLATEPATH."/../../../itBlogDisclaimer.php"; ?>