Need API Help - Return to Service

[shafferc]

Hello,

I have extensive experience with Jamf Pro but one area I've never touched is the API. But now with the release of Return to Service (via the API) I want to at the very least script something so that I can use this feature to eliminate some of the tedious work.

I work at a school and as such have hundreds of devices to erase every school year and its very time consuming to manually enter Wifi credentials on all of them after wiping to re-enroll with Jamf Pro. Can someone help me with a script that will automate this process using the Return to Service API??? It would be much appreciated. Thanks!

[ethanwenz]

You took the words right out of my mouth---er--- Google Search! I am trying to find some guidance on doing the same thing but feel out of my depth a bit. I will share the love if I find any progress!

[ethanwenz]

I found this! I am not 100% sure it's what I want to do because it references asking for a device ID when I would like to enable this feature for all devices at any time. I'm too scared to test it myself....

[ethanwenz]

https://github.com/red5coder/jamf-return-to-service

[Miff_Weaver]

Hey all,

Also in the same position haha! Thought I'd share a couple things I've found.

Kandji already have this built into their UI... hopefully Jamf will do the same real soon: 

From This I was able to locate where in the API Return to Service is and the info you need. MDM > Preview/MDM/Commands.

Change "Example Value to Schema", then follow the thread: commandData > EraseDeviceCommand > returnToService, you'll see the criteria there that you need to fill.

That's all I have... I haven't found a method of changing a WiFi network to a Base64 encrypted string... or MDM for that matter, so if anyone can point me in the right direction, that would be great!

Looking forward to getting this up and running though, it's going to save so much time and make the process a cinch! 

[Miff_Weaver]

Hey everyone, here's where I'm up to:

Download the WiFi config profile you need from Jamf, then in terminal run the following command:

security cms -D -i ~/Downloads/YOUR_WIFI_PROFILE.mobileconfig | xmllint --format - > ~/wifi-config.plist

This will take the profile, format it as an xml, then save it in your home dir.

Following that, run this command to Base64 encrypt:

cat ~/wifi-config.plist | base64

This will print the encrypted profile in your Terminal session.

Still trying to get it working in Jamf API, so far I have the following setup which is giving me a 500 error, but it's progress!

{
  "clientData": [
    {
      "managementId": "YOUR_MANAGEMENT_ID"
    }
  ],
  "commandData": {
    "commandType": "ERASE_DEVICE", 
    "returnToService": {
      "enabled": "true",
      "wifiProfileData" : "ENCRYPTED_WIFI_PROFILE"
  }
 }
}

I'm not going to be using the 'MDMProfileData' property due to our setup, but I'd imagine you follow a similar process to the commands above.

Please update me on how you're getting on, I think we're getting somewhere :)

[Miff_Weaver]

Hey again all,

I've found a solution that works for me via Mac Admins Slack.
User @zack posted it, here's a link to their profile / Link to post

I ran it in CodeRunner, it prompts you for all the information it needs and runs the returntoservice command on a device. I've messaged Zack to see if it can be adapted to run on multiple devices from a list (something that should be easy to grab using the API!). Hopefully it can, as it would save a lot of time and manual entry. I'll be testing this on a few iPads when I'm in the office tomorrow.

Main findings are:

• I'll be adapting the script to save credentials, jss address, wifiprofiledata to speed up the process.
• ManagementID is specific to the device you are going to WIPE
• This script used the Device ID field in Jamf to pull the Management ID (much smaller and easier to type in)
• The base64 encrypted config profile does NOT need to be converted to XML prior to encrypting, like I originally thought.

#!/bin/bash

#Script to run return to service on Jamf Pro
#Currently the only way to run this feature is via the API
#This script is built for devices already in ADE as it does not tell the device what MDM Profile to install, only a wi-fi profile
#You can elect to hard code any of the variables as desired, the intent was to create the ability to pass the script around to anyone to try
#This was last confirmed operational on 9/19/23

# Redistribution and use in source and binary forms, with or without
# modification, are permitted provided that the following conditions are met:
#        * Redistributions of source code must retain the above copyright
#         notice, this list of conditions and the following disclaimer.
#      * Redistributions in binary form must reproduce the above copyright
#           notice, this list of conditions and the following disclaimer in the
#           documentation and/or other materials provided with the distribution.
#         * Neither the name of the JAMF Software, LLC nor the
#           names of its contributors may be used to endorse or promote products
#           derived from this software without specific prior written permission.
# THIS SOFTWARE IS PROVIDED BY JAMF SOFTWARE, LLC "AS IS" AND ANY
# EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
# WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
# DISCLAIMED. IN NO EVENT SHALL JAMF SOFTWARE, LLC BE LIABLE FOR ANY
# DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
# (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
# LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
# ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
# (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
# SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

echo "Please enter your API credentials"
read -p 'Username: ' APIUSER
read -sp 'Password: ' APIPASS
echo -e "\n Please enter your full server URL starting with https://"
read -p 'ServerURL: ' url
echo -e "\n Please enter the ID of the device you want to return to service"
read -p 'Device ID: ' deviceid


#HARD CODED VARIABLE FOR API BEARER TOKEN RETRIEVAL
getBearerToken() {
	response=$(curl -s -u "$APIUSER":"$APIPASS" "$url"/api/v1/auth/token -X POST)
	bearerToken=$(echo "$response" | plutil -extract token raw -)
}

getBearerToken 

getManagementId() {
	mobiledevicerecord=$(curl -X 'GET' \
	"$url/api/v2/mobile-devices/$deviceid" \
	-H 'accept: application/json' \
	-H "Authorization: Bearer $bearerToken")
	managementId=$(/usr/bin/plutil -extract "managementId" raw -o - - <<< "$mobiledevicerecord")
	echo "Management ID: $managementId"
}

getManagementId 

#Download the .mobileconfig file for the wi-fi you want and enter the file path or drag and drop it when prompted
echo -e "\n Please enter the file path of the Wi-Fi Configuration Profile you would like to use:"
read -p 'configProfilePath: ' configProfilePath

# define it
base64pathwifi=$(base64 < "$configProfilePath")

curl --request POST \
--url "$url"/api/preview/mdm/commands \
--header "Authorization: Bearer $bearerToken" \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--data '
{
	"clientData": [
		{
			"managementId": "'$managementId'"
		}
	],
	"commandData": {
		"commandType": "ERASE_DEVICE",
		"returnToService": {
			"enabled": true,
			"wifiProfileData": "'$base64pathwifi'"
		}
	}
}
'

I hope this helps, I don't think I'll spend any more time trying to get it to work via the API, as I'm sure Jamf will have a UI solution coming soon and this process appears to work great for me.

✌🏻

[JayDuff]

People reading and wanting this to be easy should probably upvote this feature request.

[rzoppi]

the aforementioned script works perfectly, and with the addition with the ability to point it to a smart group saves plenty of time. HOWEVER the inability to enable location services makes this return to service feature still very limiting as a user MUST handle the iPad to manually turn location services on. Otherwise, I will have hundreds of iPads with the wrong time.

[Ecco_Luke]

@rzoppi You can set the time zone separately in a PreStage. This works fine for me with RTS. But yes, the user will need to manually enable Location Services if they're used for anything else but that's an Apple requirement.