From 2c654d0bb79ad54a86832037cba8449c04a06ee6 Mon Sep 17 00:00:00 2001 From: Christian Mejlak Date: Thu, 11 Dec 2025 15:48:27 +0100 Subject: [PATCH] fix: hydration error on smallstep.com Using `

` inside an `` results in nested paragraph tags, which is invalid HTML. This causes a hydration error. --- platform/README.mdx | 12 ++++---- platform/core-concepts.mdx | 11 ++----- step-ca/provisioners.mdx | 60 ++++++++++++++++---------------------- 3 files changed, 34 insertions(+), 49 deletions(-) diff --git a/platform/README.mdx b/platform/README.mdx index 34386520..e9df1df0 100644 --- a/platform/README.mdx +++ b/platform/README.mdx @@ -74,13 +74,13 @@ We offer integrations for any MDMs for Apple, Windows, and ChromeOS devices that ![Jamf MDM Marketecture.png](/graphics/Jamf_MDM_Marketecture.png) -

-

💡 What about MDM’s that do not support Dynamic SCEP?

-

There are two main approaches to using SCEP as a certificate enrollment protocol: static and dynamic.

+ **💡 What about MDM’s that do not support Dynamic SCEP?** + + There are two main approaches to using SCEP as a certificate enrollment protocol: static and dynamic. -

In static SCEP, a single challenge password is in every SCEP payload for every device. This practice is insecure and not recommended. Furthermore, it only shows a single user in reporting. We do not support this because we believe it's crucial to provide the most secure options for your infrastructure.

-

In contrast, for Dynamic SCEP, webhooks are used to generate new challenges and unique passwords for each device, and you would be able to see reporting for all devices.

-
+ In static SCEP, a single challenge password is in every SCEP payload for every device. This practice is insecure and not recommended. Furthermore, it only shows a single user in reporting. We do not support this because we believe it's crucial to provide the most secure options for your infrastructure. + + In contrast, for Dynamic SCEP, webhooks are used to generate new challenges and unique passwords for each device, and you would be able to see reporting for all devices. Smallstep can also be used as a drop-in replacement for Active Directory Certificate Services (ADCS), allowing you to transition from ADCS while still serving legacy workloads. We provide backwards-compatible support for SCEP and NDES, and also let you bring your existing Root CA with you, so you can get up and running in minutes. diff --git a/platform/core-concepts.mdx b/platform/core-concepts.mdx index 50bc1fb4..a5550977 100644 --- a/platform/core-concepts.mdx +++ b/platform/core-concepts.mdx @@ -57,12 +57,9 @@ With Smallstep, you can build a device inventory by syncing devices from your MD See our [Enrollment Guide](https://smallstep.com/docs/platform/enrollment-guide/) for details. -
A note on BYO devices -

- BYO devices pose a privacy challenge: Unique hardware identifiers cannot not be exposed to the organization when a device is used for both personal and organizational work. But, as long as we have a continuity of device identity across interactions with BYO devices, we don’t need to use permanent hardware identifiers. Instead, cryptographically secure software identifiers—scoped to the organization—can form a foundation for policy and authentication. BYO device identifiers aren’t usable for trust bootstrapping, though. The device’s owner will need to prove possession of the device before its identity can be trusted. -

-
+ + BYO devices pose a privacy challenge: Unique hardware identifiers cannot not be exposed to the organization when a device is used for both personal and organizational work. But, as long as we have a continuity of device identity across interactions with BYO devices, we don’t need to use permanent hardware identifiers. Instead, cryptographically secure software identifiers—scoped to the organization—can form a foundation for policy and authentication. BYO device identifiers aren’t usable for trust bootstrapping, though. The device’s owner will need to prove possession of the device before its identity can be trusted. ## Smallstep Agent @@ -219,9 +216,7 @@ This allows a third party to prove that a specific key is stored on *a specific - Trust profile: To keep these keys safe, you’re trusting the secure element manufacturer -
- Apple platforms do not provide user-space APIs for device attestations due to privacy concerns – hardware identifiers used for attestation can be used to identify a device and correlate end-user activity across remote systems in a way that violates end-user privacy expectations. For this reason, Apple limits hardware attestations to the Managed Device Attestation (MDA) workflow, using ACME DA, which is only available to managed devices in Supervised mode. -
+ Apple platforms do not provide user-space APIs for device attestations due to privacy concerns – hardware identifiers used for attestation can be used to identify a device and correlate end-user activity across remote systems in a way that violates end-user privacy expectations. For this reason, Apple limits hardware attestations to the Managed Device Attestation (MDA) workflow, using ACME DA, which is only available to managed devices in Supervised mode. ### A note about provisioned credentials diff --git a/step-ca/provisioners.mdx b/step-ca/provisioners.mdx index 99ade131..5144b050 100644 --- a/step-ca/provisioners.mdx +++ b/step-ca/provisioners.mdx @@ -100,11 +100,10 @@ provisioner for a given workload. Use the [`step ca provisioner`](../step-cli/reference/ca/provisioner) command group to add, remove, or modify provisioner configurations. Run these commands directly on your CA machine. They need to modify the `$(step path)/config/ca.json` configuration file. -
-

May I edit ca.json directly?

-

You may edit your ca.json configuration file directly, but we strongly recommend using step ca provisioner commands instead. -Fields in ca.json may be encoded differently than you expect.

-
+ **May I edit `ca.json` directly?** + + You may edit your `ca.json` configuration file directly, but we strongly recommend using `step ca provisioner` commands instead. + Fields in `ca.json` may be encoded differently than you expect. Some provisioner options override global defaults for your CA. @@ -711,28 +710,26 @@ $ STEP_CONSOLE=true step ssh certificate carl carl.crt #### Notes -
- Why is the OAuth client secret unprotected? + **Why is the OAuth client secret unprotected?** -When using the OIDC provisioner, you may notice that your OAuth client secret is visible to anyone via the CA's /provisioners API endpoint. -Counterintuitively, this is a secure implementation of OAuth that conforms to the OAuth Best Current Practices for Native Apps (RFC8252 / IETF BCP212). -And it is the same approach that Google's gcloud CLI tool uses for Google Cloud Platform authentication: An OAuth client secret is hardcoded into its source code. + When using the OIDC provisioner, you may notice that your OAuth client secret is visible to anyone via the CA's `/provisioners` API endpoint. + Counterintuitively, this is a secure implementation of OAuth that conforms to the OAuth Best Current Practices for Native Apps (RFC8252 / IETF BCP212). + And it is the same approach that Google's `gcloud` CLI tool uses for Google Cloud Platform authentication: An OAuth client secret is hardcoded into its source code. -So, what makes it secure? -The Authorization Code flow for native OAuth apps requires the redirect URI hostname be hardcoded as `127.0.0.1` (or `localhost`) in the client configuration. -This constraint obviates the need for a client secret, because the loopback address is inherently resistant to network attacks that the client secret is designed to mitigate in other, non-native app flows. + So, what makes it secure? + The Authorization Code flow for native OAuth apps requires the redirect URI hostname be hardcoded as `127.0.0.1` (or `localhost`) in the client configuration. + This constraint obviates the need for a client secret, because the loopback address is inherently resistant to network attacks that the client secret is designed to mitigate in other, non-native app flows. -An attacker in posession of the client secret would need local access to your device in order to compromise the flow. -OAuth in general is not very resistant to local attacks, so the threat model for the native app flow with an exposed client secret is the same as with any other OAuth flow: -It assumes that if you have a local attacker on your device, it's unlikely that this kind of attack is going to be your biggest threat. + An attacker in posession of the client secret would need local access to your device in order to compromise the flow. + OAuth in general is not very resistant to local attacks, so the threat model for the native app flow with an exposed client secret is the same as with any other OAuth flow: + It assumes that if you have a local attacker on your device, it's unlikely that this kind of attack is going to be your biggest threat. -The client secret is superfluous in the Authorization Code flow for native apps. -In fact, BCP212 has recommended that OAuth identity providers offer a special OAuth client type that has no client secret. -In practice, very few OAuth providers have implemented this "secretless" approach, so we don't yet support it. -Functionally, however, it is equivalent to having a public secret. + The client secret is superfluous in the Authorization Code flow for native apps. + In fact, BCP212 has recommended that OAuth identity providers offer a special OAuth client type that has no client secret. + In practice, very few OAuth providers have implemented this "secretless" approach, so we don't yet support it. + Functionally, however, it is equivalent to having a public secret. -Bottom line, the OAuth flow implemented in `step` and `step-ca` is widely vetted and considered secure. -
+ Bottom line, the OAuth flow implemented in `step` and `step-ca` is widely vetted and considered secure. #### Further reading @@ -748,10 +745,9 @@ It allows clients to use a different PKI to bootstrap trust. Configure this provisioner with a root CA certificate, and any certificate that chains up to that root can be used in a certificate request. -
-

May I configure my CA's X5C provisioner accept its own root?

-

We do not recommend it, because it will allow any user with a valid certificate from your PKI to get any kind of certificate. Configure X5C with the root of a more restricted CA, to ensure only specific people or machines can use the provisioner.

-
+ **May I configure my CA's X5C provisioner accept its own root?** + + We do not recommend it, because it will allow any user with a valid certificate from your PKI to get any kind of certificate. Configure X5C with the root of a more restricted CA, to ensure only specific people or machines can use the provisioner. - Clients may request an X.509 or SSH certificate @@ -1268,12 +1264,8 @@ This operation cannot be performed using an ECDSA key. Because [`step ca init`](../step-cli/reference/ca/init) creates an ECDSA chain by default, you will need to [convert your CA to use an RSA CA chain](../tutorials/rsa-chain.mdx) before using the SCEP provisioner. -
-

- Note: Some SCEP clients may fail if the intermediate CA certificate does not contain the right key usage extensions or does contain otherwise unexpected content. - Consult the documentation of your SCEP client for specific configuration required or ask us on Discord or in GitHub Discussions if you hit a blocker. -

-
+ **Note:** Some SCEP clients may fail if the intermediate CA certificate does not contain the right key usage extensions or does contain otherwise unexpected content. + Consult the documentation of your SCEP client for specific configuration required or ask us on Discord or in GitHub Discussions if you hit a blocker. #### Configure the Provisioner @@ -1334,9 +1326,7 @@ Finally, restart `step-ca`. Your SCEP provisioner is now available at the endpoint `http://ca.example.com:8080/scep/my_scep_provisioner`. -
-

Note: Some SCEP clients expect a specific path segment at the end of the SCEP URL (Cisco Catalyst switches, for example). For compatibility with these clients, the SCEP provisioner is also made available at any path segment beneath the configured provisioner endpoint.

-
+ **Note:** Some SCEP clients expect a specific path segment at the end of the SCEP URL (Cisco Catalyst switches, for example). For compatibility with these clients, the SCEP provisioner is also made available at any path segment beneath the configured provisioner endpoint. ### K8sSA - Kubernetes Service Account