Skip to content

Setup Guide

Jump to bottom
Jedda Wignall edited this page Nov 23, 2023 · 13 revisions

This article will walk you through some simple steps to get up and running with step-posture-connector and step-ca.

We'll assume you have a working online CA already setup with step-ca and will start with creation of ACME provisioners and adding webhooks. If you haven't already setup your step-ca, they have a great Getting Started article available here.

Setting up a compatible ACME provisioner in step-ca

The following steps will walk you through creating a Smallstep ACME provisioner compatible with step-posture-connector and an Apple device attestation challenge.

  1. Add a new ACME provisioner for Apple format device attestation:

    step ca provisioner add attestation --type ACME --challenge device-attest-01

  2. Optionally (but recommended), follow Smallstep's advice here to randomise the provisioner name and echo out your directory URI:

    PROVISIONER_NAME=$(< /dev/urandom LC_ALL=C tr -dc A-Za-z0-9 | head -c80)

    step ca provisioner update attestation --name $PROVISIONER_NAME

    echo /acme/$PROVISIONER_NAME/directory

You now have a provisioner that can issue ACME certificates to your Apple devices with a suitable ACME Certificate Payload.

Adding webhooks to your step-ca ACME provisioner

The following steps will help you add a webhook pointing at step-posture-connector. You'll need to sub in your provisioner name (which you may have randomised with the commands above) as well as the IP or hostname pointing to your instance of step-posture-connector:

  1. If you haven't already, follow the Smallstep guide to Enable Remote Provisioner Management for your CA.

  2. Add a webhook to your ACME provisioner pointing at step-posture-connector:

    step ca provisioner webhook add [provisioner_name] step-posture-connector --url https://[host or ip]:9443/webhook/device-attest

Make sure to take note of the Webhook ID and Webhook Secret generated and printed by step-ca. You'll need to provide them in your step-posture-connector configuration. Obviously if you've changed the port step-posture-connector runs on you'll need to reflect this in your webhook.

If you are planning on using Jamf as a provider; note that Macs require a ?mode=computer query to be added to your webhook.

Generating a server certificate to use with step-posture-connector

These steps will assist you in generating a server certificate and key to be used by step-posture-connector for it's built in HTTPS webhook server. Note that you don't have to use a TLS certificate generated by the same step-ca instance, but it certainly makes it simple to get things setup.

  1. Generate a certificate key and certificate for whatever hostname you are using for step-posture-connector (if you are running it on the same host as your step-ca instance this will be localhost):

    step ca certificate localhost server.pem server.key

Note that by default, step-ca issues certificates with a 24 hour expiry. If you are planning to automate new certificate issuance this might be fine, but many people will want a longer expiry. There are details on the step-ca website to lengthening your expiry times.

  1. Copy server.pem and server.key to a location accessible by step-posture-connector.

  2. Optionally if you want to enable mutual TLS between step-ca and step-posture-connector, you'll also need to copy your CA across to a location accessible by step-posture-connector:

    cp [stepca directory]/intermediate_ca.crt [location accessible by step-posture-connector]/ca.pem

Deploying step-posture-connector using Docker Compose

There are many ways to deploy step-posture-connector, but this guide will show you how to deploy it using Docker Compose.

  1. Ensure sure you have installed Docker and Docker Compose using the appropriate steps[https://docs.docker.com/compose/install/] for your OS.

  2. Modify the supplied docker-compose.yml file for your needs. This would include ensuring there is connectivity between your step-ca and step-posture-connector instances, and setting up your configuration environment variables.

Using enriched data in your step-ca X.509 templates

You can use templates to enrich certificates with the data returned from step-posture-connector. For more information see the step-ca template documentation.

Requesting ACME & MDA from your devices through MDM

You can use the following profile example to assist in instructing devices to perform MDA and request an ACME certificate:

https://gist.github.com/jedda/1f5c631f39b500fe2a769a228ef22572

At the present time, many MDMs (including Jamf Pro) do not have built in GUI support for the com.apple.security.acme so you'll likely need to edit the plist locally and upload it to your MDM.

Clone this wiki locally