brysontyrrell / jamf-functions

Jamf event-driven workflows using AWS Step Functions

Jamf Functions

This repository contains CloudFormation templates and Amazon States Language (ASL) files that will create resources in an AWS account to run scheduled and webhook based automations from Jamf Pro. The examples in this project, and the base resources it creates, will then enable you to create your own automations in template form or using AWS Step Functions Workflow Studio.

Base Resources Template

The base resources template at the root of this project creates resources in your AWS account that are required before you deploy any of the example workflows that are included.

• API Gateway: Jamf Pro needs an HTTP endpoint to send webhooks to. The API is created with a long randomized path value to obscure it from discovery (similar to how Slack's inbound webhooks work).
• Event Bus: This is a service in AWS that enables messages to be received and then delivered to one or more targets. There is a special logging rule included so a copy of every webhook is saved in CloudWatch logs in case you need to troubleshoot.
• API Connection: This securely stores the client ID and secret for your Jamf Pro API client so the Step Functions can make authenticated requests to the Jamf Pro APIs. AWS handles all the token generation and management for you!

The API Gateway uses a simple implementation of API key authentication. Jamf Pro webhooks support basic authentication with a username and password, or setting a value in custom headers. This approach uses the latter.

Create a Jamf Pro API Client

You must first create an API client to obtain the client ID and secret values required for the API connection resource. Full instructions are available at the Jamf Learning Hub: API Roles and Clients.

First create a role by navigating in Jamf Pro to Settings > System > API roles and clients (you will default to viewing the API Roles tab) and clicking + New. Give the role a name and select all the privileges required for the workflows you will deploy. Click Save.

Refer to the table below if you are deploying one of the examples. The Jamf Developer Portal also has pages that list the required API privileges for the Classic API and the Pro API if you are writing your own custom workflows.

Once you have created the role, create the client by navigating to the API Clients tab of the API roles and clients page and clicking + New. Give the client a name, select the role you just created, and click the Enable API Client button. Click Save.

There will be a Generate client secret button on the page for your new client (this button will only be active if the client is not disabled). Click it, and click Create secret on the pop-up. Copy both the client ID and client secret values.

You will not be able to retrieve this secret again. You will have to rotate the secret, generating a new one, which will invalidate the current.

Deploy the CloudFormation Stack

Download the base_resources.yaml file.

Log into your AWS account and go to the CloudFormation console.

Select Create stack > With new resources (standard). Choose Upload a template file and browse for the base_resource.yaml file. Fill in the URL of your Jamf Pro server (without a trailing /), and the client ID and secret you copied from the previous step.

Click Next, click Next, again, and then check all the boxes under "Transforms might require access capabilities" before clicking Submit. CloudFormation will now create the stack and all the resources.

Once the stack reached the state CREATE_COMPLETE you can navigate to the Outputs tab where the values needed for launching the example workflow stacks and creating webhooks will be found.

Create Jamf Pro Webhooks (As Needed)

You will now need to create the webhooks in Jamf Pro required for the workflows you have created.

Create a webhook in Jamf Pro by navigating to Settings > Global > Webhooks and clicking + New. Git the webhook a name. For Webhook URL copy the value of WebhooksApiUrl from the outputs of the base resources CloudFormation stack.

Set the Authentication Type to Header Authentication. In the text field you need to paste in the following JSON replacing <VALUE> with the value of WebhooksApiKey from the outputs of the base resources CloudFormation stack.

{
  "x-api-key": "<VALUE>"
}

Under Content Type ensure JSON is selected and select the appropriate webhook event. For smart group events you have the option of sending only membership changes for a specific group instead of all.

Example Workflows

The workflows included with this project are based on published Jamf Routines. They are effectively Step Functions versions of those automations, and provide a good reference for writing your own.

The API client permissions and webhooks required for each workflow are detailed below:

Redeploy Management Framework

Permissions	Webhook
Send Computer Remote Command to Install Package	SmartGroupComputerMembershipChange

Rename Mobile Devices

Permissions	Webhook
Read Mobile Devices (< 11.4) Send Mobile Device Set Device Name Command	MobileDeviceEnrolled

Jamf Pro 11.4+ includes the management ID in webhooks. Versions before 11.4 require an API call to read the mobile device record and get this value.

Restart Mobile Devices

Permissions	Webhook
Read Mobile Devices Send Mobile Device Restart Device Command	n/a