How to request a certificate from a Microsoft Certificate Authority using the ADCertificatePayloadPlugin
Learn how to request a certificate from a Microsoft Certificate Authority using the ADCertificatePayloadPlugin.
OS X Lion's Profile Management feature and the ADCertificatePayload Plugin provide the ability to easily request and retrieve a digital certificate from a Microsoft Active Directory Certificate Services Certificate Authority. For a Lion system bound to Active Directory, this feature greatly simplifies the process of obtaining a digital identity for a computer or user account.
Network and system requirements
- An OS X Lion system bound to Active Directory (verify via sudo dsconfigad -show)
- A valid Active Directory domain
- A working Microsoft Active Directory Certificate Services Certificate Authority, with Web Certificate Authority functionality enabled
How to request a certificate from a Microsoft Certificate Authority
Two types of certificates can be acquired from a Microsoft Certificate Authority--one associated with an Active Directory user account, or one associated with a computer account. Depending on the type of certificate and type of Active Directory authentication credentials supplied, there are a variety of configuration combinations that can be used.
Before discussing these combinations, it may help to understand the keys that can be present in the configuration profile payload. Many of the keys are the usual name, identification, version, and time stamp values found in any .mobileconfig profile. The following are specific to the ADCertificatePayloadPlugin profile:
|CertServer||string, mandatory||The URL for a Microsoft Active Directory Certificate Services Certificate Authority.
For example, http://yourca.example.com/certsrv
|CertTemplate||string, mandatory||The name of the intended computer certificate template to be used for certificate creation; must be created and enabled on the Certificate Authority|
|UserName||string, optional||Valid username for an Active Directory user with permission to read & enroll with the configured certificate template|
|Password||string, optional||Valid password for the configured Active Directory user account|
|PromptForCredentials||boolean, optional||Field to be used if the the end user should be prompted to supply the password and/or Active Directory username|
|PayloadType||string, mandatory||Value must be "com.apple.ADCertificate.managed"|
Two unique UID values are required for the profile--one for the PayloadUUID in the PayloadContent dict and one for the exterior PayloadUUID. The Mac OS X "uuidgen" binary can be used to generate these values.
Also, two unique PayloadIdentifier strings are required for the profile--one within the PayloadContent dict, and one for the exterior PayloadIdentifier.
It is not imperative that the Lion client be enrolled in mobile device management with a Lion Server. The supported methods for installing an ADCertificatePayloadPlugin profile are double-clicking on a valid .mobileconfig file in the Finder, or using the command line utility /usr/bin/profiles . You cannot compose the profile in Lion Server's Profile Manager, nor push the composed profile out via Profile Manager to an enrolled Lion client.
Valid certificate types and Active Directory authentication credential combinations that can be used to obtain a certificate
|Certificate type||Profile payload type||Active Directory authentication credential||Username key value||Password key value||PromptForCredentials key value||Support profile Install method|
|machine/computer||SystemConfiguration||machine account kerberos Ticket Granting Ticket (TGT) (see note 1)||none||none||omitted/none||See note 4|
|user||Configuration||Active Directory username + password||valid Active Directory username||valid Active Directory password||omitted/false||See note 4|
|user||Configuration||Active Directory username + password||valid Active Directory username||none||true (see note 3)||double-click on file|
|user||Configuration||Active Directory username + password||none||none||true (see note 3)||double-click on file|
- To acquire a machine account Kerberos TGT: Log in as a local admin, determine the "AD machine name" by using sudo dsconfigad -show . Obtain the TGT by using sudo kinit -k (computer name)$ .
- If installing with the command line utility /usr/bin/profiles, the profile's payload type key is ignored. If the profiles command is run by root, the profile is installed as "SystemConfiguration". Otherwise, the profile will be treated as "Configuration" and associated with whatever account executes 'profiles'. If installing by double-clicking the file in the Finder, a machine account certificate requires a Payload Type of "SystemConfiguration". Also, a user account certificate requires a Payload Type of "Configuration".
- Omitting a value for UserName and/or Password with a 'true' PromptForCredentials key will automatically prompt the user for whatever values are missing at installation time.
- Install method:
double-click on file (see note 2)
/usr/bin/profiles -I -F (path to .mobileconfig file)
If no values for UserName and Password are supplied and the 'PromptForCredentials' key is also omitted, double-clicking the .mobileconfig file will prompt the user to supply Username and Password values.
This is a sample profile template:
<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd"> <plist version="1.0"> <dict> <key>PayloadContent</key> <array> <dict> <key>CertServer</key> <string>http://YOUR.HOSTNAME.HERE/certsrv</string> <key>CertTemplate</key> <string>YOUR_CERT_TEMPLATE_HERE</string> <key>UserName</key> <string>YOUR_AD_USERNAME_HERE_OPTIONAL</string> <key>Password</key> <string>YOUR_AD_USERNAME_PASSWORD_HERE_OPTIONAL</string> <key>PromptForCredentials</key> <false/> <key>ADCertServerCertificateIDReplySearchString</key> <string>YOUR_CERT_ID_REPLY_SEARCH_STRING_HERE_OPTIONAL</string> <key>PayloadDisplayName</key> <string>YOUR_PAYLOAD_DISPLAY_NAME_HERE</string> <key>PayloadIdentifier</key> <string>YOUR.PAYLOAD.IDENTIFIER.HERE</string> <key>PayloadType</key> <string>com.apple.ADCertificate.managed</string> <key>PayloadUUID</key> <string>YOUR_GENERATED_UUID_1</string> <key>PayloadVersion</key> <integer>1</integer> <key>deleted</key> <false/> </dict> </array> <key>PayloadDescription</key> <string>YOUR_PAYLOAD_DESCRIPTION_HERE</string> <key>PayloadDisplayName</key> <string>YOUR_PAYLOAD_DISPLAY_NAME_HERE</string> <key>PayloadIdentifier</key> <string>YOUR.PAYLOAD.IDENTIFIER.HERE</string> <key>PayloadOrganization</key> <string>YOUR_PAYLOAD_ORGANIZATION_HERE</string> <key>PayloadRemovalDisallowed</key> <false/> <key>PayloadType</key> <string>SystemConfiguration</string> <key>PayloadUUID</key> <string>YOUR_GENERATED_UUID_2</string> <key>PayloadVersion</key> <integer>1</integer> </dict> </plist>
This template can be copied and pasted into a .mobileconfig file and then customized for your environment.