vCloud Director: Federation certificate expiration emails / Certificate regeneration troubles in large environments

Hi, this is Daniel and this is my first post about a small gotcha you might experience with VMware vCloud Director and the surprising resumé that there is no automated solution for fixing that.

Since vCloud Director 5.1 it is possible to enable your organization to use an SAML Identity provider. And even if you don’t use it, vCloud Director seems automatically to generate a certificate behind the scenes which expires after one year for every organization you have.

Some time before this certificate expires, you or your customers may receive automated email warnings about the expiry of a federation certificate in your virtual datacenter. Unfortunately vCloud Director does not check if this message is really relevant to you and your environment. Here are my findings regarding this issue so far.

There are three possibilities how to handle it:

  • Manual
  • Database
  • PowerCLI/API (vCloud Director 5.6)

If you are not using the SAML Identity Provider, there is a manual process how to regenerate a federation certificate:

  1. Log into your vCloud Director Environment
  2. Navigate to the Administration tab
  3. Choose the Federation link in the Settings menu on the left hand side
  4. Check if the “Use SAML Identity Provider” is selected. In this case you are using the SAML Identity Provider and you should stop here.
  5. Scroll down to the bottom of the page and click the “Regenerate” button.

The expiration date will be updated and it will be valid for one year. So, as a happy VMware long-timer user, the certificate will expire again and you might have to repeat this process again and again. And -even worse- imagine you have hundreds of organizations (or more)? I tought there had to be a way to automate this. Otherwise this would be a really annoying task.

In VMware KB 2078249 there are some additional notes on how to extend the certificate expiry with an update on the vCloud Director database. You could use this as a starting point. But this does not work if you use SSO for authentication. While searching around the vCloud Director (Version 5.5) database, I found the table IDENTITY_PROVIDER. The field PROVIDER_TYPE contains SAML (organization uses SAML) or INTEGRATED (organization uses integrated provider). You could use this information to check if it is safe to update the federation settings. But: This is not verified by VMware. Use at your own risk.

I hoped there would be a cleaner solution to this and started a new PowerCLI session. (We are using PowerCLI 5.8 Release 1.)

$Org = Get-Org -Name Testing
$Org.ExtensionData.Settings.OrgFederationSettings

SAMLMetadata          :
Enabled               : False
CertificateExpiration :
Client                : VMware.VimAutomation.Cloud.Views.CloudClient
Href                  :
Type                  :
Link                  :
AnyAttr               :
VCloudExtension       :

As you can see in the highlighted line, SAML is disabled for this organization. Let’s check the members of this object.

$Org.ExtensionData.Settings.OrgFederationSettings | Get-Member

   TypeName: VMware.VimAutomation.Cloud.Views.OrgFederationSettings

Name                            MemberType Definition
----                            ---------- ----------
Equals                          Method     bool Equals(System.Object obj)
GetHashCode                     Method     int GetHashCode()
GetType                         Method     type GetType()
RegenerateFederationCertificate Method     void RegenerateFederationCertificate()
ToString                        Method     string ToString()
UpdateServerData                Method     VMware.VimAutomation.Cloud.Views.OrgFederationSettings UpdateServerData()
UpdateViewData                  Method     void UpdateViewData()
AnyAttr                         Property   VMware.VimAutomation.Cloud.Views.XmlAttributeCollection AnyAttr {get;set;}
CertificateExpiration           Property   System.Nullable[datetime] CertificateExpiration {get;set;}
Client                          Property   VMware.VimAutomation.Cloud.Views.CloudClient Client {get;}
Enabled                         Property   System.Nullable[bool] Enabled {get;set;}
Href                            Property   string Href {get;set;}
Link                            Property   VMware.VimAutomation.Cloud.Views.LinkCollection Link {get;set;}
SAMLMetadata                    Property   string SAMLMetadata {get;set;}
Type                            Property   string Type {get;set;}
VCloudExtension                 Property   VMware.VimAutomation.Cloud.Views.VCloudExtension[] VCloudExtension {get;set;}

In the highlighted line we found a RegenerateFederationCertificate method. This looked very promising.

$Org.ExtensionData.Settings.OrgFederationSettings.RegenerateFederationCertificate()
Exception calling "RegenerateFederationCertificate" with "0" argument(s): "Object reference not set to an instance of an object."
At line:1 char:1
+ $Org.ExtensionData.Settings.OrgFederationSettings.RegenerateFederationCertificat ...
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    + CategoryInfo          : NotSpecified: (:) [], MethodInvocationException
    + FullyQualifiedErrorId : NullReferenceException

Unfortunately, it threw an exception and I could not get any detailed information about it. But I did a quick research in the vCloud Director API spec. In vCloud Director 5.1 and 5.5 I could not find any method related to this. This might be the reason why it failed. So you have to do it manually or direct in the vCloud Director Database for these versions.

So what is the outcome of this observation? As it seems there is currently no supported and automated way on how to get around this issue. Too bad.

But vCloud Director 5.6 got a new RegenerateFederationCertificate API call. Unfortunately I can not test this in my environment at the moment. So just give it a try. If PowerCLI doesn’t work you can still use the REST API directly.

Any suggestions and feedback welcome!

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: