Monday, March 1, 2010

How to Securely Deploy iPhones with Exchange ActiveSync - Phase 3 - Publishing User Certificates to Active Directory

This is the fourth post in my series, How to Securely Deploy iPhones with Exchange ActiveSync in the Enterprise. To read an overview of the solution click here. In this phase, we will publish the same user certificate to each user object in Active Directory that is a member of the ActiveSync Users security group.

As mentioned earlier, ActiveSync will be configured to require user certificates for authentication.  This means that the user needs a user certificate with the private key and ActiveSync will check this certificate for a matching certificate in Active Directory.  We need to publish the user accounts in Active Directory, as shown below.


When you view the properties of the published certificate, you see that it was issued by the CA (W2K8R2-CA) and that the certification path is valid, since we published the root CA certificate to all machines in the domain using Group Policy in Phase 2.


While this is a fairly simple process to do, I wrestled with different ways of doing it programmatically.  I finally decided to use VBScript to publish the certificate to AD.  I chose VBScript instead of PowerShell because I could not be certain that the ActiveSync Administrator(s) would have PowerShell installed.

The script uses CAPICOM, which is a security technology from Microsoft that allows Microsoft Visual Basic, Visual Basic Script, ASP, and C++ programmers to easily incorporate digital signing and encryption into their application.  To use CAPICOM, you must download and register the CAPICOM.DLL on the computer that runs the script.  The script automatically registers the DLL, as long as it resides in the same network share where the ActiveSync user certificate resides.

First, download CAPICOM and extract the contents to get the CAPICOM.DLL file (we have no need for any of the other files or examples).  Then create a network share that the mobile administrators have access to (for example \\fileserver\iPhone).  Copy the CAPICOM.DLL, the ActiveSyncUser.cer user certificate (exported in Phase 1), and the vbscript below to the share.  You will need to edit the script to reflect the name you used for your ActiveSync Users group in AD, the path to CAPICOM.DLL and the user certificate, and the name of the user certificate if necessary.

Here's the Publish Mobile Cert.vbs script:

'======================================================================================================================================
'Publish Mobile Cert.vbs -
The admin running the script must have rights to modify the user accounts that are members of the ActiveSync Users group in AD.

'Jeff Guillet
'02/10/2010
'
'This script publishes the mobile user certificate into Active Directory for all members of the ActiveSync Users security group
'
'Micosoft link for CAPICOM: http://www.microsoft.com/downloads/details.aspx?displaylang=en&FamilyID=860EE43A-A843-462F-ABB5-FF88EA5896F6
'=======================================================================================================================================


On Error Resume Next


'Configure constants
Const ADS_PROPERTY_UPDATE = 2
Const ADS_PROPERTY_APPEND = 3


'--------------------------------------------------------------------------
'Modify the three variables below, as required
'--------------------------------------------------------------------------
eASUsersGroup = "ActiveSync Users"
pathToFiles = "\\fileserver\iPhone\"
certFile = "ActiveSyncUser.cer"
'--------------------------------------------------------------------------


msg = "This script publishes the '" & certFile & "' certificate to all members of" & vbCRLF
msg = msg & "the '" & eASUsersGroup & "' security group. Do you want to continue?"
r = MsgBox(msg, vbYesNo + vbQuestion, "Publish Mobile Cert")
If r = vbNo then Wscript.Quit


'Create log file
Set fso = CreateObject("Scripting.FileSystemObject")
Set FullLog = fso.OpenTextFile(pathToFiles & "Publish Mobile Cert.log", 8, True)


'Check for and set dependencies
'--Check for CAPICOM.DLL
Set FSO = CreateObject("Scripting.FileSystemObject")
If NOT FSO.FileExists ("C:\Windows\System32\capicom.dll") Then
If NOT FSO.FileExists (pathToFiles & "capicom.dll") Then
MsgBox pathToFiles & "capicom.dll is missing. Cannot continue.", vbCritical, "Missing File"
Wscript.Quit
Else
FSO.CopyFile pathToFiles & "capicom.dll", "C:\Windows\System32\"
End if
End if
'--Check for certificate
If NOT FSO.FileExists (pathToFiles & certFile) Then
MsgBox pathToFiles & certFile & " is missing. Cannot continue.", vbCritical, "Missing File"
Wscript.Quit
End If
'--Register CAPICOM.DLL
Set WshShell = WScript.CreateObject("WScript.Shell")
Return = WshShell.Run("regsvr32 C:\Windows\System32\capicom.dll /s", 0, true)

'Load the certificate file and convert it to Base-64
Set Certificate = CreateObject("CAPICOM.Certificate")
Certificate.Load pathToFiles & certFile
BinaryEncodedCertificate = Certificate.Export(CAPICOM_ENCODE_BINARY)
Set Utilities = CreateObject("CAPICOM.Utilities")
ArrayEncodedCertificate = Utilities.BinaryStringToByteArray(BinaryEncodedCertificate)

'Configure connection to Active Directory
Set con = CreateObject("ADODB.Connection")
con.Provider = "ADsDSOObject"
con.Open "DS Query"
Set command = CreateObject("ADODB.Command")
Set command.ActiveConnection = con
command.Properties("searchscope") = 2
command.Properties("Page Size") = 20000
command.Properties("Timeout") = 180

'Get default domain
Set oRoot = GetObject("LDAP://rootDSE")
oDomain = "LDAP://" & oRoot.Get("defaultNamingContext")

'Construct and execute query to get the eASUsersGroup
command.CommandText = "SELECT AdsPath FROM '" & oDomain & "' WHERE name = '" & eASUsersGroup & "' AND objectClass = 'Group'"
Set rs = Command.Execute

'Append to the log file
FullLog.writeline String(75, "=")
FullLog.writeline "Publish Mobile Cert.vbs"
FullLog.writeline Now
FullLog.Writeline "Adding the mobile user certificate to the following users:"
FullLog.writeline String(75, "-")

'Loop through the result set
Do While NOT rs.EOF
Set oGroup = GetObject(rs.fields(0))
groupDN = oGroup.distinguishedName
'Publish the certificate to each member of the group
For Each Member In oGroup.Members
userCount = userCount + 1
'Append the certificate to the user's certificate store in Active Directory
Set UserObj = GetObject("LDAP://" & member.distinguishedName)
UserObj.PutEx ADS_PROPERTY_APPEND, "userCertificate", Array(ArrayEncodedCertificate)
UserObj.SetInfo
If Err.Number = 0 Then
FullLog.writeline member.distinguishedName
Else
FullLog.writeline "Unable to update user: " & member.distinguishedName
errorCount = errorCount + 1
End If
Next
Exit Do
Loop

FullLog.writeline String(75, "=") & vbCRLF & vbCRLF

msg = "Successfully published the certificate to " & userCount - errorCount & " user accounts." & vbCRLF
msg = msg & "Review the Publish Mobile Cert.log for details."
If errorCount > 0 Then
msg = msg & vbCRLF & vbCRLF & errorCount & " error(s) were encountered."
MsgBox msg, vbExclamation, "Publish Mobile Cert"
Else
MsgBox msg, vbInformation, "Publish Mobile Cert"
End If
Here's a link to the script for those of you averse to copying and pasting.

To run the script you must have rights to modify the user accounts that are members of the ActiveSync Users security group.  Simply double-click the script to run it.  The script will register CAPICOM.DLL, connect to Active Directory and search for the ActiveSync Users group, enumerate all the members of the group, and publish the ActiveSync user certificate to each user.  A log file is generated in the folder path specified in the script each time it is run.

We have now completed publishing the ActiveSync user certificate to the user accounts in Active Directory that are members of the ActiveSync Users group.



This concludes Phase 3 of my series, How to Securely Deploy iPhones with Exchange ActiveSync in the Enterprise. The next phase will cover how to create the iPhone Configuration Profile using Apple's iPhone Configuration Utility.

Other articles in this series:

7:02 PM