Skip to content

fix: hydration error on smallstep.com #472

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
C-Mejlak wants to merge 1 commit into
base: main
Choose a base branch
from
Open

fix: hydration error on smallstep.com #472

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 6 additions & 6 deletions platform/README.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)

<Alert severity="info">
<div>
<p><strong>💡 What about MDM’s that do not support Dynamic SCEP? </strong></p>
<p>There are two main approaches to using SCEP as a certificate enrollment protocol: static and dynamic. </p>
**💡 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.

<p>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.</p>
<p>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.</p>
</div>
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.
</Alert>

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.
Expand Down
11 changes: 3 additions & 8 deletions platform/core-concepts.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

<Alert severity="info">
<div>
A note on BYO devices
<p>
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.
</p>
</div>

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.
</Alert>

## Smallstep Agent
Expand Down Expand Up @@ -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

<Alert severity="info">
<div>
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.
</div>
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.
</Alert>

### A note about provisioned credentials
Expand Down
60 changes: 25 additions & 35 deletions step-ca/provisioners.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

<Alert severity="warning">
<div>
<p><b>May I edit <Code>ca.json</Code> directly?</b></p>
<p>You may edit your <Code>ca.json</Code> configuration file directly, but we strongly recommend using <a href="https://smallstep.com/docs/step-cli/reference/ca/provisioner"><Code>step ca provisioner</Code></a> commands instead.
Fields in <Code>ca.json</Code> may be encoded differently than you expect.</p>
</div>
**May I edit `ca.json` directly?**

You may edit your `ca.json` configuration file directly, but we strongly recommend using <a href="https://smallstep.com/docs/step-cli/reference/ca/provisioner">`step ca provisioner`</a> commands instead.
Fields in `ca.json` may be encoded differently than you expect.
</Alert>

Some provisioner options override global defaults for your CA.
Expand Down Expand Up @@ -711,28 +710,26 @@ $ STEP_CONSOLE=true step ssh certificate carl carl.crt
#### Notes

<Alert severity="info">
<div>
<b>Why is the OAuth client secret unprotected?</b>
**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 <Code>/provisioners</Code> API endpoint.
Counterintuitively, this is a secure implementation of OAuth that conforms to the OAuth Best Current Practices for Native Apps (<a href="https://www.rfc-editor.org/rfc/rfc8252.html">RFC8252 / IETF BCP212</a>).
And it is the same approach that Google's <Code>gcloud</Code> 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 (<a href="https://www.rfc-editor.org/rfc/rfc8252.html">RFC8252 / IETF BCP212</a>).
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.
</div>
Bottom line, the OAuth flow implemented in `step` and `step-ca` is widely vetted and considered secure.
</Alert>

#### Further reading
Expand All @@ -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.

<Alert severity="warning">
<div>
<p><b>May I configure my CA's X5C provisioner accept its own root?</b></p>
<p>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.</p>
</div>
**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.
</Alert>

- Clients may request an X.509 or SSH certificate
Expand Down Expand Up @@ -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.

<Alert severity="info">
<div>
<p>
<strong>Note:</strong> 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 <a href="https://u.step.sm/discord">Discord</a> or in <a href="https://github.com/smallstep/certificates/discussions">GitHub Discussions</a> if you hit a blocker.
</p>
</div>
**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 <a href="https://u.step.sm/discord">Discord</a> or in <a href="https://github.com/smallstep/certificates/discussions">GitHub Discussions</a> if you hit a blocker.
</Alert>

#### Configure the Provisioner
Expand Down Expand Up @@ -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`.

<Alert severity="info">
<div>
<p><strong>Note:</strong> 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.</p>
</div>
**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.
</Alert>

### K8sSA - Kubernetes Service Account
Expand Down