Skip to content

Commit

Permalink
[v16] Document Jamf API credentials support (#42305)
Browse files Browse the repository at this point in the history
* Document Jamf API credentials support

* Add "urlencode" to dictionary

* Add `$` to code block commands
  • Loading branch information
codingllama authored Jun 3, 2024
1 parent 71e97fa commit e1f2b33
Show file tree
Hide file tree
Showing 4 changed files with 103 additions and 37 deletions.
5 changes: 5 additions & 0 deletions docs/config.json
Original file line number Diff line number Diff line change
Expand Up @@ -1957,6 +1957,11 @@
"helm": {
"version": "3.4.2"
},
"jamf": {
"api_endpoint": "https://yourtenant.jamfcloud.com",
"client_id": "your-client-id",
"client_secret": "your-client-secret"
},
"kubernetes": {
"major_version": "1",
"minor_version": "17"
Expand Down
1 change: 1 addition & 0 deletions docs/cspell.json
Original file line number Diff line number Diff line change
Expand Up @@ -889,6 +889,7 @@
"upgrader",
"uqcje",
"urandom",
"urlencode",
"urlfetch",
"usename",
"userdata",
Expand Down
114 changes: 80 additions & 34 deletions docs/pages/access-controls/device-trust/jamf-integration.mdx
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
---
title: Jamf Pro Integration
title: Jamf Pro Integration
description: Sync your Jamf Pro inventory into Teleport
---

Expand Down Expand Up @@ -29,31 +29,44 @@ and behavior.

(!docs/pages/includes/device-trust/prereqs.mdx!)

## Step 1/4. Create a Jamf user
## Step 1/4. Create Jamf API credentials

Create a readonly Jamf user for inventory sync.

1. Access `https://yourtenant.jamfcloud.com/accounts.html`, replacing
`yourtenant` with your Jamf Pro account.
<Admonition type="notice" title="v16.0.0 or lower">
Teleport versions v16.0.0 or lower don't support Jamf API credentials. Follow
the instructions under [Using Jamf user and password authentication](
#optional-using-jamf-user-and-password-authentication) instead.
</Admonition>

1. Create a new Standard Account with the following settings:
Follow the instructions at [Jamf API Roles and Clients](
https://learn.jamf.com/en-US/bundle/jamf-pro-documentation-current/page/API_Roles_and_Clients.html)
to create a role and an API client. We recommend creating a role and API client
specific for Teleport.

- 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
Make sure that your Jamf role has the "Read Computers" privilege.

Take note of the user and password created here for the next step.
You can test your client credentials using the following Jamf query:

User account setup: ![Jamf user setup](
../../../img/access-controls/device-trust/jamf-setup-1.png)
```code
$ URL='<Var name="(=jamf.api_endpoint=)" description="Jamf API URL"/>'
$ CLIENT_ID='<Var name="(=jamf.client_id=)" description="Jamf API client ID" />'
$ CLIENT_SECRET='<Var name="(=jamf.client_secret=)" description="Jamf API client secret" />'
## Acquire access token from Jamf.
$ TOKEN_RESP="$(curl -X POST "$URL/api/oauth/token" \
-H 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode "client_id=$CLIENT_ID" \
--data-urlencode "client_secret=$CLIENT_SECRET" -s)"
$ echo "$TOKEN_RESP"
$ ACCESS_TOKEN="$(echo "$TOKEN_RESP" | jq -r .access_token)"
## Test access token privileges.
$ curl -H "Authorization: Bearer $ACCESS_TOKEN" "$URL/api/v1/computers-inventory?page-size=1"
```

Privileges setup: ![Jamf privileges setup](
../../../img/access-controls/device-trust/jamf-setup-2.png)
The query above should print an inventory entry from Jamf. If you get permission
errors (401 or 403), double check your client credentials, role privileges and
try to recreate your API client.

## Step 2/4. Configure Jamf service

Expand Down Expand Up @@ -86,9 +99,9 @@ teleport:
jamf_service:
enabled: true
name: jamf
api_endpoint: https://yourtenant.jamfcloud.com # CHANGEME
username: teleport # CHANGEME
password_file: /var/lib/teleport/jamf_password.txt
api_endpoint: (=jamf.api_endpoint=) #CHANGEME
client_id: (=jamf.client_id=) #CHANGEME
client_secret_file: /var/lib/teleport/jamf_client_secret.txt

auth_service:
enabled: false
Expand All @@ -104,16 +117,17 @@ Change the following settings, as appropriate:
- teleport.proxy_server
- jamf_service.api_endpoint
- jamf_service.username
- jamf_service.client_id
Finally, write your Jamf password to the `/var/lib/teleport/jamf_password` file:
Finally, write your Jamf client secret to the
`/var/lib/teleport/jamf_client_secret` file:

```code
$ sudo nano /var/lib/teleport/jamf_password # or use your favorite editor
$ sudo nano /var/lib/teleport/jamf_client_secret # 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
# Only the OS user that runs `teleport` should have access to the secret file.
$ sudo chmod 400 /var/lib/teleport/jamf_client_secret
$ sudo chown teleport /var/lib/teleport/jamf_client_secret
```

## Step 3/4. Create a join token
Expand Down Expand Up @@ -176,7 +190,7 @@ 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](
https://developer.jamf.com/jamf-pro/reference/get_v1-computers-inventory).
https://developer.jamf.com/jamf-pro/reference/get_v1-computers-inventory).
Jamf recommends a full sync no more than once every 24 hours.

The default "inventory" configuration is roughly equivalent to the one below:
Expand Down Expand Up @@ -277,8 +291,8 @@ jamf_service:
enabled: true
+ name: jamf1
+ api_endpoint: https://tenant1.jamfcloud.com
+ username: tenant1
+ password_file: /var/lib/teleport/jamf1_password.txt
+ client_id: tenant1-id
+ client_secret_file: /var/lib/teleport/jamf1_client_secret.txt
auth_service:
enabled: false
Expand All @@ -301,8 +315,8 @@ jamf_service:
enabled: true
+ name: jamf2
+ api_endpoint: https://tenant2.jamfcloud.com
+ username: tenant2
+ password_file: /var/lib/teleport/jamf2_password.txt
+ client_id: tenant2-id
+ client_secret_file: /var/lib/teleport/jamf2_client_secret.txt
auth_service:
enabled: false
Expand All @@ -314,6 +328,38 @@ ssh_service:
enabled: false
```

## Optional: Using Jamf user and password authentication

<Admonition type="notice" title="v16.1.0+">
Teleport versions v16.1.0 and higher support [Jamf API credentials](
#step-14-create-jamf-api-credentials). Prefer using API credentials instead
of username and password authentication.
</Admonition>

Create a readonly Jamf user for inventory sync.

1. Access `(=jamf.api_endpoint=)/accounts.html`, replacing
`yourtenant` with your Jamf Pro account.

1. 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.

User account setup: ![Jamf user setup](
../../../img/access-controls/device-trust/jamf-setup-1.png)

Privileges setup: ![Jamf privileges setup](
../../../img/access-controls/device-trust/jamf-setup-2.png)

## Next steps

Automatically enroll synced devices on user login with
Expand Down
20 changes: 17 additions & 3 deletions docs/pages/includes/config-reference/jamf-service.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -13,18 +13,32 @@ jamf_service:

# API endpoint for the Jamf Pro API.
# Required.
api_endpoint: https://yourtenant.jamfcloud.com
api_endpoint: (=jamf.api_endpoint=)

# Username for the Jamf Pro API.
# Required.
# Prefer using client_id and client_secret_file.
# If both username+password and client_id+client_secret are set the service
# will use the latter.
username: teleport

# Path to a file containing the password for the Jamf Pro API.
# It is recommended to set the permissions for the file as restrictively as
# possible.
# Required.
# Prefer using client_id and client_secret_file.
# If both username+password and client_id+client_secret are set the service
# will use the latter.
password_file: /var/lib/teleport/jamf_password.txt

# Client ID for the Jamf Pro API.
# See https://developer.jamf.com/jamf-pro/docs/client-credentials.
client_id: (=jamf.client_id=)

# Path to a file containing the client secret for the Jamf Pro API.
# It is recommended to set the permissions for the file as restrictively as
# possible.
# See https://developer.jamf.com/jamf-pro/docs/client-credentials.
client_secret_file: /var/lib/teleport/jamf_client_secret.txt

# Delay for initial syncs.
# Set to zero for syncs to start after a short random delay (a couple minutes
# max).
Expand Down

0 comments on commit e1f2b33

Please sign in to comment.