How to replace SAML certificate with custom CA certificate in a Tenant Organization

Products

• VMware Cloud Director

Issue/Introduction

• The default certificate generated by the 'Regenerate Certificate' button creates a certificate with one year validity
• The regenerateFederationCertificate API creates a certificate with one year expiration.
• Need to use custom CA certificate for SAML authentication.
• Need to extend certificate validity to more than one year.

Environment

VMware Cloud Director 10.6.1

Resolution

Generate the certificate

1. Generate a certificate CSR.
   
   example:
   openssl req -x509 -newkey rsa:4096 -keyout samlkey.key -out samlcert.csr -sha256 -days 3650 -nodes
   
   
2. Send the CSR to your Certificate Authority(CA) for signing. CA should return to you a signed certificate in PEM format.

Import the Certificate to Cloud Director

1. Login to the Tenant portal as an Organization Administrator and then navigate to 'Administration → Certificate Management → Certificate Library'
2. Click the 'Import' button and proceed to import the certificate. Fill in certificate 'Friendly Name', Select the File, Enter the Passphrase if configured and Import. 
   
   Reference to Import Certificates to the Certificates Library Using Your VMware Cloud Director Tenant Portal if required.

Retrieve the URN of the newly imported certificate

1. Login to the Tenant portal as an Organization Administrator.
2. Click the inverted caret and select the 'API Explorer' link.
   
   
   
   
3. In the API Explorer page locate the API named /1.0.0/ssl/certificateLibrary. Select the API and then click the 'Try it out' button.
   
   
   
   
4. Click the 'Execute' button to run the API.
   
   
   
   
5. Scroll down the page and examine the 'Response body' content section. The response body will contain the details of all SSL certificates which are uploaded to the Tenant's Certificate Library. They are easily identifiable using the 'alias' value for each certificate. The 'alias' value you seek will match the Friendly Name which was provided earlier in the process while importing the certificate.
   
   
   1. Locate the SAML certificate which the Tenant wants to apply to their Organization by locating the 'alias' in the response body.
   2. Record the 'ID' value found on the line above the certificate 'alias'. This is the URN.
      
      example:
      "id": "urn:vcloud:certificateLibraryItem:12345678-####-####-########"

Retrieve the Org ID of the Tenant

1. Login to the Tenant portal as an Organization Administrator and open API Explorer as previously shown.
2. Locate the API named /1.0.0/orgs.
3. Execute the API and examine the response body.  Record the ID URN value of the Organization.
   
   example:
   "id": "urn:vcloud:org:222333##-####-####-####-########"

Update the Organization federation settings to use the custom SAML certificate

1. Login to the Cloud Director API using an API client of your choice. Refer to How to establish an API connection VMware Cloud Director if required.
2. Perform a GET request against the organization to confirm its current federation settings. The Org ID used here will match the Org URN identified previously.
   
   GET https://cloud.example.com/api/admin/org/222333##-####-####-####-########/settings/federation
   
   
3. Examine the API response body and locate the entries for  'SigningCertLibraryItemId' and 'EncryptionCertLibraryItemId'. 
   
   example:
   <SigningCertLibraryItemId>abcdefg###-####-####-####-########</SigningCertLibraryItemId>
<EncryptionCertLibraryItemId>9876####-####-####-####-########</EncryptionCertLibraryItemId>
   
   
4. Modify the  'SigningCertLibraryItemId' and 'EncryptionCertLibraryItemId' values. Overwrite the the existing values and apply the certificateLibraryItem URN ID identified earlier when querying the certificateLibrary API.
   
   example:
   <SigningCertLibraryItemId>12345678-####-####-########</SigningCertLibraryItemId>
   <EncryptionCertLibraryItemId>12345678-####-####-########</EncryptionCertLibraryItemId>
   
   
5. Perform a PUT request to the organization with the modified body. 
   
   PUT https://cloud.example.com/api/admin/org/222333##-####-####-####-########/settings/federation
   
   
6. Confirm the change is made by navigating to  'Administration -> Identity Providers -> SAML'  in the Tenant UI. The Certificate Expiration will match that which you set in your custom certificate.
   
   

Note: If a user clicks the 'Regenerate Certificate' button on the SAML UI page it will overwrite the change and reset the SAML certificate to use a default certificate with one year validity.

Additional Information

Note: VMware Cloud Director does not accept certificates whose signature algorithms use SHA1, for example, sha1WithRSAEncryption.

For further information on enabling SAML on an organization refer to: Enable Your VMware Cloud Director Organization to Use a SAML Identity Provider