Skip to main content
Version: 14.x

Jamf Pro Integration

Device Trust Jamf Pro integration lets you automatically sync your Jamf Pro computer inventory into Teleport.

The Teleport Jamf Pro service is a distinct teleport process that periodically reads your computer inventory from Jamf Pro and syncs it to Teleport. It performs both incremental (called "partial") and full syncs, as well as removals from Teleport if a computer is removed from Jamf Pro.

Syncing devices from Jamf Pro is an inventory management step, equivalent to automatically running the corresponding tctl devices add commands.

See the Device Trust guide for fundamental Device Trust concepts and behavior.

This integration is hosted on Teleport Cloud

In Teleport Enterprise Cloud, Teleport manages the Jamf Pro integration for you, and you can enroll the Jamf Pro integration from the Teleport Web UI.

Visit the Teleport Web UI and find the dropdown menu on the upper left of the screen. Select the Management option.

On the left sidebar, click Enroll New Integration to visit the "Enroll New Integration" page:

On the "Select Integration Type" menu, click the tile for your integration. You will see a page with instructions to set up the integration, as well as a form that you can use to configure the integration.

Prerequisites​

  • A running Teleport Enterprise cluster. For details on how to set this up, see the Enterprise Getting Started guide.

  • The Enterprise tctl admin tool and tsh client tool version >= 14.3.33. You can download these tools by visiting your Teleport account. You can verify the tools you have installed by running the following commands:

    $ tctl version
    # Teleport Enterprise v14.3.33 go1.21

    $ tsh version
    # Teleport v14.3.33 go1.21
  • To enroll a macOS device, you need:
  • To enroll a Windows device, you need:
    • A device that includes a TPM with 2.0 support.
    • tsh installed on the device. Download the Windows tsh installer.
    • Credentials for a user with administrator privileges for the device. This is only required during enrollment.
    • A Teleport version newer than v13.1.2.

Step 1/4. Create a Jamf user​

Create a readonly Jamf user for inventory sync.

  1. Access https://yourtenant.jamfcloud.com/accounts.html, replacing yourtenant with your Jamf Pro account.

  2. Create a new Standard Account with the following settings:

    • Username: teleport (change as desired)
    • Access Level: Full Access
    • Privilege Set: Custom
    • Access Status: Enabled
    • Password: (a strong password of your choice)
    • Privileges:
      • Advanced Computer Searches: Read
      • Computers: Read

    Take note of the user and password created here for the next step.

    User account setup: Jamf user setup

    Privileges setup:

Step 2/4. Configure Jamf service​

Hosted Jamf plugin

Teleport Cloud users can quickly get started with Jamf integration by using the hosted Jamf plugin in the Web UI.

Configure Jamf hosted plugin

Select the Jamf plugin: Fill in the required information and click "Connect Jamf" button:

Jamf inventory sync is performed by a separate teleport process, configured using the jamf_service key. It is recommended to run the service isolated from other Teleport processes, as it requires the Jamf credentials created in the step above.

Save the following file as /var/lib/teleport.yaml and edit as needed:

version: v3
teleport:
  # Necessary to write devices back to Teleport.
  proxy_server: teleport.example.com:443 # CHANGEME
  join_params:
    token_name: "/tmp/token"

jamf_service:
  enabled: true
  name: jamf
  api_endpoint: https://yourtenant.jamfcloud.com # CHANGEME
  username: teleport                             # CHANGEME
  password_file: /var/lib/teleport/jamf_password.txt

auth_service:
  enabled: false

proxy_service:
  enabled: false

ssh_service:
  enabled: false

Change the following settings, as appropriate:

  • teleport.proxy_server
  • jamf_service.api_endpoint
  • jamf_service.username

Finally, write your Jamf password to the /var/lib/teleport/jamf_password file:

$ sudo nano /var/lib/teleport/jamf_password # or use your favorite editor

# Only the OS user that runs `teleport` should have access to the password file.
$ sudo chmod 400 /var/lib/teleport/jamf_password
$ sudo chown teleport /var/lib/teleport/jamf_password

Step 3/4. Create a join token​

Jamf service requires an MDM token to write devices to Teleport. On your local workstation, create the token as shown below:

$ tctl tokens add --type=mdm
The invite token: efgh456-insecure-do-not-use-this
This token will expire in 30 minutes.

From the Jamf service host, use this token to add an MDM service to Teleport.

> teleport start \
   --token=efgh456-insecure-do-not-use-this \
   --ca-pin=sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678\
   --config=/path/to/teleport.yaml

On the Jamf service host, write the token to a file called /tmp/token.

Step 4/4. Start Jamf service​

Using the token created above, start the service:

Configure your Teleport instance to start automatically when the host boots up by creating a systemd service for it. The instructions depend on how you installed your Teleport instance.

On the host where you will run your Teleport instance, enable and start Teleport:

$ sudo systemctl enable teleport
$ sudo systemctl start teleport

You can check the status of your Teleport instance with systemctl status teleport and view its logs with journalctl -fu teleport.

The initial sync should happen in a few minutes. You can confirm from the Teleport service logs:

2023-06-21T17:26:40-03:00 INFO [JAMF:1]    Jamf service successfully started pid:25757.1 service/service.go:228
2023-06-21T17:26:40-03:00 INFO [JAMF:1]    Starting sync CutTime:0001-01-01 00:00:00 +0000 UTC FilterRSQL: Mode:1 OnMissing:DELETE pid:25757.1 service/service.go:261
2023-06-21T17:26:40-03:00 INFO [JAMF:1]    Device sync report, page #0 deletes:0 failures:0 pid:25757.1 upserts:1 service/service.go:666
2023-06-21T17:26:40-03:00 INFO [JAMF:1]    Sync complete pid:25757.1 service/service.go:277

Using the default configuration, the service will sync devices from Jamf every few hours. Once a day a full inventory sync is performed, enumerating all devices from Jamf and reflecting any additions or removals on Teleport.

After the initial sync happens, you may verify the synced devices using tctl devices ls:

$ tctl devices ls
Asset Tag    OS      Enroll Status Device ID
------------ ------- ------------- ------------------------------------
CXXXXXXXXX17 macOS   not enrolled  20ec6373-9e8e-46e0-8f1c-47ad6b06a768
CXXXXXXXXX2T macOS   not enrolled  79755778-7cbe-4e2c-83ec-7eaa3d4d7e36
CXXXXXXXXX3T macOS   not enrolled  665e59d5-393a-4894-841d-edad06329717
CXXXXXXXXX4T macOS   not enrolled  dd032e90-bfb0-47d5-bce5-e57545f6788f
CXXXXXXXXX5T macOS   not enrolled  bf189863-a94a-40dc-9013-d96f8dada2f1
(...)

Optional: Customize the sync schedule​

When using the minimal configuration, described in the steps above, Jamf service utilizes a default sync schedule. It is possible to customize sync intervals, as well as the set of devices synced from Jamf, by applying RSQL filters provided by the Jamf Pro API. Jamf recommends a full sync no more than once every 24 hours.

The default "inventory" configuration is roughly equivalent to the one below:

jamf_service:
  enabled: true
  # ...
  inventory:
  - sync_period_partial: 6h
    sync_period_full: 24h
    on_missing: DELETE
    filter_rsql: general.remoteManagement.managed==true

Unpacking the configuration, we have the following keys:

sync_period_*​

  • sync_period_partial: period for partial syncs. A partial sync attempts to fetch new and modified devices, but won't scan the entire Jamf inventory.
  • sync_period_full: period for full syncs. A full sync scans the entire Jamf inventory, processing new/modified devices and removals from Jamf.

Both sync periods may be disabled by setting the period to 0 or -1. It is recommended to do a full sync with some regularity, so Teleport has the chance to fully synchronize both inventories.

on_missing​

The on_missing key determines what to do with devices deleted from Jamf, but present in Teleport. The possible actions are:

  • DELETE: devices removed from Jamf are eventually removed from Teleport. (Requires a full sync.)
  • NOOP: devices removed from Jamf are allowed to remain in the Teleport inventory.

Only devices synced by Jamf are susceptible to deletion in this manner. Devices written manually via tctl devices add or written by other sources won't be deleted.

For immediate removal of unwanted devices first lock the device on Teleport, then remove it from Jamf:

$ tctl devices lock --asset-tag=SERIAL_NUMBER --message='reason for locking'
Created a lock with name "a2f1491c-4a3e-4daf-9c83-2fe931668076".

Manual removal via tctl devices rm is possible, but note that if the device is still in the Jamf inventory, it'll be recreated during the next sync.

filter_rsql​

The filter_rsql key applies a Jamf Pro API filter when querying for devices. Refer to https://developer.jamf.com/jamf-pro/reference/get_v1-computers-inventory for the possible filter values.

Optional: Sync multiple sources​

When syncing inventory, Jamf service claims ownership of all synced devices. This can be verified by inspecting a device's source field:

# tctl get device/mydevice
kind: device
metadata:
  name: 20ec6373-9e8e-46e0-8f1c-47ad6b06a768
spec:
  asset_tag: mydevice
  os_type: macos
  # ...
  source:         # Set during inventory sync
    name: jamf    # Copied from jamf_service.name
    origin: jamf  # Always "jamf" for Jamf service
  update_time: "2023-06-21T19:44:40.40601Z"
version: v1

Device ownership is important in a few situations, but it is particularly important when running "on_missing=DELETE" syncs, as only the devices owned by the sync source are considered for deletion.

If you want to run multiple Jamf sources you can simply run multiple Jamf services, each with its configuration and credentials. Just make sure that each service has a different "jamf_service.name". For example:

teleport.yaml - Service #1:

version: v3
teleport:
  proxy_server: teleport.example.com:443

jamf_service:
  enabled: true
+ name: jamf1
+ api_endpoint: https://tenant1.jamfcloud.com
+ username: tenant1
+ password_file: /var/lib/teleport/jamf1_password.txt

auth_service:
  enabled: false

proxy_service:
  enabled: false

ssh_service:
  enabled: false

teleport.yaml - Service #2:

version: v3
teleport:
  proxy_server: teleport.example.com:443

jamf_service:
  enabled: true
+ name: jamf2
+ api_endpoint: https://tenant2.jamfcloud.com
+ username: tenant2
+ password_file: /var/lib/teleport/jamf2_password.txt

auth_service:
  enabled: false

proxy_service:
  enabled: false

ssh_service:
  enabled: false

Next steps​

Automatically enroll synced devices on user login with auto-enrollment.