Sunday, February 9, 2014

vCAC - Automatically Manage Local Administrator AD Groups

In my last post, we covered adding the VM requester's AD account to local administrators on the guest.  This is a quick and dirty way to getting the machine requester up and running with their new VM.  However, many organizations prefer to use AD security groups for this kind of access.  In fact, if you use an AD group to control local admins for a Windows VM, then you can create actions for the provisioned VM so that the owner can assign local admin to whomever they wish.

In this post we will cover the following use case - a new VM is requested and as it is being provisioned, a new AD security group will be created in a designated OU with the name of the VM and some custom suffix (like "vmname-localadm").  The requester of the VM will be placed into this group by default and the new group will be added to local admins on the machine after it has been built and customized.

To perform these tasks we will use vCenter Orchestrator (vCO)as well as the vCAC Guest Agent.  In summary, the tasks will be performed in this order:

  - a new machine is requested (and approved if necessary)
  - the machine build begins and a host name is created
  - a vCO workflow is called to create the security group and add the machine requester to the new group
  - the machine is built and customized by vCenter (including domain join)
  - the Guest Agent runs a VBScript on the machine to add the new security group to local admins
  - when the machine is destroyed, a vCO workflow is called to delete the security group

There are a few requirements for this that will not be covered here.  I have provided links to help you get started with those requirements where appropriate, otherwise you should be able to address them with the VMware documentation.

  - vCAC Advanced Services set to use embedded vCO (just check Administration > Advanced Services > Server Configuration and make sure the default Orchestrator server is selected)
  - vCAC endpoint created for the embedded vCO instance

The scripts and vCO workflows below are provided as-is and should always be evaluated and tested before running.  I make no warranty nor provide support.

You will need to add the VBScript below to your VM template.  This script will be called by the Guest Agent to complete the task of assigning the security group to local admins on the new VM.  Be sure to check to see that the file is not blocked.

Now you will need to import a vCO package I created to do this work.  It contains two top level workflows which will be called from vCAC workflow "stubs" - download here.

This is most easily done from vCAC under Administration > Advanced Services > Import Workflow Packages as shown below.  If you are comfortable importing a package from the vCO client you may choose to do it that way to see all the elements that will be brought in and note any conflicts.

Once imported there are two vCAC Extensibility workflows you will need to run in vCO client to associate the "Create" and "Delete" workflows with the appropriate vCAC workflow stubs.

First, run the workflow Library  > vCloud Automation Center > Extensibility > Workflow stubs > "Assign a state change workflow to a blueprint and its virtual machines."

-Select the "BuildingMachine" workflow stub and set the vCAC Host to your IaaS host.
-Click next
-Under the blueprints selection, browse to and select the blueprint(s) that will trigger the workflow stub during the provisioning state
- Do not apply operations to existing machines
- Click next
- The "End user workflow to run" will be the workflow > Manage Local Administrator > "vCAC Create Local Admin Security Group"
- Select YES for "Add vCO workflow inputs as blueprint properties
- Select NO for "Add last vCO Workflow run input values...."
- Click Submit

Next, run the workflow again, but use the following settings:

-Select the "MachineDisposing" workflow stub
- The "End user workflow to run" will be > Manage Local Administrators > "vCAC Delete Local Admin Security Group"

Now within vCAC Infrastructure > Blueprints look at the blueprint you configured for the workflow stubs.  You will find that custom properties have been created (noted by the red boxed area).  You will need to modify two properties:

 - ExternalWFStubs.BuildingMachine.strGroupSuffix should be set to the security group suffix you want to use.  The result will be a group called - for example, WINSRV01-LocalAdmins.

  ExternalWFStubs.BuildingMachine.strTargetOU should be the AD OU where you would like the group to be created.  You MUST have created this OU and you cannot use the standard Users container in AD.

To activate the guest agent and have it run the VBScript above, you will need to add properties in the green boxed area.  NOTE that the ScriptPath property should reflect the path and filename of the VBScript (may be different than pictured) but the items in curly brace should look exactly as they do in the example above.

At this point you are ready to test this out by deploying a machine from the blueprint.  Note that I have only tested with 6.0 but it should work with 5.2.


  1. Hi John,
    Great article. thanks for posting it.
    I followed the steps and getting "TypeError: Cannot read property "userGroups" from null (Dynamic Script Module name : getUsergroupFromContainer#52995)"

    In addition to the properties shown in your screen shot, 3 more added in my case.

    Any idea why?

    Thank you

    1. Have you configured the AD plugin in vCO?

    2. yes I have the AD plugin configured.

    3. Have you already created the Target OU (container) in AD?

    4. Yes I have the AD OU container but it has space in it. I wonder if that makes it fail.
      Getting "TypeError: Cannot read property "userGroups" from null (Dynamic Script Module name : getUsergroupFromContainer#52995)"
      It seems ouTarget is blank.

    5. Well, in my example above I used an OU with a space in the name for the ExternalWFStubsBuildingMachine.strTargetOU custom property value. Verify that you have entered the custom property name correctly.

    6. Thanks John, somehow the value of ouTarget is passing blank. even though custom property strTargetOU is passing the value for OU.

    7. The workflow "vCAC Create Local Admin Security Group" should create a log entry like ""Found target OU " with the OU name. Do you see that in the workflow log?

    8. yep , it is creating the AD group now. I had been passing full OU path and not realizing it is searching by just OU name.

      Now failing at getAttribute
      TypeError: Cannot call method "getAttribute" of null (Workflow:Create AD Group and add user / Set Group Name Consistently (item12)#55024)

      Thanks again

    9. Is it creating the user group in AD? That should happen just prior to this error.

    10. yes it is creating and then fails with this error

    11. Would you email me at diasj - at - vmware - dot - com? I need more information and logs/screenshots of what you are seeing. Thanks.

    12. Hi John, I just emailed you the log and screenshot.

    13. Hi John,

      great stuff, we use this in our environment!

      We just moved on to vRA 7.1.
      Are you planning on making an updated version for vRA 7.1? We would love to see that! :)

    14. You should be able to use this within the 7.1 framework. But instead of work flow stubs, you should leverage the event broker.

  2. Hi John, that link to download the work flows didn't work

    1. Thank you, kind stranger. I've corrected the link.

  3. Hi John. Were you ever able to figure out the issue of Cannot call method "getAttribute" of null (Workflow:Create AD Group and add user / Set Group Name Consistently (item12)#55024). We have an odd issue where everything works if the group starts with A-L, but then fails with anything after that. We have 2 domains and it works fine on everything for one domain, but not the other. Probably a DC issue, but just wanted to see if you have seen it before

  4. Someone there who implemented this using Event Broker in vRA 7.3? I suppose Eventbroker does not pass vCAC:Entity and vCAC:VirtualMachine. I get Errors like:

    Error in state VMPSMasterWorkflow32.BuildingMachine phase PRE event (queue = 942545c8-ff04-4fd5-9007-4f16dc2eb187): Extensibility consumer error(20999) - TypeError: Cannot call method "getProperties" of null (Workflow:Get Owner and Machine Name / Scriptable task (item2)#54823) and SRV-AS1325