From 3e47e62fff86d57382561d4b44753447b01f0d95 Mon Sep 17 00:00:00 2001 From: Carl Tashian Date: Mon, 8 Dec 2025 17:58:48 +0000 Subject: [PATCH 1/4] Enterprise relay docs --- manifest.json | 4 ++ tutorials/configure-enterprise-relay.mdx | 80 ++++++++++++++++++++++++ 2 files changed, 84 insertions(+) create mode 100644 tutorials/configure-enterprise-relay.mdx diff --git a/manifest.json b/manifest.json index 463512de..47e9b1a8 100644 --- a/manifest.json +++ b/manifest.json @@ -76,6 +76,10 @@ { "title": "Configure Browser Certificates", "path": "/tutorials/browser-certificate-setup-guide.mdx" + }, + { + "title": "Configure Enterprise Relay", + "path": "/tutorials/configure-enterprise-relay.mdx" } ] }, diff --git a/tutorials/configure-enterprise-relay.mdx b/tutorials/configure-enterprise-relay.mdx new file mode 100644 index 00000000..647fc549 --- /dev/null +++ b/tutorials/configure-enterprise-relay.mdx @@ -0,0 +1,80 @@ +--- +title: Configure your endpoints for Smallstep Enterprise Relay +updated_at: December 08, 2025 +html_title: Configure your Apple endponts to use Smallstep's Enterprise MASQUE Relay +description: This tutorial describes how to deploy Smallstep's enterprise MASQUE relay service +--- + +## Before you begin + +To get your Relay set up, you will need to give Smallstep the following information: + +- **Relay Trust Bundle**. This will be used by the Relay to verify client certificates. +This bundle needs to include both Root and Intermediate CA certificates for any CAs you want your Relay to trust. +These can include Smallstep or custom CAs. +A typical configuration will include the Smallstep Account Root and Intermediate CA. +- **Relay Region**. The GCP region for the relay, eg. `US_CENTRAL1` + +## Client Configuration + +Once we have your details, +Smallstep will create your relay server and give you the Relay URL, +which you’ll need to configure clients. + +Your new Relay will accepts client certificates from the CAs you asked us to configure in the Relay Trust Bundle. +Usually this will include your team’s Accounts Intermediate CA. +If they will use ACME Device Attestation, your clients will need to trust the Accounts Root CA. +You can download the Accounts Root CA certificate from your [Authorities](https://smallstep.com/app/?next=/cm/authorities) page. + +The Relay’s server certificate is issued by your team’s Workloads Intermediate CA. +So, your clients will need to trust the Workloads Root CA. +You can download the Workloads Root CA certificate from your [Authorities](https://smallstep.com/app/?next=/cm/authorities) page. + +## Example: Create a Jamf Configuration Profile + +In this example, we’ll use Jamf Pro to configure endpoints connecting to a Smallstep Relay. + +**In the Smallstep console:** + +1. Visit [Authorities](https://smallstep.com/app/?next=/cm/authorities). + 1. Select the **Smallstep Accounts** authority + 2. Download the Root Certificate + 3. Under the Provisioners section of the page, choose the provisioner named `acme-da` + 4. Temporarily save the **URL shown on the page, eg.** `https://accounts.example.ca.smallstep.com/acme/acme-da/directory` +2. Return to [Authorities](https://smallstep.com/app/?next=/cm/authorities) + 1. Select the **Smallstep Workloads** authority + 2. Download the Root Certificate + +**In Jamf Pro:** + +1. Choose 🖥️ **Computers** +2. Under the **Content Management** tab, choose **Configuration Profiles** +3. Add a new Configuration Profile + 1. Choose **Options → General** + - Name: Smallstep + 2. For ACME CA trust, add a [**Certificate payload**](https://support.apple.com/guide/deployment/certificates-payload-settings-dep91d2eb26/web) + - Certificate Name: **Smallstep Accounts Authority** + - Certificate Option: **Upload** + - Certificate Upload: (upload the Accounts Root CA certificate) + - Allow all apps access: ☑️ + 3. For Relay server trust, add a [**Certificate payload](https://support.apple.com/guide/deployment/certificates-payload-settings-dep91d2eb26/web)** + - Certificate Name: **Smallstep Workloads Authority** + - Certificate Option: **Upload** + - Certificate Upload: (upload the Workloads Root CA certificate) + - Allow all apps access: ☑️ + 4. Add a [ACMECertificate Payload](https://support.apple.com/guide/deployment/automated-certificate-management-environment-depb95c66a07/web) + - URL: (paste the ACME provisioner URL you saved earlier) + - Name: Smallstep + - Redistribute Profile: 7 days + - Key Size: `384` + - Key Type: `ECSECPrimeRandom` + - Client Identifier: `$SERIALNUMBER` + - Subject: `/CN=$SERIALNUMBER/L=$PROFILEIDENTIFIER` + - Hardware Bound: ✅ + - Attest: ✅ + - Key Usage: `0xB` + - Extended Key Usage: `1.3.6.1.5.5.7.3.2\` + 5. Add a [Relay payload](https://developer.apple.com/documentation/devicemanagement/relay) + 1. Relays: Add the URL for your Smallstep Enterprise Relay + 2. Match domains: Up to you + 3. Exclude domains: Up to you From efb1521f537fcb1bbc2b9f7718ba4e4ea2b38b37 Mon Sep 17 00:00:00 2001 From: Carl Tashian Date: Mon, 8 Dec 2025 18:06:08 +0000 Subject: [PATCH 2/4] Tweaks --- tutorials/configure-enterprise-relay.mdx | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-) diff --git a/tutorials/configure-enterprise-relay.mdx b/tutorials/configure-enterprise-relay.mdx index 647fc549..49349531 100644 --- a/tutorials/configure-enterprise-relay.mdx +++ b/tutorials/configure-enterprise-relay.mdx @@ -11,8 +11,7 @@ To get your Relay set up, you will need to give Smallstep the following informat - **Relay Trust Bundle**. This will be used by the Relay to verify client certificates. This bundle needs to include both Root and Intermediate CA certificates for any CAs you want your Relay to trust. -These can include Smallstep or custom CAs. -A typical configuration will include the Smallstep Account Root and Intermediate CA. +A typical configuration will include your team's Smallstep Accounts Root and Intermediate CA. - **Relay Region**. The GCP region for the relay, eg. `US_CENTRAL1` ## Client Configuration @@ -30,17 +29,17 @@ The Relay’s server certificate is issued by your team’s Workloads Intermedia So, your clients will need to trust the Workloads Root CA. You can download the Workloads Root CA certificate from your [Authorities](https://smallstep.com/app/?next=/cm/authorities) page. -## Example: Create a Jamf Configuration Profile +## Example: Jamf Pro Configuration Profile In this example, we’ll use Jamf Pro to configure endpoints connecting to a Smallstep Relay. **In the Smallstep console:** -1. Visit [Authorities](https://smallstep.com/app/?next=/cm/authorities). +1. Visit [Authorities](https://smallstep.com/app/?next=/cm/authorities) 1. Select the **Smallstep Accounts** authority 2. Download the Root Certificate 3. Under the Provisioners section of the page, choose the provisioner named `acme-da` - 4. Temporarily save the **URL shown on the page, eg.** `https://accounts.example.ca.smallstep.com/acme/acme-da/directory` + 4. Temporarily save the **URL shown on the page**, eg. `https://accounts.example.ca.smallstep.com/acme/acme-da/directory` 2. Return to [Authorities](https://smallstep.com/app/?next=/cm/authorities) 1. Select the **Smallstep Workloads** authority 2. Download the Root Certificate @@ -52,12 +51,12 @@ In this example, we’ll use Jamf Pro to configure endpoints connecting to a Sma 3. Add a new Configuration Profile 1. Choose **Options → General** - Name: Smallstep - 2. For ACME CA trust, add a [**Certificate payload**](https://support.apple.com/guide/deployment/certificates-payload-settings-dep91d2eb26/web) + 2. For ACME CA trust, add a **[Certificate payload](https://support.apple.com/guide/deployment/certificates-payload-settings-dep91d2eb26/web)** - Certificate Name: **Smallstep Accounts Authority** - Certificate Option: **Upload** - Certificate Upload: (upload the Accounts Root CA certificate) - Allow all apps access: ☑️ - 3. For Relay server trust, add a [**Certificate payload](https://support.apple.com/guide/deployment/certificates-payload-settings-dep91d2eb26/web)** + 3. For Relay server trust, add a **[Certificate payload](https://support.apple.com/guide/deployment/certificates-payload-settings-dep91d2eb26/web)** - Certificate Name: **Smallstep Workloads Authority** - Certificate Option: **Upload** - Certificate Upload: (upload the Workloads Root CA certificate) From e4485a638ba932345148007c5d61307139c9b816 Mon Sep 17 00:00:00 2001 From: Carl Tashian Date: Mon, 8 Dec 2025 20:38:28 +0000 Subject: [PATCH 3/4] Update tutorials/configure-enterprise-relay.mdx Co-authored-by: Max --- tutorials/configure-enterprise-relay.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tutorials/configure-enterprise-relay.mdx b/tutorials/configure-enterprise-relay.mdx index 49349531..55405cbf 100644 --- a/tutorials/configure-enterprise-relay.mdx +++ b/tutorials/configure-enterprise-relay.mdx @@ -20,7 +20,7 @@ Once we have your details, Smallstep will create your relay server and give you the Relay URL, which you’ll need to configure clients. -Your new Relay will accepts client certificates from the CAs you asked us to configure in the Relay Trust Bundle. +Your new Relay will accept client certificates from the CAs you asked us to configure in the Relay Trust Bundle. Usually this will include your team’s Accounts Intermediate CA. If they will use ACME Device Attestation, your clients will need to trust the Accounts Root CA. You can download the Accounts Root CA certificate from your [Authorities](https://smallstep.com/app/?next=/cm/authorities) page. From 097741ff04f5ccf20aa6cb0200e6c2fe70c246d4 Mon Sep 17 00:00:00 2001 From: Carl Tashian Date: Mon, 8 Dec 2025 20:51:18 +0000 Subject: [PATCH 4/4] Clarity --- tutorials/configure-enterprise-relay.mdx | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/tutorials/configure-enterprise-relay.mdx b/tutorials/configure-enterprise-relay.mdx index 55405cbf..e7dd5ff3 100644 --- a/tutorials/configure-enterprise-relay.mdx +++ b/tutorials/configure-enterprise-relay.mdx @@ -20,13 +20,12 @@ Once we have your details, Smallstep will create your relay server and give you the Relay URL, which you’ll need to configure clients. -Your new Relay will accept client certificates from the CAs you asked us to configure in the Relay Trust Bundle. -Usually this will include your team’s Accounts Intermediate CA. -If they will use ACME Device Attestation, your clients will need to trust the Accounts Root CA. +For most customers, the Relay will accept client certificates from your team's Smallstep Accounts CA. +And, therefore, your clients will need to trust your team's Smallstep Accounts Root CA. You can download the Accounts Root CA certificate from your [Authorities](https://smallstep.com/app/?next=/cm/authorities) page. -The Relay’s server certificate is issued by your team’s Workloads Intermediate CA. -So, your clients will need to trust the Workloads Root CA. +For most customers, the Relay’s server certificate is issued by your team’s Workloads CA. +And, therefore, your clients will need to trust your team's Smallstep Workloads Root CA. You can download the Workloads Root CA certificate from your [Authorities](https://smallstep.com/app/?next=/cm/authorities) page. ## Example: Jamf Pro Configuration Profile