How to replace a Principal Identity Certificate in NSX

Products

• VMware NSX

Issue/Introduction

• This article provides the steps for replacing NSX Principal Identity (PI) Certificate:

Environment

VMware NSX

Cause

A PI certificate is used for authentication with a remote entity, NSX will have the certificate (not the key), the remote entity will own the certificate and the key.

When the remote entity makes an authentication request using the PI user, NSX presents the certificate and the remote entity will use the key it has to verify the connection.

Resolution

NSX Self Signed Certificate

Self Signed Certificates generated on NSX can not be used for PI connections to NSX.

CA Signed Certificate or Self signed certificate

The remote entity should generate a CA signed certificate or self signed certificate with public and private key and retain the private key.

Use the public key part of the new certificate when creating the PI user in NSX, NSX does not need or use the private key.

Importing the remote entity certificate:

1. In System, Certificates, click IMPORT and select Certificate (Not CA Certificate).
2. Give the certificate a meaningful name, its usual best if it refers to the remote entity, to easily identify it later.
3. Deselect the Service Certificate option.
4. Paste the new remote entity public key in the Certificate Contents box, this is the part of the certificate starting with '-----BEGIN CERTIFICATE-----' and ending with '-----END CERTIFICATE-----' and all the Base64 details in between.
   Note:There will be one '-----BEGIN CERTIFICATE-----' and '-----END CERTIFICATE-----' if it is a self signed certificate.
   If this is a CA signed certificate, there may be multiple '-----BEGIN CERTIFICATE-----' and '-----END CERTIFICATE-----' entries, import them all, the order should be Leaf certificate (the server/endpoint), Intermediate CA certificate(s) (if any), then Root certificate. The number depends on the certificate authority that signed the certificate.
5. There is a box in this window called Private Key, do not import the private key from the remote entity here or in the Certificate Contents box.
   Note: Private key is the part that start with '-----BEGIN PRIVATE KEY-----' and ending with '-----END PRIVATE KEY-----' and all the Base64 details in between. Certificate(s) used for PI in NSX do not need the private key, they are required for other services such as load balancer/VPN, which are not covered under this KB.
6. Leave the Passphrase option blank.
7. Add a Description as desired.
8. And click SAVE.

Replace the expired/expiring PI certificate.

UI Option: Since NSX 4.2.1. The certificate can be replaced in the NSX UI, prior to this, it was only possible using API calls.

1. In the NSX manager UI, go to System, Certificates.
2. Locate the expired/expiring PI certificate in the certificates list.
3. Click on the ellipsis (three dots/hamburger menu) on the left side of the certificate entry.
4. Select Replace Certificate from the menu presented.
5. In the next window Replace Certificates, on the right side, under Select Certificate to Replace With, from the drop down menu Select Service/Entity, chose the new remote entity certificate (public key) imported above under step 'Importing the remote entity certificate'.
6. Click SAVE, the expired/expiring certificate will now be replaced.
7. Once the certificate is replaced, validate the remote entity can still preform operations using the PI user, this is outside the scope of NSX and lays directly with the remote entity.
8. Once the PI user is validated, the old expired/expiring certificate should show 0 under the Used By column and can now be deleted.

API Option: All versions. If you are on a version prior to 4.2.1 or using API is your preferred option, use the following procedure.

1. Find the certificate ID, you can do it two ways, UI or API:
   1. UI Option: In System, Certificates, expand the imported certificate (imported above under step 'Importing the remote entity certificate'.) and note the certificate ID, for example:
      
      
   2. API Option: Use the following API call to retrieve all the certificates in NSX:
      GET https://<nsx-mgr>/api/v1/trust-management/certificates
      
      Locate the imported certificate (imported above under step 'Importing the remote entity certificate'.) and note the certificate id, for example:
      "id" : "########-4c4a-4cc0-97d7-########",
"display_name" : "test-user@###",
      
      
2. Find the PI user ID:
   1. Use the API call below to get the PI user ID, which uses the expiring/expired certificate:
      GET https://<nsx-mgr>/api/v1/trust-management/principal-identities
   2. In the results returned, find the user, then under the user, locate the id, for example will look something like:
      "resource_type" : "PrincipalIdentity",
"id" : "########-35d6-47ff-863e-############", -> this is the id you need for the next API call.
"display_name" : "test-user@###",
      
      
3. Replace the certificate:
   1. Use the POST API call below to apply the new Certificate ID (imported above under step 'Importing the remote entity certificate'.) along with the PI user ID obtained from above:
      POST https://<nsx-mgr>/api/v1/trust-management/principal-identities?action=update_certificate
{
    "principal_identity_id": "########-####-####-####-############",
    "certificate_id" : "########-####-####-####-############"
}
4. Once the certificate is replaced, validate the remote entity can still preform operations using the PI user, this is outside the scope of NSX and lays directly with the remote entity.
5. Once the PI user is validated, the old expired/expiring certificate should show 0 under the Used By column and can now be deleted.

 

Note: Do not use this procedure to replace Local Manager or Global Manager principal identity certificates Replace Certificates Through API

More details on Importing/Replacing PI Certificates can be found in the Administration Guide Add a Role Assignment or Principal Identity