Guide to Deploy the AXIGEN Outlook Connector via Active Directory

Active Directory contains a very useful feature which allows system administrators to automatically deploy software onto machines or users when the machine is booted or a user logs on. This document assumes you will be deploying software on a set of machines in which the user does not have local admin rights, so it will focus on the process to deploy onto the computers via the Computer Configuration GPO (Group Policy Object) settings.

Before proceeding, there are a few items you should be aware of:

  • In order to be automatically installed, a software application must have the form of an .MSI package, configured with minimal or no user interaction (for the AXIGEN Outlook Connector, the package is AXIOLK-1.0.0-BETA1.MSI)
  • Installation runs using the local computer domain account (NT AuthoritySystem). Authentication to the shared location containing the AXIOLK-1.0.0-BETA1.MSI package uses the local machines’ Kerberos cache.
  • Package Deployment configured under the Computer Configuration Group Policies is only pushed to Computers within the assigned Organizational Unit (OU) tree;
  • Package Deployment configured under the User Configuration Group Policies is only pushed to Users within the assigned Organizational Unit (OU) tree
  • The shared location containing the AXIOLK-1.0.0-BETA1.MSI package must grant Domain Computers at least READ access. Authenticated Users group is also sufficient.
  • The Group Policy Object must grant Read and Apply Group Policy rights to Domain Computers. Authenticated Users group is also sufficient.
  • To allow multiple administrators to change or redeploy a package, the Group Policy must contain these additional administrator groups with the appropriate read/write/modify rights.
  • Packages are only deployed upon the initial boot of a computer, or during the logon of a user, depending on how the Package Object is defined. Packages will NOT be deployed during the normal Security Settings refresh interval.
  • Once a Package is successfully deployed, it will NOT be redeployed unless it is manually redeployed or versioning is enabled.
For those familiar with creating Group Policies and the Software Settings Wizard, you may skip to the end of this document for a quick-check list of items that need to be set. Microsoft also has a few articles on how to publish software for deployment within Active Directory at
Also, a short Troubleshooting section in Appendix C has been included to cover some of the more common problems encountered when deploying software via Active Directory.

Verify the AXIGEN Outlook Connector Works before You Begin

Before you defining the GPO and Package Objects, first make sure that the AXIOLK-1.0.0-BETA1.MSI installer files work as you have planned. You may want to test the AXIOLK-1.0.0-BETA1.MSI file on the local computer account first. See the Troubleshooting section on how to obtain a command prompt as the NT AuthoritySystem account.

Defining the GPO and Package Object

Create a shared folder on a server, and grant Domain Computers at least READ access to it. Copy the AXIOLK-1.0.0-BETA1.MSI installation file to the share and make sure it also grants READ access to Domain Computers.

Create the Group Policy Object in the Active Directory Users and Computers application:
  1. Right click on the OU you wish to define the GPO on and select Properties
  2. Click the Group Policy tab and click New.
  3. Type a descriptive name for this new GPO (AXIGEN Outlook Connector – Deployment). Make sure you prefix the name with your Section/Division to avoid ambiguity.
  4. Click the Properties button, then select the Security tab. Add the Domain Computers group (or edit the existing Authenticated Users group) and assign the READ and APPLY GROUP POLICY rights to it.
  5. Click on the Edit button to edit this new Group Policy. Expand the Computer ConfigurationSoftware Settings tree on the left side of the screen. Right-click the Software Installation tree option and select the menu item NewPackage.
  6. An Open File dialog box should appear. Type in the UNC path to the server share where the AXIOLK-1.0.0-BETA1.MSI installer file is located. Select the AXIOLK-1.0.0-BETA1.MSI installer file and click Open. If you receive a ‘Cannot open file’ error, check the share permissions to make sure the account you are using the Active Directory Users and Computers application with has READ/WRITE access to the shared folder.
  7. Select the Assign radio button and click OK. The other Published and Advanced radio buttons are alternate ways to publish the AXIOLK-1.0.0-BETA1.MSI package. Published will not automatically install the AXIOLK-1.0.0-BETA1.MSI installer file, it will only create an entry in the local Add/Remove Programs utility for a later manual installation. Advanced will give you the ability to change certain properties such as the Package Name.
  8. You have now created and assigned the Package Object.
  9. Right click on the Package Object and select Properties.
  10. Click on the Security tab and add Domain Computers (or Authenticated Users if that is your scheme) to the security permissions. Make sure Domain Computers is given the READ right.
  11. Click the Advanced tab and select Domain Computers (or Authenticated Users if that is your scheme) and click Edit. Assign the List Contents, Read All Properties and Read Permissions checkboxes are selected.
  12. Close the Group Policy window.
  13. Close the GPO window.
  14. The AXIOLK-1.0.0-BETA1.MSI package has now been defined and is ready for deployment.
  15. Wait about 10-15 minutes for your changes to be replicated to the other Domain Controllers, and then reboot a machine contained within the OU you defined the GPO for.

Verifying the Installation

After rebooting a workstation contained within the OU you have defined the GPO Software Deployment policy for, an information box should appear on the screen after the Applying Security Settings messages stating it is installing the AXIOLK-1.0.0-BETA1.MSI package along with the name you defined in the Package Object advanced properties, or defaulting to the deployment name within the AXIOLK-1.0.0-BETA1.MSI installation file. After the workstation boots, log in and open the Event Viewer. Navigate to the Applications Event Viewer. A successful installation will have three informational entries indicating a successful AXIOLK-1.0.0-BETA1.MSI deployment. If there are any Errors, check the Event Viewer message to see what the failure reason was and consult the troubleshooting section below.

Redeploying the Package Object

You may wish to update the AXIOLK-1.0.0-BETA1.MSI installer file and redeploy the application to the targets. Keep in mind that once the computer successfully deploys the software package, it will not redeploy the application unless told to do so. To redeploy the Package Object:
  1. Open the Properties for the GPO defining the Package Object you have created. Edit the Policy by clicking on the Edit button.
  2. Right-click on the Package Object and select All Tasks > Redeploy Application.
  3. The package will now be marked for deployment at the next reboot of the targeted workstations.

APPENDIX A:Changing the Location of the AXIGEN Outlook Connector Installation File

In certain circumstances, it may become necessary to change the UNC path of the AXIOLK-1.0.0-BETA1.MSI installation file. The Active Directory Users and Computers application does not offer an interface to do so, but there are two alternative options. Either create a new Package object for software deployment or edit the existing Package Object with the ADSI editor. The ADSI editor is part of the Windows 2000 Resource Kit, and can be added to the MMC utility through the Add/Remove Snap-In selection.

To edit the existing package, you first need the CLSID of the existing Package Object:
  1. Open the GPO the Package Object is defined in, right click the Package Object and select Properties.
  2. Click the Deployment tab then click the Advanced button. Write down the Script Name location. You will need the long alphanumeric number directly after the Policies notation.
  3. Open the ADSI editor, connect it to your domain and navigate to the SystemPolicies tree on the left side of the window. Locate the CLSID you wrote down at the previous step.
  4. Expand this CLSID tree and then expand the following trees to get to the actual defined Package Object: CN=Machine CN=Class Store CN=Packages.
  5. Right click on the Package Object and select Properties. Navigate to the Optional property ‘Axiolk-1.0.0-Beta1.MSIFileList’. This property contains the UNC path of the location of the AXIOLK-1.0.0-BETA1.MSI Installer file. Edit this value to point to the new UNC path. Note the leading zero. It is possible to have multiple UNC paths defined for a Package Object, starting with 0: then 1: and so on. If you are changing the UNC path, type in the new UNC path, prefixed with 0: and click the Add button. Select the old UNC path and click the Remove button.
  6. The UNC path for the Package Object has now been updated to reflect the new UNC path. If you wish to redeploy the AXIOLK-1.0.0-BETA1.MSI Installer file again to all computers within the OU, go back into the Active Directory Users and Computers, locate the Package Object in the assigned GPO, right click the Package Object and select ‘Redeploy Application’

Appendix B: Creating Kerberos Service Principals

Since the local machine uses its local account’s Kerberos credential cache to authenticate to the server shared location containing the AXIOLK-1.0.0-BETA1.MSI Installation file, it must first request a HOST principal for the server hosting the share. Depending on the permissions set on the server computer object within Active Directory, this may be created automatically, or you may need to create it manually. If the permissions on the object allow for Full Control or Read/Write/Modify of SELF on the server computer object, after the next Active Directory registration of the server (usually after a reboot), the HOST service principal may be automatically created. One cautionary note on this: if the server is allowed to automatically update the properties on its own object, it will remove anything you had defined manually. For example, if you create the Package Object UNC path using the FQDN (server.domain.comshareAxiolk-1.0.0-Beta1.MSI), and server.domain.com is not the actual computer name of the server, the server will update Active Directory with the computer name instead (HOST/server instead of HOST/server/domain.com). In this case, there will be no HOST service principal for server.domain.com and the package installation will fail. It is recommended to prevent the server from auto-updating its own Active Directory object properties and define both the HOST/server and HOST/server.domain.com HOST service principals manually instead.

To create the HOST service principals manually, you need to use the ADSI editor. Open the ADSI editor and navigate to your server computer object. Navigate to the Optional servicePrincipalName attribute and add both the HOST/server and HOST/server.domain.com values. Set this value on all server computer objects that will be hosting shares for software deployment. Client workstations the software will be deployed on do not need to be modified.

Appendix C: Troubleshooting

Various steps performed during the GPO push of the AXIOLK-1.0.0-BETA1.MSI package may fail. The failures are often caused by incorrect permissions for the computer account to access the GPO, by the defined package, the physical package, or by authentication-related issues. Also, an improperly configured AXIOLK-1.0.0-BETA1.MSI setup file may cause installation failures. Microsoft has an excellent guide on troubleshooting GPO’s at
http://www.microsoft.com/windows2000/techinfo/howitworks/management/gptshoot.asp

Problem: You do not see the message box at startup stating the AXIOLK-1.0.0-BETA1.MSI package is being installed.

Resolution: There are a few possibilities that can contribute to this. First, check to make sure the target machine is located within the OU (or downstream OU) where the GPO containing the software deployment is applied. Also, check the permissions on the OU and GPO to make sure Domain Computers (or Authenticated Users) have both READ and APPLY GROUP POLICY rights. Also make sure the defined package object within the GPO has the necessary rights for Domain Computers. Alternatively, your GPO definition may not have fully replicated through the Active Directory domain. Either wait a while for replication to occur or, if you have Domain Admin rights, manually force Replication.

Problem: The Application Event Viewer indicates errors stating that the AXIOLK-1.0.0-BETA1.MSI package installation failed with a ‘Package source not located’ error.

Resolution: This indicates that the local computer read and tried to apply the GPO and AXIOLK-1.0.0-BETA1.MSI Package object, but could not access the physical AXIOLK-1.0.0-BETA1.MSI file. Check the permissions on the shared folder containing the AXIOLK-1.0.0-BETA1.MSI file to make sure Domain Computers (or Authenticated Users) have at least READ access rights. Also, check to make sure the Kerberos service principal (servicePrincipalName) is set correctly for the computer containing the share via the ADSI editor. It is also possible that the Package Object was created using the physically path (C:AppsInstaller.AXIOLK-1.0.0-BETA1.MSI) instead of the UNC path (servershareAXIOLK-1.0.0-BETA1.MSI). Alternatively, the Package Object may reference the FQDN of the share path (server.domain.comshareAxiolk-1.0.0-Beta1.MSI), but a HOST/server.domain.com Kerberos Service Principal does not exist.

You can manually verify the computer account has access to the share and AXIOLK-1.0.0-BETA1.MSI installer file by attempting to connect to the share using the local computer account (NT AuthoritySystem) by performing the following:
  1. On the target computer, log in as an administrator.
  2. Schedule an AT job for 1 minute ahead of the current time to launch a command prompt as NT AuthoritySystem:
    a.	C:> at 1:00pm /interactive cmd.exe
  3. After the command prompt window appears, you will have NT AuthoritySystem access. Attempt to list the contents of the share using the UNC path:
    a.	C:> dir servershare
    - You should receive a directory listing of the files on the share

Problem: Package seems to have been installed correctly by the Application Event Viewer messages, but the application does not seem to work.

Resolution: If your AXIOLK-1.0.0-BETA1.MSI installer file attempts to write to HKEY_CURRENT_USER in the registry, the installation may not be complete. Since the application is installed using the local computer account, no user is currently logged on, hence no available Current User profile exists. Instead, split the AXIOLK-1.0.0-BETA1.MSI installation into two parts and push the actual files and common registry keys via a Computer Configuration GPO, and define the CURRENT_USER registry keys in a separate User Configuration GPO. Also, make sure that the AXIOLK-1.0.0-BETA1.MSI installer file is able to silently install with little or no user intervention. Test the installation of your AXIOLK-1.0.0-BETA1.MSI installer file using the local computer account by following the technique listed above on how to obtain a command prompt as the NT AuthoritySystem account.

Problem: Cannot create GPO object.

Resolution: Make sure that the account you are using to run the Active Directory Users and Computers application has sufficient rights to create Group Policies. Usually, you must be a member of the Group Policy Creator Owners group, explicitly or implicitly by nested groups. See your local OU administrator to verify your group membership and to delegate the ability to create Group Policies.

Problem: The Deployment Counter on the Package Object is not increasing even though my clients were successful in installing the deployed package.

Resolution: If Domain Computers does not have WRITE privileges to the Package Object, this counter will always be zero. It is entirely up to you if you want to allow Domain Computers to be able to write in the properties of the defined Package Object, since this is only a counter, and does not indicate which machines actually have the AXIOLK-1.0.0-BETA1.MSI installed.

Problem: You updated the AXIOLK-1.0.0-BETA1.MSI installer file, but machines are not updated automatically.

Resolution: You must redeploy the Package Object within the GPO. Right-click on the Package Object and select All Tasks > Redeploy Application. Alternatively, use the built-in versioning techniques of Package Objects (see Microsoft Knowledge Base for more information on using versioning of Software Package Objects).

Problem: Other administrators cannot redeploy the software or edit the GPO. Only the original creator or Domain Administrators can.

Resolution: Check the security permissions on both the Package Object and the GPO to ensure intended administrators can Read/Write/Modify the objects accordingly.

Creating GPO’s for AXIOLK-1.0.0-BETA1.MSI Deployment Quick-Check List

1. Setup the Share and ensure Host Principals exist:
  • Setup a Windows Share on a server and grant either Domain Computers or Authenticated Users at least READ access (We recommend using Domain Computers at this point);
  • Make sure a ‘HOST/<shorthostname>’ and a ‘HOST/<host FQDN>’ principals exist for the servers object containing the share via the ADSI editor (servicePrincipalName attribute. E.g. HOST/server and HOST/server.domain.com).
2. Create the GPO:
  • Create a new GPO Computer Configuration > Software Settings for the software you wish to deploy. Make sure the package deployment path is the UNC path (e.g. myserverkit$AXIOLK-1.0.0-BETA1.MSI).
3. Create the Package object and apply permissions:
  • Make sure Domain Computers (or Authenticated Users) has READ permissions to the newly created Package. Also, make sure List Contents, Read All Properties and Read Permissions are selected in the Advanced security settings for the Package;
  • If other Administrators will have the ability to edit the Package settings (not the physical AXIOLK-1.0.0-BETA1.MSI file, but the Package object defined in the GPO), add their accounts or their Administrators group to the Package Security settings.
4. Assign permissions to the GPO itself:
  • Make sure Domain Computers (or Authenticated Users) has READ and APPLY GROUP POLCY to the GPO;
  • If other Administrators will have the ability to change the GPO, add their user accounts or their Administrators group to the GPO Security settings.
5. Assign the GPO to the OUs
  • Assign the new GPO to the OUs you wish to have the software deployed onto.
6. Replicate and Test:
  • Wait 5-10 minutes for Replication to occur;
  • Reboot target workstation and check event logs for installation failure messages.
You (as an administrator) can use Group Policy to assign or to publish software to users or computers in a domain. Additionally, it is useful to be able to deploy software based on group membership. A Group Policy object (GPO) is usually applied only to members of an organizational unit (OU) to which the GPO is linked. Because a user cannot be located in several OUs at the same time, you must be able to apply Group Policy settings outside the boundaries of OUs. This article describes how to have your software deployment policy applied to users who are not in an OU.

Assign a program to a group

  1. Create a folder to hold the Windows Installer package on a server. Share the folder by applying permissions that let users and computers read and run these files. Then, copy the MSI package files into this location.
  2. From a Windows Server 2003-based computer in the domain, log on as a domain administrator, and then start Active Directory Users and Computers.
  3. In Active Directory Users and Computers, right-click the container to which you want to link the GPOs, and then click Properties.
  4. Click the Group Policy tab, and then click New to create a new GPO for installing the Windows Installer package. Give the new GPO a descriptive name.
  5. Click the new GPO, and then click Edit. The Group Policy Object Editor starts.
  6. Right-click the Software Settings folder under either Computer Configuration or User Configuration, point to New, and then click Package.   

    Notes
    • The Software Settings folder under Computer Configuration contains software settings that apply to all users who log on to the computer. This folder contains software installation settings. It may also contain other settings that are put there by independent software vendors.
    • The Software Settings folder under User Configuration contains software settings that apply to users regardless of which computer they log on to. This folder also contains software installation settings. It may contain other settings that are put there by independent software vendors.
  7. In the Open dialog box, type the Universal Naming Convention (UNC) path of the Windows Installer file (.msi) for this package in the File name box, and then click Open.

    Note.

    • If the Windows Installer file resides on the local hard disk, do not use a local path. Instead, use the UNC path of the local computer to indicate the location of the installation files. A UNC path takes the form servernamesharenamepathfilename.msi.
  8. In the Deploy Software dialog box, do one of the following:
    • Click Assigned to specify that the application is deployed as assigned and that default settings are used for deployment properties.

    • Click Advanced to specify that you are manually editing the package properties instead of accepting the defaults. You can also choose between assign and publish for the deployment method.
  9. When you are prompted to choose between Advanced and Assigned, click Assigned unless you have to modify the advanced options.
  10. Click OK. The software package appears in the details pane of the Group Policy Object Editor.
  11. Close the Group Policy Object Editor.
  12. In the GPO Properties dialog box, click the GPO, and then click Properties.
  13. Click the Security tab.
  14. Click Authenticated Users in the Group or user names list, and then click Remove.
  15. Click Add, select the security group that you want this policy applied to, and then click OK to add the security group to the list.
  16. Select the security group, and then under Permissions for Users, click to select the READ and the Apply Group Policy check boxes in the Allow column.
  17. Click Apply, click OK, click Apply, and then click OK.
Changes to a GPO are not immediately applied on the target computers. Instead, changes are applied according to the current Group Policy update interval. You can use the Secedit.exe (gpupdate.exe /force) command-line tool to impose GPO settings upon a target workstation immediately.