Installation and Setup

Installation

To install the latest production release of JSSImporter, download the latest package installer from the Releases section of the JSSImporter repo. This will add the JSSImporter.py processor to the /Library/AutoPkg/autopkglib folder, and the python-jss package to /Library/AutoPkg/JSSImporter.

Notes

• Version 1.1.0 is updated for python 3, and designed specifically to work with AutoPkg 2.0 and above, which bundles in python 3. Older versions will only work with python 2 and older versions of AutoPkg.
• Prior to version 1.1.0, python-jss was installed into /Library/Application Support/JSSImporter.
• Prior to version 1.0.0, JSSImporter did not bundle python-jss into the package.

Which version is right for me?

Due to changes in Jamf Pro since JSSImporter was developed, there have been some challenges in maintaining full functionality. You may find that different versions work best for you. It is recommended to start with the latest version (1.1.0), and then if you have problems with that, to revert to 1.0.0 and then 0.5.1.

A big challenge is that there is no public API for uploading packages to a Jamf Cloud Distribution Server (JCDS), so some degree of hackery has had to be employed. Version 1.1.0 should work best with JCDS, but there are occasionally issues.

Setup

Prior to using the JSSImporter, You will need to add some preferences to your AutoPkg preferences file:

• The URL to your JSS
• The username and password of an API privileged user (see next section for more info)
• Your distribution points

Creating an API user

If you haven't done so already, you'll need to create a service account with which JSSImporter will interact with the API. It is recommended to create a user named something like "AutoPkg", which you can do in the Jamf Pro admin interface in Management Settings > Jamf Pro User Accounts and Groups.

The user will need Create, Read, and Update privileges on the following:

• Categories
• Computer Extension Attributes
• Smart Computer Groups
• Static Computer Groups
• File Share Distribution Points (only needs "Read")
• Cloud Distribution Points (only needs "Read")
• Packages
• Policies
• Scripts

Basic preferences

The preferences you will definitely need are JSS_URL, API_USERNAME, and API_PASSWORD. You will probably also want to configure distribution points so your packages can get synced to them. Distribution points are covered later. You can configure these basics with the following commands:

defaults write com.github.autopkg JSS_URL https://test.jss.private:8443
defaults write com.github.autopkg API_USERNAME apiUser
defaults write com.github.autopkg API_PASSWORD apiPassword

SSL and Self-Signed Certificates

If your JSS uses a self-signed certificate, please consider switching to a real certificate. Please.

The bundled python-jss uses the python requests module by default, or curl if it is not available on the system. You can investigate adding the self-signed certificate to a curl.rc file for the user account autopkg is using.

For the non-security-minded admin, if you are testing or are running with scissors in YOLO mode, you can disable certificate verification by using the following preference:

defaults write com.github.autopkg JSS_VERIFY_SSL -bool False

This value defaults to True, because you should want to verify both where you're uploading to and that what you upload isn't harmed in transit. It's worth it before you push this to an installer that runs as root on all the computers you manage.

Additional Preferences

In addition to the URL, user, password and SSL preferences, there are a few others you may want to use.

• JSS_SUPPRESS_WARNINGS: Boolean. Determines whether to suppress urllib3 warnings when you are using python requests as the request handler. This has no effect on curl. If you choose not to verify SSL with JSS_VERIFY_SSL, urllib3 throws warnings for each of the numerous requests JSSImporter makes. If you would like to see them, set to False. Defaults to True.

A note on passwords

These instructions walk you through setting preferences through bash command-line tools (PlistBuddy, defaults). JSSImporter is written in Python. JSSImporter is often used in AutoPkgr which adds Objective-C to the mix. And the templates are all XML. Each of these languages has reserved characters, some of which may be in your API user's or distribution point's password.

If you are having weird issues with authentication errors, even though you know you are typing the password in correctly to defaults/AutoPkgr/etc, please side-step the issue entirely and create a password that is truly secure and try again. "Special characters" do not automatically create password complexity. Just randomly generate a very long alphanumeric password and you'll be golden. You won't be typing it in pretty much ever, so the length is not going to be a nuisance, compared to the anxiety attacks you may experience trying to figure out the intracies of encoding and decoding passwords back and forth through all of these different languages.

This is not to say that JSSImporter doesn't do its best job trying to handle these correctly; but rather that there are enough FAQ password issues that it makes sense to just call it out and spare yourself the mysterious issues introduced when bash expands the ! or $ in your password to something mysterious.