Merge pull request #471 from smallstep/carl/con-302

Enterprise relay setup doc

Author: tashian

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"
             }
           ]
         },

tutorials/configure-enterprise-relay.mdx

@@ -0,0 +1,83 @@
+---
+title: Configure your endpoints for Smallstep Enterprise Relay
+updated_at: December 16, 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 create your Relay server, you will need to give Smallstep the following information:
+
+- **Relay Region**. The GCP region for the relay, eg. `US_CENTRAL1`
+- **Relay Trust Bundle** (optional). 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.
+By default, your team's Smallstep Accounts Root and Intermediate CAs are trusted.
+- **Relay Issuing Authority** (optional). The CA that will issue the Relay's server TLS certificate.
+This must be a Smallstep CA in your team.
+By default, your team's Smallstep Workloads CA is used.
+
+Once we have your details,
+Smallstep will create your relay server and respond with a **Relay URL**,
+which you’ll need for configuring clients.
+
+## Typical Client Configuration
+
+On Apple platforms, a typical client could be configured as follows:
+
+- **Workloads CA Trust**: The Relay’s server certificate is issued by your team’s Workloads CA.
+Therefore, the client must trust your team's Workloads Root CA to connect to the relay.
+You can download the Workloads Root CA certificate from your [Authorities](https://smallstep.com/app/?next=/cm/authorities) page.
+- **Accounts CA Trust**: To obtain its client certificate, the client must 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.
+- **Client Certificate**: An [ACMECertificate MDM payload](https://support.apple.com/guide/deployment/automated-certificate-management-environment-depb95c66a07/web) is used to obtain a client certificate for accessing the Relay.
+- **Relay Configuration**: The Relay is configured using a [Relay MDM payload](https://developer.apple.com/documentation/devicemanagement/relay)
+
+## 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. 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