Merge pull request #440 from smallstep/carl/tweaks

tashian · web-flow · commit 0b37b90fdc01 · 2025-10-02T10:23:13.000-07:00
Small changes
diff --git a/step-ca/acme-basics.mdx b/step-ca/acme-basics.mdx
@@ -1,5 +1,5 @@
 ---
-updated_at: September 18, 2025
+updated_at: October 02, 2025
 title: ACME Basics
 html_title: ACME Protocol Basics for step-ca Users
 description: Learn ACME protocol fundamentals for step-ca. Implement automated certificate management using industry-standard protocols.
@@ -26,8 +26,8 @@ ACME is a modern, standardized protocol for automatic validation and issuance of
 
 ## Requirements
 
-- **Open source -** This tutorial assumes you have initialized and started up a `step-ca` server (see [Getting Started](./getting-started.mdx)).
-- **[Smallstep Certificate Manager](https://smallstep.com/certificate-manager) -** follow the instructions provided in the Certificate Manager [ACME documentation](../certificate-manager/acme/README.mdx).
+This tutorial assumes you have initialized and started up a `step-ca` server (see [Getting Started](./getting-started.mdx)),
+[Smallstep Certificate Manager](https://smallstep.com/certificate-manager), or other ACME server.
 
 ## Overview
 
@@ -40,15 +40,12 @@ ACME is a modern, standardized protocol for automatic validation and issuance of
 ## Why ACME?
 
 With ACME, machines can get certificates from a CA without any human interaction involved.
+It is used by public Web PKI CAs (eg. Let's Encrypt) and by private, internal CAs.
 
-For example, you can:
-
-- Use ACME in production to issue X.509 certificates to internal workloads, proxies, queues, databases, etc. so you can use mutual TLS for authentication and encryption.
-- Simulate Let’s Encrypt’s certificate authority in development and
-  pre-production scenarios where connecting to [Let’s Encrypt’s staging
-  server][le-staging] is problematic.
-
-[le-staging]: https://letsencrypt.org/docs/staging-environment/
+ACME allows the CA to prove that a client controls a set of resources for the purpose of certificate issuance.
+ACME doesn't restrict _who_ can make requests of the CA.
+There is an extension to ACME called External Account Binding (EAB) which adds keys for ACME accounts,
+and this feature is available in Smallstep's commercial CA software.
 
 ## A Typical ACME Flow
 
diff --git a/tutorials/connect-jamf-pro-to-smallstep.mdx b/tutorials/connect-jamf-pro-to-smallstep.mdx
@@ -1,5 +1,5 @@
 ---
-updated_at: September 19, 2025
+updated_at: October 02, 2025
 title: Connect Jamf Pro to Smallstep
 html_title: Integrate Jamf Pro with Smallstep Tutorial
 description: Integrate Jamf Pro with Smallstep for Apple device security. Complete guide for enforcing device trust in macOS and iOS environments.
@@ -44,20 +44,17 @@ This API client will allow Smallstep to read your Jamf device inventory and mana
 1. In Jamf Pro, choose ⚙️ **Settings**
 2. Under the **System** tab, choose **API Roles and Clients**
 3. Add an **API Role**
-
-    Display name: Smallstep
-
-    For Privileges, choose:
-
-    - Read Mobile Devices
-    - Read Computers
+    - Display name: Smallstep
+    - Privileges:
+      - Read Mobile Devices
+      - Read Computers
 4. Next, in the **API Clients** tab, add a **Client**
     - Display name: Smallstep
     - API Roles: Smallstep
     - Enabled: Yes, choose Enable
-    - Choose **Save**
-5. Choose **Generate client secret**
-6. Temporarily save the **Client ID** and **Client Secret**. You’ll use them in the next step.
+5. Choose **Save**
+6. Choose **Generate client secret**
+7. Temporarily save the **Client ID** and **Client Secret**. You’ll use them in the next step.
 
 ## Connect Jamf Pro to Smallstep
 
@@ -76,14 +73,14 @@ For compatibility reasons, Smallstep may use ACME or SCEP for certificate enroll
 1. In Jamf Pro, choose ⚙️ **Settings**
 2. Under the **Global** tab, Choose **Webhooks**
 3. Add a new Webhook
-    1. Display name: Smallstep
-    2. Webhook URL: (details from step #2)
-    3. Authentication Type: Basic
-        1. Basic Authentication Username: (details from step #2)
-        2. Basic Authentication Password: (details from step #2)
-        3. Basic Authentication Verify Password: (details from step #2)
-    4. Content Type: JSON
-    5. Webhook Event: SCEPChallenge
+    - Display name: Smallstep
+    - Webhook URL: (details from step #2)
+    - Authentication Type: Basic
+        - Basic Authentication Username: (details from step #2)
+        - Basic Authentication Password: (details from step #2)
+        - Basic Authentication Verify Password: (details from step #2)
+    - Content Type: JSON
+    - Webhook Event: SCEPChallenge
 4. Choose **Save**
 
 Your Smallstep team is now linked to Jamf Pro. Smallstep will do a partial sync of your device inventory from Jamf every hour, and a full sync every 8 hours.
@@ -103,8 +100,8 @@ In this step, you’ll upload the Smallstep agent package to Jamf Pro’s softwa
 2. In Jamf Pro, choose ⚙️ **Settings**
 3. Under the **Computer Management** tab, Choose **Packages**
 4. Add a new Package
-    1. Display name: Smallstep Agent
-    2. Filename: (upload from step #1)
+    - Display name: Smallstep Agent
+    - Filename: (upload from step #1)
 5. Choose **Save**
 
 #### Create an Agent Bootstrap Script
@@ -113,9 +110,9 @@ This step will install a script on your client devices that bootstraps the conne
 
 1. In Jamf Pro, choose ⚙️ **Settings**
 2. Under the **Computer Management** tab, Choose **Scripts**
-3. Add a new Script
-    1. In the **General tab**, for **Display Name**: `Smallstep Agent Install`
-    2. In the Script tab:
+3. Add a new Script:
+    - In the **General tab**, for **Display Name**: `Smallstep Agent Install`
+    - In the Script tab:
         - Mode: `Shell/Bash`
         - Content:
 
@@ -225,14 +222,15 @@ The devices that you scoped will receive a certificate and have the agent instal
 
 By default, Jamf will attempt to re-deploy the configured package profile to every scoped Computer on a cadence. Each Computer will attempt to install the distributed package, regardless of any existing version already installed. The Smallstep Agent pkg has built-in logic to skip any unnecessary install logic when the currently installed version matches the version being distributed. However, configuring Jamf to prevent identical package re-deploys can reduce wasted cycles across your entire fleet of managed computers as well as reduce resource usage of your Jamf tenant.
 
-1. In Jamf Pro Configure an Extension Attribute that reports the currently installed version on each computers
+1. In Jamf Pro, Configure an Extension Attribute that reports the currently installed version on each computers
     1. In Jamf Pro under Settings → Computer Management → Extension Attributes → New
         - Display Name: SmallstepAgent Version
         - Data type: String
         - Inventory display: General
         - Input Type: Script
             - Mode: Shell/Bash
-            -
+            - Content:
+
                 ```shell
                 #!/bin/bash
 
@@ -251,7 +249,7 @@ By default, Jamf will attempt to re-deploy the configured package profile to eve
                 fi
                 ```
         - Save
-2. In Jamf Pro Create a new Smart Computer Group
+2. In Jamf Pro, Create a new Smart Computer Group
     1. In Jamf Pro, go to Computers → Smart Computer Groups → New
     2. On the Computer Group tab
         - Display Name: Needs SmallstepAgent Version
diff --git a/tutorials/docker-tls-certificate-authority.mdx b/tutorials/docker-tls-certificate-authority.mdx
@@ -1,5 +1,5 @@
 ---
-updated_at: September 18, 2025
+updated_at: October 02, 2025
 title: Run a private online TLS certificate authority in a Docker container
 html_title: Run step-ca in Docker Container Tutorial
 description: Run step-ca certificate authority in Docker. Containerized PKI deployment for modern infrastructure environments with easy scalability options.
@@ -47,7 +47,7 @@ The following environment variables are available for CA configuration:
 - `DOCKER_STEPCA_INIT_NAME` (**required**) the name of your CA—this will be the issuer of your CA certificates
 - `DOCKER_STEPCA_INIT_DNS_NAMES` (**required**) the hostname(s) or IPs that the CA will accept requests on
 - `DOCKER_STEPCA_INIT_PROVISIONER_NAME` a label for the initial admin (JWK) provisioner. Default: "admin"
-- `DOCKER_STEPCA_INIT_SSH` set this to a non-empty value to create an SSH CA
+- `DOCKER_STEPCA_INIT_SSH` set this to `true` to create an SSH CA
 - `DOCKER_STEPCA_INIT_PASSWORD`  specify a password for the encrypted CA keys and the default CA provisioner. A password is generated by default. Note: In a production environment, a more secure option for specifying a password is to use the manual installation process, below.
 
 Once `step-ca` is running, the CA's URL and SHA256 fingerprint are all clients need to bootstrap with the CA.
diff --git a/tutorials/intermediate-ca-new-ca.mdx b/tutorials/intermediate-ca-new-ca.mdx
@@ -2,7 +2,7 @@
 title: Use step-ca with your existing CA
 html_title: Deploy Intermediate CA with Existing Root
 description: Use step-ca as intermediate CA with existing infrastructure. Modernize PKI while preserving root certificate investments and trust chains.
-updated_at: September 17, 2025
+updated_at: October 02, 2025
 ---
 
 Need to extend or migrate from an existing CA to a Smallstep CA?
@@ -24,7 +24,7 @@ while still issuing certificates trusted by your existing clients.
 </Alert>
 
 This tutorial covers three ways of bootstrapping a Smallstep CA
-using an existing PKI.
+that can run in parallel with your existing PKI.
 
 ## About this tutorial
 
@@ -35,13 +35,13 @@ using an existing PKI.
 
 <Alert severity="info">
   <div>
-    If you run into any issues please let us know <a href="https://github.com/smallstep/certificates/discussions">in GitHub Discussions</a>.
+    If you run into any issues please let us know <a href="https://github.com/smallstep/certificates/discussions">in GitHub Discussions</a> or <a href="https://u.step.sm/discord">Discord</a>.
   </div>
 </Alert>
 
 ## Requirements
 
-This tutorial assumes you have initialized and started up a `step-ca` instance using the steps in [Getting Started](../step-ca/getting-started.mdx).
+This tutorial assumes you have initialized and started a `step-ca` instance using the steps in [Getting Started](../step-ca/getting-started.mdx).
 You'll also need the ability to sign a new intermediate CA
 using your existing CA.
 You can use your existing root
@@ -158,6 +158,8 @@ To generate those artifacts run:
 step certificate create "Intermediate CA Name" intermediate.csr intermediate_ca_key --csr
 ```
 
+In this example, we're generating the Intermediate CA key on the filesystem. For stronger key protection, use our [cryptographic protection](../step-ca/cryptographic-protection.mdx) features to generate the signing key inside a Key Management System (KMS) instead.
+
 ### 3. Transfer the CSR file and get it signed.
 
 Now, you will need to transfer the CSR (intermediate.csr) file to your existing root CA and get it signed. Below we have examples of
