Skip to content

Setting Up a MicroMDM Instance

Jump to bottom
jenjac edited this page Jan 4, 2019 · 7 revisions

1. Download and Install the micromdm Binaries

  1. Download the latest zip from the micromdm GitHub repo Here
  2. Unzip the file.
  3. Move the appropriate binaries to /usr/local/bin
    cp ~/Downloads/build/darwin/mdmctl /usr/local/bin
    cp ~/Downloads/build/darwin/micromdm /usr/local/bin

2. Download, Install and Start ngrok

The ngrok tool is used to create a secure tunnel to your test machine, so mdm clients can interact with your test server without having to set up all the DNS and Firewall rules.

  1. Download the latest zip from ngrok using Step 1 Here
  2. Unzip the file as described on Step 2 of the ngrok download page.
  3. Move the binary to /usr/local/bin
    cp ~/Downloads/ngrok /usr/local/bin
  4. Create and connect an account using Step 3 on the ngrok download page. (without "./" at the beginning of the command)
  5. Start ngrok in its own Terminal Window
    ngrok http 8080
    We use "8080" for our test setup because we will be starting our test micromdm instance without tls.
  6. Open the ngrok Web Interface on the client running ngrok at this url:
    http://127.0.0.1:4040

The following steps are listed in more detail in the micromdm GitHub Quickstart. For the purposes of the GusDay presentation, simplified directions are posted below.

3. Configure mdmctl

The mdmctl tool acts as a command line interface to micromdm. We will use it to set up and configure your micromdm instance. For help using the mdmctl tool mdmctl with the "-h" option.

  1. Configure mdmctl to connect to your micromdm instance through the ngrok tunnel.
    mdmctl config set -api-token SUPER_SECRET_TOKEN -name UNIQUE_NAME -server-url NGROK_URL

    SUPER_SECRET_TOKEN is a strong password that will be used to send all interface calls to your micromdm server instance.
    UNIQUE_NAME is any name to identify your server in the mdmctl config.
    NGROK_URL is the url presented when starting ngrok.

  2. Set the newly configured server item as active in mdmctl.
    mdmctl config switch -name UNIQUE_NAME

    Use the UNIQUE_NAME value that you entered in the previous command.

4. Start the micromdm Server

  1. Create a folder to serve as a file repo location
    mkdir -p /Users/USERNAME/Documents/micromdm/filerepo

    USERNAME is your local account username
    The repo can go anywhere else as well (ex. /opt/micromdm/filerepo)

  2. Start micromdm in its own Terminal Window
    sudo micromdm serve -server-url=NGROK_URL -api-key SUPER_SECRET_TOKEN -filerepo /Users/USERNAME/Documents/micromdm/filerepo -tls=false

    SUPER_SECRET_TOKEN is the same value that you used when configuring mdmctl.
    NGROK_URL is the same url that you used when configuring mdmctl.

5. Get and Apply a Push Certificate

Every Apple MDM instance needs a push certificate to communicate with clients. You can get a free push certificate for your organization using the steps below. Described in more detail HERE.

  1. Register for a mdmcert.download account HERE

  2. Verify your email address using the verification email sent to you.

  3. Create a new request using mdmctl
    mdmctl mdmcert.download -new -email=your-email@example.org
    Replace the "-email" parameter value with the email you used to register in Step 1.

  4. In a few minutes, you will get an email with a signed request attachment. Download the attachment.

  5. Decrypt the signed request using mdmctl
    cd ~/Documents/micromdm
    mdmctl mdmcert.download -decrypt=~/Downloads/YOUR_ATTACHMENT.p7

    YOUR_ATTACHMENT refers to the file that you downloaded in the last step.

  6. A file called mdmcert.download.push.req is generated in the current working directory. Upload the file to https://identity.apple.com by using the green 'Create a Certificate' button at top right. You will then be able to download an actual Push Certificate! The filename will be similar to MDM_ McMurtrie Consulting LLC_Certificate.pem (note the accompanying private key will be in mdmcert.download.push.key.

  7. Upload the certificate to micromdm using mdmctl
    mdmctl mdmcert upload -cert="~/Downloads/MDM_ McMurtrie Consulting LLC_Certificate.pem" -private-key=~/Documents/micromdm/mdmcert.download.push.key

6. Get and Apply a DEP Token

To connect your micromdm instance to DEP, follow these steps. Described in more detail HERE

  1. Extract the public key which you will need to upload, using mdmctl
    mdmctl get dep-tokens -export-public-key ~/Documents/micromdm/DEP_Public_key.pem

  2. Go to the DEP portal and create a "MDM Server" (as its called in the DEP portal) record. You will be prompted to upload the DEP_Public_key.pem file. Once you successfully create the server, you'll be offered a new download - a file ending .p7m. This files contains the encrypted DEP tokens.

  3. Import the downloaded p7m file using mdmctl
    mdmctl apply dep-tokens -import ~/Downloads/MY_DEP_TOKEN.p7m

    MY_DEP_TOKEN refers to the file you downloaded in Step 2.

To continue your micromdm setup go to Configuring a MicroMDM Imaging Setup

Clone this wiki locally