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..e7dd5ff3 --- /dev/null +++ b/tutorials/configure-enterprise-relay.mdx @@ -0,0 +1,78 @@ +--- +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. +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 + +Once we have your details, +Smallstep will create your relay server and give you the Relay URL, +which you’ll need to configure clients. + +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. + +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 + +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