Certificates, we all need them to secure our corporate resources, and when it comes to mass deploying them there are many solutions at hand to do so. Going from individual certificates uploaded to MDM profiles, AD bound certs and SCEP, to a external CA like Symantec. But one other solution in that mix, and maybe my favourite one, is the Jamf ADCS connector.

The reason for this is the simplicity of integrating it in Jamf Pro and the fact that you don’t need to make much resources available to do so. But, as straight forward as things might be, there are always some potential gotcha’s to keep in mind. So let’s take a quick look at how to install the ADCS Connector, and some of the most common reasons for it not to work.

As always, the pre-reqs and yes… the manual:

Now, before we continue, let’s first pause a moment and have a look at the network diagram. As always, when things don’t work… it must be the network. Ok, not always, but still when troubleshooting integrations like this one I would always dare to put a bet on “it’s the network” 🙂 the odds on this are always better than any casino game 🙂

On-prem Jamf Pro:

JamfCloud

With this, the network requirements should be clear, so let’s have a look at the installation process.

As said, we need an AD bound Windows 2016 Server on which we’ll run the ADCS Connector installer… Yes, it’s really as simple as that, but there are some gotcha’s!

First of all, you will need to allow the execution of scripts in PowerShell. If you don’t, you will see the following error:

So, before trying the installation command, open PowerShell, and run:

Set-ExecutionPolicy unrestricted

Now we are ready to run the installer. However, make sure that you are in the working directory where the .deploy script of the ADCS connector is located, AND make sure to change the FQDN and JAMFPRODN in the command:

  • ‘- fqdn’ is the Fully Qualified Domain Name of your ÁDCS Connector server, resolvable from your Jamf Pro server (public DNS if JamfCloud)
  • ‘- jamfProDn’ is your Jamf Pro URL

DO NOT use IP addresses!

.\deploy.ps1 -fqdn my.adcs-proxy.url -jamfProDn my.domain.name -cleanInstall

(no http or https in both addresses)

If you want to crosscheck the ADCS Connector FQDN run the following in PowerShell:

[System.Net.Dns]::GetHostByName($env:ComputerName)

The installer does not take much time, but be careful! DO NOT close the PowerShell upon completion of the installer! The reason for this is that the installer will create 2 certificate which you will need to upload in Jamf Pro: one adcs-proxy-ca certificate and one client-cert certificate. Those will be created within the folder you are running the installer from:

NOTE: the client-cert certificate will be protected by a randomly generated password, which will be communicated in PowerShell upon completion of the installation. Keep the PowerShell open or copy that password temporarily to a text editor. We'll need this password to integrate the ADCS connector in Jamf Pro.  If you lose it, you will need to run the ADCS Connector installer again!

With our ADCS Connector installed, our 2 certs and the client password at hand, we can now integrate the connector in Jamf Pro > Settings > Global Management > PKI > Certificate Authorities

Click on ‘Configure New Certificate Authority’, and add the following details:

  • Fully Qualified Domain Name: this is the FQDN of the CA, which needs to be resolvable from the Jamf Pro server
  • CA Name: the name of your certificate Authority
  • URL/IP address: this is the FQDN of the Jamf adcs Connector server. As said above, best practice is not to use IP addresses, but a fully qualified domain name instead. As the connection is linked to the certificates we are going to upload, it should match the FQDN you used when running the connector install command. See below for potential issues if it does not match.
  • Next we’ll upload the 2 certificates created during the install process of the connector. As discussed above, we’ll need the random password protecting the Client Certificate in order to be able to import it in Jamf Pro.

That’s it! Done! If all is fine, this should now allow us to make a configuration profile, add the certificate payload and deploy certificates to our devices. I’m not going too far into discussing the Certificate Subject, SAN, etc… as this highly depends the need and purpose of the cert in your environment (see below for one additional tip regarding the template however).

Works! Easy isn’t it?

What? It does not work? You are pushing the profile with the cert settings, and it fails? In this case you’ll probably get an error like:

'Unable to retrieve ADCS certificate for profile payload'

Are you sure about your network considerations? 🙂 Just saying… I do bet a beer on it…

Ok, ok, not jumping into conclusions, first things first. The very first thing to do with almost all Jamf Pro issues is: check the Jamf Pro server logs, start at the bottom and work your way up to the timestamp where you tried something which did not work. In this case we are looking for anything mentioning ADCS. A few examples of things you might find are:

  • Jamf Pro not able to reach the ADCS connector
  • Certificate Problems
  • Template issues
  • Typos in the Jamf Pro Certificate Authority settings

Your best clue to network problems is the Jamf Pro server logs mentioning anything like :

2019-07-06 14:58:53,627 [INFO ] [neralPool-5] [RetryExec                ] - I/O exception (java.net.NoRouteToHostException) caught when processing request to {s}->https://adcs.travellingtechguy.dev:443: No route to host (Host unreachable)

Yes, network issues 🙂 . If you have an onprem Jamf Pro server, try to ping or traceroute the FQDN of your ADCS Connector server… doesn’t work? Try to ping the private/local IP adress of the connector. Works over IP but not over FQDN, then you have DNS issues. Doesn’t work on IP either? Bigger problems, probably VLAN or routing related.

You can resolve and ping the ADCS connector from the Jamf Pro server, then it’s probably going to be firewall related. In that case you’ll probably find something like this in the Jamf Pro logs:

Caused by: org.apache.http.conn.ConnectTimeoutException: Connect to adcs.travellingtechguy.dev:443 [adcs.travellingtechguy.dev/10.0.1.4] failed: connect timed out

The ADCS Connector installer should have created ADCS Proxy rules in the Windows Firewall, allowing connections on port 443 inbound to the ADCS server. You might want to crosscheck those, as well as any network firewalls in between Jamf Pro and the ADCS Connector. You need to allow inbound communication FROM Jamf Pro, all the way into the ADCS Connector, on port 443. Try telnetting to the ADCS Connector server from the Jamf pro Server:

Telnet fqdnADCSConnector 443

I know that if you are using Jamf Cloud, this all becomes tricky, as you don’t have access to the JamfCloud server as such. However, while Jamf Support can assist with those troubleshooting steps, I’d first make sure to check if your network boundary firewalls, and the Windows firewalls allow inbound connection on port 443 FROM the IP adresses defined here. Going through the process of raising a support ticket, troubleshooting all the above, ending up in realising the port is blocked… is always a bit unfortunate.

Next to check would be the communication between the ADCS Connector and the CA… can you ping / resolve the FQDN of the CA FROM the ADCS Connector? I’d imagine/hope yes, as the device is bound to the same domain, but still, worth checking if the ADCS Connector is correctly resolving the CA FQDN which you put in the Jamf Pro settings… that should resolve to the internal IP of the CA server.

Now, if all the above has been checked, and you still get the ‘Unable to retrieve ADCS certificate for profile payload’ error on your profile, there is something else going on, and yes, the logs will give you a clue. As always. Depending the issue, the command to push the profile might fail or remain pending for a while…

If you made an fqdn error or typo in the ADCS Connector install command, or the CA settings in Jamf Pro (see above), you might see something like below in the logs. Here I mistakenly put the wrong FQDN for the ADCS Connector in the install command (while being correct in the Jamf Pro settings). Hence I get a CN mismatch:

Caused by: org.springframework.web.client.ResourceAccessException: I/O error on GET request for "https://adcs.travellingtechguy.dev/api/v1/version":Host name 'adcs.travellingtechguy.dev' does not match the certificate subject provided by the peer (CN=ttgad.travellingtechguy.dev); nested exception is javax.net.ssl.SSLPeerUnverifiedException: Host name 'adcs.travellingtechguy.dev' does not match the certificate subject provided by the peer (CN=ttgad.travellingtechguy.dev)

As the error has been made during the installation (which created the certs we imported in Jamf Pro…) the only way to fix this is running the intaller again. If however, it’s just a typo in the Jamf Pro settings… we can easily fix it by changing the FQDN of the ADCS connector in Jamf Pro. Do not mix IP adresses and FQDN’s in your setup, as said, best practice is FQDN all the way.

Finally, some other typo’s like the wrong CA name (Jamf Pro settings), or wrong template (configuration profile options) can cause errors like below:

2019-07-07 10:23:50,329 [INFO ] [duledPool-7] [rtificateRequestProcessor] - Certificate request ID 15 fulfillment is incomplete:

All of this are just the most common issues regarding integrating the ADCS Connector in Jamf Pro and deploying your certificates. This does not mean that the cert you got deployed on your machines will work or fit the need of your deployment. There are many variables and options to configure regarding the type of cert (computer or user), the subject name, the SAN’s etc… to make it compatible for the authentication you need. This is a bit beyond the purpose of this post.

However, I promised one more tip regarding the templates you use to deploy your certs. Here it is:

(Thanks to Manu from Netopie for mentioning this at the Jamf Road Show in Paris!)

The Windows CA has 2 default templates, Computer and User. For instance for the Computer template:

However, if you use those, the name of the deployed cert will be linked to the entry of the reqesting entity in AD:

In our ADCS Connector scenario, this is our ADCS Connector itself, as it’s the connector which is contacting the CA to request a cert on behalf of Jamf Pro. Hence we end up with certs which all have the same name in our keychain:

In the example above, the cert is named to the entry of my ADCS Connector in the AD records (remember it is bound to AD), but what we really want is the cert to get the name according to the options we put in the Configuration Profile Certificate payload options… see Certificate Subject. Hence something like this:

To do this, you’re better of cloning the default template, name it to what you want (Macs in my example) and set the Subject Name to ‘Supply in the request’. This way Jamf Pro will provide the required Certificate Subject in the request, according to the options you defined in the config profile certificate payload.

The certs in the keychain screenshots above show up as ‘not trusted’… that’s because I did not deploy the Root Cert of my CA in the profile for this testing scneario

Oh yeah, actually one more thing… to check the incoming API request from Jamf Pro on the ADCS Windows server you can check the following logs. Here you should see 3 steps: an initial API call, a request and a retrieve. This for each cert request:

C:\inetpub\logs\LogFiles\W3SVC2

In the screenshot below you do see those at 10:20:43 – 48. After that I have been playing around with some wrong settings to get the error logs mentioned above. Hence you don’t seen any retrieve API call… further down the line.

If all the above seems correct… you might also need to have a look at the permissions on the template you are using. I did not run into any issues with that, but the way you create the template on the CA, you might need to adjust the permission to use it. As the ADCS Connector is AD bound, it should be given permission to use the template:

If needed, give it explicit read + enrol privileges by adding it to the template security settings:

And one very very last thing... if you end up seeing 403 errors on IIS of the ADCS Connector Machine, and all the above is correct, you might have made a mistake in the install command (probably wrong Jamf  Pro URL), you are running the connector behind a F5 Load Balancer, Reverse Proxy or similar, which might need some tweaking to allow the ADCS Connector to present it's own self signed certificate... or you are facing other IIS issues which would bring me a bit too far for this post...

BONUS: Check out this video from Daniel as well !

That’s it! Hope this clarifies a few things on how to install and troubleshoot issues with the Jamf Pro ADCS connector! There are probably other reasons which might cause trouble, but the issues above should cover the majority of the gotcha’s you might run in to.

As always, if you like this post, hit the like button, tell your friends about it and leave a comment down below!

Brgds,

TTG

Print Friendly, PDF & Email