LDAP over SSL - Modifying Active Directory with PHP

Some AD objects can be modified without running an ldaps connection. Things like passwords however, cannot.

This is a guide to getting ldaps running on a *nix machine.

1. Install OpenSSL and OpenLDAP
2. Install Certificate Services on your Domain Controller
3. Tell Apache how to use LDAPs
4. Troubleshooting

Install OpenSSL and OpenLDAP

Duh :) I presume you've done this already. If not, check your distribution specific documentation. Check that you have LDAP and OpenSSL support by performing creating a php webpage like:

<?php phpinfo(); ?>

And then viewing it on your server.

Install Certificate Services on your Domain Controller

There are two types of setup you can have here. The first is a Certificate Authority (CA) that is configured as an Enterprise CA on your local domain or as simply a request to a Third Party CA. The second type of CA is a Standalone CA on your local domain.

The request methods are very similar but without precise command line arguments you'll find one or other won't work correctly.

We'll try to document both methods here as best we can. Much of this information has been compiled through trial, error and testing on both development and live Domain Controllers

Enterprise or Third Party CA's

This guide is for using Enterprise or Third Party Certificate Authorities

LDAP over SSL is not enabled by default on domain controllers, you must configure this by installing Certificate Services.

If you follow this guide from Microsoft you should be able to get SSL enabled.

In my own installation I came across a few stumbling blocks that may or may not affect you. If you use an external CA for your SSL certificate, rather than an self-signed one you probably won't get this problem!

After generating the .req request file running the recommended certreq -new request.inf request.req and then using the Certification Authority console, and attempt to submit the request - no go. Lo and behold, |Microsoft KB 910249 came and bit me.

Certificate Request Processor

The request contains no certificate template information. 0×80094801 (-2146875391)
Denied by Policy Module 0×80094801, the request does not contain a certificate template extension or the Certificate Template request attribute.

Microsoft's resolution: Generate the request some other way.

Stuff that.

Here's the solution I found after 5 minutes with Google

certreq -submit -attrib "CertificateTemplate: DomainController" request.req

The key is the extra attribute we add to force use of the template. The certificate is issued.

However I still had a problem with a DNS error message. In the end I actually used the IIS based certificate manager at http(s)://<IP of server>/certsrv and issued the certificate that way, then back the Microsoft guide.

Standalone CA's

This guide is for running Standalone Certificate Authorities, they cannot follow the same processes as Enterprise level CAs and will result in errors when trying to accept the certificates to the domain controller

This is based on the information from the Microsoft TechNet Article: Advanced Certificate Enrollment and Management

Firstly from your domain controller, run the following .vbs script

Set oArgs = WScript.Arguments
Set oShell = WScript.CreateObject("WScript.Shell")
'
' Parse command line
'
if oArgs.Count < 1 then
    sTemplateName = "DomainController"
    sType = "E"
else
    if ((oArgs(0) = "-?") or (oARgs.Count < 2)) then
        Wscript.Echo "Usage: reqdccert.vbs [Templatename] [Type]"
        Wscript.Echo "[Templatename] is the name of a V2 template"
        Wscript.Echo "[Type]         can be E for Email and A for Authentication certificate"
        Wscript.Echo "If no option is specified, the DomainController certificate template is used."
        Wscript.Quit 1
    else
        sTemplateName = oArgs(0)
                sType = oArgs(1)
    end if
end if
Set oFilesystem = CreateObject("Scripting.FileSystemObject")
Set objSysInfo = CreateObject("ADSystemInfo")
Set objDC = GetObject("LDAP://" & objSysInfo.ComputerName)
sGUID = objDC.GUID
sDNShostname = objDC.DNShostname
sHostname = objDC.cn
'##############################################################################
'
' Create the ASN.1 file
'
'##############################################################################
Dim aASNsubstring(2, 5)
Const HEX_DATA_LENGTH = 1
Const ASCIIDATA = 2
Const HEXDATA = 3
Const HEX_BLOB_LENGTH = 4
Const HEX_TYPE = 5
aASNsubstring(0, ASCIIDATA) = sDNShostname
aASNsubstring(0, HEX_TYPE) = "82"
'
' Convert DNS name into Hexadecimal
'
For i = 1 to Len(aASNsubstring(0, ASCIIDATA))
    aASNsubstring(0, HEXDATA) = aASNsubstring(0, HEXDATA) & _
                                    Hex(Asc(Mid(aASNsubstring(0, ASCIIDATA), i, 1)))
Next
aASNsubstring(0, HEX_DATA_LENGTH) = ComputeASN1 (Len(aASNsubstring(0, HEXDATA)) / 2)
'
' Build the ASN.1 blob for DNS name
'
sASN = aASNsubstring(0, HEX_TYPE) & _
       aASNsubstring(0, HEX_DATA_LENGTH) & _
       aASNsubstring(0, HEXDATA)
'
' Append the GUID as other name
'
if (sType = "E") then
    aASNsubstring(1, HEXDATA) = sGUID
    aASNsubstring(1, HEX_TYPE) = "A0"
    aASNsubstring(1, HEX_DATA_LENGTH) = ComputeASN1 (Len(aASNsubstring(1, HEXDATA)) / 2)
    sASN = sASN & _
           "A01F06092B0601040182371901" & _
           aASNsubstring(1, HEX_TYPE) & _
           "120410" & _
           aASNsubstring(1, HEXDATA)
end if
'
' Write the ASN.1 blob into a file
'
Set oFile = oFilesystem.CreateTextFile(sHostname & ".asn")
'
' Put sequence, total length and ASN1 blob into the file
'
oFile.WriteLine "30" & ComputeASN1 (Len(sASN) / 2) & sASN
oFile.Close
'
' Use certutil to convert the hexadecimal string into bin
'
oShell.Run "certutil -f -decodehex " & sHostname & ".asn " & _
                                       sHostname & ".bin", 0, True
'
' Use certutil to convert the bin into base64
'
oShell.Run "certutil -f -encode " & sHostname & ".bin " & _
                                    sHostname & ".b64", 0, True
'##############################################################################
'
' Create the INF file
'
'##############################################################################
Set iFile = oFilesystem.OpenTextFile(sHostname & ".b64")
Set oFile = oFilesystem.CreateTextFile(sHostname & ".inf")
oFile.WriteLine "[Version]"
oFile.WriteLine "Signature= " & Chr(34) & "$Windows NT$" & Chr(34)
oFile.WriteLine ""
oFile.WriteLine "[NewRequest]"
oFile.WriteLine "KeySpec = 1"
oFile.WriteLine "KeyLength = 1024"
oFile.WriteLine "Exportable = TRUE"
oFile.WriteLine "MachineKeySet = TRUE"
oFile.WriteLine "SMIME = FALSE"
oFile.WriteLine "PrivateKeyArchive = FALSE"
oFile.WriteLine "UserProtected = FALSE"
oFile.WriteLine "UseExistingKeySet = FALSE"
oFile.WriteLine "ProviderName = " & Chr(34) & _
                "Microsoft RSA SChannel Cryptographic Provider" & Chr(34)
oFile.WriteLine "ProviderType = 12"
oFile.WriteLine "RequestType = PKCS10"
oFile.WriteLine "KeyUsage = 0xa0"
oFile.WriteLine ""
oFile.WriteLine "[EnhancedKeyUsageExtension]"
oFile.WriteLine "OID=1.3.6.1.5.5.7.3.1"
oFile.WriteLine "OID=1.3.6.1.5.5.7.3.2"
oFile.WriteLine ";"
oFile.WriteLine "; The subject alternative name (SAN) can be included in the INF-file"
oFile.WriteLine "; for a Windows 2003 CA."
oFile.WriteLine "; You don't have to specify the SAN when submitting the request."
oFile.WriteLine ";"
oFile.WriteLine "[Extensions]"
iLine = 0
Do While iFile.AtEndOfStream <> True
    sLine = iFile.Readline
    If sLine = "-----END CERTIFICATE-----" then
        Exit Do
    end if
    if sLine <> "-----BEGIN CERTIFICATE-----" then
        if iLine = 0 then
            oFile.WriteLine "2.5.29.17=" & sLine
        else
            oFile.WriteLine "_continue_=" & sLine
        end if
        iLine = iLine + 1
    end if
Loop
oFile.WriteLine "Critical=2.5.29.17"
oFile.WriteLine ";"
oFile.WriteLine "; The template name can be included in the INF-file for any CA."
oFile.WriteLine "; You don't have to specify the template when submitting the request."
oFile.WriteLine ";"
oFile.WriteLine ";[RequestAttributes]"
oFile.WriteLine ";CertificateTemplate=" & sTemplateName
oFile.Close
iFile.Close
'##############################################################################
'
' Create the certreq.exe command-line to submit the certificate request
'
'##############################################################################
Set oFile = oFilesystem.CreateTextFile(sHostname & "-req.bat")
oFile.WriteLine "CERTREQ -attrib " _
                 & Chr(34) & "CertificateTemplate:" & sTemplateName _
                 & Chr(34) & " " & sHostname & ".req"
'
' The GUID structure needs to be reconstructed. The GUID is read
' as a string like f4aaa8576e6828418712b6ca89fbf5bc however the
' format that is required for the certreq command looks like
' 57a8aaf4-686e-4128-8712-b6ca89fbf5bc. The bytes are reordered
' in the following way:
'
'                            11111111112222222222333
'             Position 12345678901234567890123456789012
'                      |------|--|--|--|--------------|
' Original GUID:       f4aaa8576e6828418712b6ca89fbf5bc
'
'                            11 1 1111 1112 222222222333
'             Position 78563412 1290 5634 7890 123456789012
'                      |------- |--- |--- |--- |----------|
' Reformatted GUID:    57a8aaf4-686e-4128-8712-b6ca89fbf5bc
'
oFile.WriteLine "REM "
oFile.WriteLine "REM !!! Only valid for Windows 2003 or later versions !!!"
oFile.WriteLine "REM If you do not specify certificate extensions in the *.INF file"
oFile.WriteLine "REM they can be specified here like the following example"
oFile.WriteLine "REM "
oFile.WriteLine "REM CERTREQ -submit -attrib " _
                 & Chr(34) & "CertificateTemplate:" & sTemplateName _
                 & "\n" _
                 & "SAN:guid=" _
                 & Mid(sGUID, 7, 2) _
                 & Mid(sGUID, 5, 2) _
                 & Mid(sGUID, 3, 2) _
                 & Mid(sGUID, 1, 2) & "-" _
                 & Mid(sGUID, 11, 2) _
                 & Mid(sGUID, 9, 2) & "-" _
                 & Mid(sGUID, 15, 2) _
                 & Mid(sGUID, 13, 2) & "-" _
                 & Mid(sGUID, 17, 4) & "-" _
                 & Mid(sGUID, 21, 12) _
                 & "&DNS=" & sDNShostname & Chr(34) & " " & sHostname & ".req"
oFile.Close
'##############################################################################
'
' Create the certificate verification script
'
'##############################################################################
Set oFile = oFilesystem.CreateTextFile(sHostname & "-vfy.bat")
oFile.WriteLine "certutil -viewstore " & Chr(34) & objDC.distinguishedname & _
                "?usercertificate" & chr(34)
oFile.Close
'##############################################################################
'
' Compute the ASN1 string
'
'##############################################################################
Function ComputeASN1 (iStrLen)
    If Len(Hex(iStrLen)) Mod 2 = 0 then
        sLength = Hex(iStrLen)
    else
        sLength = "0" & Hex(iStrLen)
    end if
    if iStrLen > 127 then
        ComputeASN1 = Hex (128 + (Len(sLength) / 2)) & sLength
    else
        ComputeASN1 = sLength
    End If
End Function

This will create the following files

• DC_Name.asn
• DC_Name-req.bat
• DC_Name-vfy.bat
• DC_Name.b64
• DC_Name.bin
• DC_Name.inf

The only two files we are interested in are the .inf and .asn files.

Now from the command line prompt call the following (replacing request.inf with the actual names of your files)

certreq -new request.inf request.req

This will create a file called request.req

We then copy the request.req and the .asn files over to the CA. This is where things get more complicated.

Again from the command line we need to run

certreq -attrib "CertificateTemplate:DomainController" request.req

This will give us a request ID, this is important, make a note of it.

certutil -setextension <RequestID> 2.5.29.17 1 @<dcname>.asn

What Microsoft also doesn’t tell you here, is that if you are using Windows Server 2008, this command will not work unless you have loaded the command prompt with elevated priviledges (UAC). The subject alternative name, which is identified by the object identifier 2.5.29.17, is set with the attributes that are defined in the <dcname>.asn file. The fourth parameter that is set to “1” marks the extension as critical.

The TechNet ‘Processing Domain Controller Certificates‘ article mentions how to validate the certificate request is good, however we are assuming these tests come back as positive so next we need to issue and retrieve the certificate.

From the CA now run

certutil –resubmit <RequestID>

and then finally

CERTREQ -retrieve <RequestID> <dcname>.cer <dcname>.p7b

You will now have a .cer and a .p7b file which you can copy back to the domain controller.

To install the certificate, from the command line on the domain controller

CERTREQ -ACCEPT <dcname>.p7b

Microsoft tells you to restart the Domain Controller. In our experience this was not necessary and SSL over LDAP was available immediately

Export the CA Certificate

Apparently you are supposed to now export the CA certificate, and for some installations you may need to do this, and install it on your web server. I have not had to do this in any of my tests. In my tests, after installing the certificate on the domain controller I was able to connect over LDAPS immediately.

Tell Apache how to use LDAPs

Do a phpinfo() and check where the HOME variable points to in the Apache environment. Create a symbolic link or copy ldap.conf to this location.

If you get a connect error may be because your local OpenSSL installation doesn't recognise the certificate (or its authority) provided by the server. This can be circumvented by adding the following line to ldap.conf on your server or similar:

Change TLS_REQCERT allow to TLS_REQCERT never

Apache must be able to read ldap.conf, you cannot skip this step.

Troubleshooting

☹

Unable to bind to server: Can't contact LDAP server

This is probably the most generic error. Use the console to check to make sure you can actually get a connection. There's no point chasing problems in PHP if you can't do it from the console.

ldapsearch -H "ldaps://dc01.mydomain.local" -b "" -s base -Omaxssf=0

The ldapsearch should spit back a whole bunch of stuff. If it doesn't, you need to troubleshoot the error message it gives you. Optionally add -d7 (debug level) to the command line above.

From the domain controller itself you can test if LDAP over SSL works

1. Start the Active Directory Administration Tool (Ldp.exe).
2. On the Connection menu, click Connect.
3. Type the name of the domain controller to which you want to connect.
4. Type 636 as the port number.
5. Click OK

RootDSE information should print in the right pane, indicating a successful connection.