From c1c18a651de8dadb4fffa111aad5f055e0df49c0 Mon Sep 17 00:00:00 2001 From: Linda Ikechukwu <32891838+Linda-Ikechukwu@users.noreply.github.com> Date: Mon, 15 May 2023 12:39:54 +0100 Subject: [PATCH 1/7] Update provisioners.mdx Suggesting several wording edits. - Removing future tense in favor of present tense - Changing plural to singular in several instances - Spelling out terms in clear on the first use before introducing an acronym - Several other wording and styling edits --- step-ca/provisioners.mdx | 297 ++++++++++++++++++++++++--------------- 1 file changed, 180 insertions(+), 117 deletions(-) diff --git a/step-ca/provisioners.mdx b/step-ca/provisioners.mdx index e9e9de83..0b298a26 100644 --- a/step-ca/provisioners.mdx +++ b/step-ca/provisioners.mdx @@ -60,45 +60,60 @@ Azure | ✔️ | ✔️ | 𝗫 | 𝗫 | ✔️ | 𝗫 | 𝗫 | 𝗫 | 𝗫 GCP | ✔️ | ✔️ | 𝗫 | 𝗫 | ✔️ | 𝗫 | 𝗫 | 𝗫 | 𝗫

- By design, SSH user certificates cannot be renewed by any provisioner. You can re-use the same key to get a new certificate, however. See [smallstep/discussions#1296](https://github.com/smallstep/certificates/discussions/1296). - Privileged OIDC subject names can generate Host SSH Certificates. These can be configured in the OIDC provisioner. -For an example of how to interpret this table, let's take the `JWK` provisioner. -The `JWK` provisioner is capable of signing, renewing, and revoking X.509 -certificates, as well signing user and host SSH certificates. A `JWK` provisioner -_cannot_ renew or rekey SSH certificates. +**Notes:** + +By design, SSH user certificates cannot be renewed by any provisioner. +However, you can re-use the same key to get a new certificate. +See [smallstep/discussions#1296](https://github.com/smallstep/certificates/discussions/1296). + + +Privileged OIDC subject names can generate Host SSH Certificates, +and can be configured in the OIDC provisioner. + -An `SSHPOP` provisioner _can_ revoke and rekey SSH certificates and renew SSH host -certificates. An `SSHPOP` provisioner _cannot_ sign, renew, or revoke X.509 -certificates, and it _cannot_ sign SSH user and host certificates or renew SSH -user certificates. +To illustrate how to interpret this table, let's take the `JWK` and `SSHPOP` provisioner. + +A `JWK` provisioner _can_ sign, renew, and revoke X.509 certificates, as well as sign user and host SSH certificates. +However, it _cannot_ renew or rekey SSH certificates. + +On the other hand, an `SSHPOP` provisioner _can_ revoke and rekey SSH certificates +and renew SSH host certificates. +However, it _cannot_ sign, renew, or revoke X.509 certificates. +Additionally, it _cannot_ sign SSH user and host certificates or renew SSH user certificates. It's important to understand the capabilities and limitations when selecting a provisioner for a given workload. ## Provisioner Management -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. +To add, remove, or modify provisioner configurations, +use the [`step ca provisioner`](../step-cli/reference/ca/provisioner) command group. +You must run these commands directly on your CA machine, +as they need to modify the `$(step path)/config/ca.json` configuration file.
-

May I edit ca.json directly?

+

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. -For a list of global options, see the [configuration guide](./configuration.mdx) section for the `authority` configuration block. +Within `ca.json` you can define an optional claims property for each provisioner. +The settings defined in the `claims` property of individual provisioners under an authority +override the global defaults set for that authority. +For a list of global options, +see the `claims` object under the authority configuration block in the [configuration guide](./configuration/#example-configuration). -A remote provisioner management API can be enabled in `step-ca`. -It is disabled by default. -With remote provisioner management, the CA's provisioner configuration is stored in the database instead of `ca.json`. (The global CA configuration remains in `ca.json`.) - -This feature can be useful if you +If you have multiple CA administrators, [run several load-balanced](./certificate-authority-server-production.mdx#load-balancing-or-proxying-step-ca-traffic) `step-ca` instances, -or if you want to manage your provisioners remotely (eg. with Infrastructure as Code (IaC) tools; [see below](#unattended-remote-provisioner-management)). +or if you want to manage your provisioners remotely (eg. with Infrastructure as Code (IaC) tools; [see below](#unattended-remote-provisioner-management)), you can enable the remote provisioner management API, which is disabled by default. + +With remote provisioner management enabled, +provisioner configurations are stored in the database instead of `ca.json`, +while the global CA configuration remains in `ca.json`. See [Remote Provisioner Management](#remote-provisioner-management) for more. @@ -111,7 +126,9 @@ Common provisioner operations include: - [Listing all provisioner](#list-all-provisioners) - [Modifying the configuration of an existing provisioner](#modify-a-provisioner) -Unless you are using [remote provisioner management](#remote-provisioner-management), you must send a `SIGHUP` signal, or restart the `step-ca` process, for changes to your provisioner configuration to take effect. +If you are not using [remote provisioner management](#remote-provisioner-management), +you must either restart the `step-ca` process +or send a `SIGHUP` signal to apply changes to your provisioner configuration. #### Add a provisioner @@ -131,8 +148,9 @@ Use [`step ca provisioner remove`](../step-cli/reference/ca/provisioner/remove) step ca provisioner remove acme ``` -You can also edit the `ca.json` configuration file and remove the entire block -containing the provisioner you'd like to remove. +Alternatively, +you can edit the `ca.json` configuration file, +and remove the entire block containing the provisioner you'd like to remove. #### List all provisioners @@ -140,7 +158,7 @@ To get a list of all of your current provisioners, use [`step ca provisioner lis #### Modify a provisioner -Use [`step ca provisioner update`](../step-cli/reference/ca/provisioner/update) to update provisioner configurations: +Use [`step ca provisioner update`](../step-cli/reference/ca/provisioner/update) to update provisioner configurations: ```bash step ca provisioner update acme \ @@ -149,20 +167,21 @@ step ca provisioner update acme \ --x509-default-dur=36h ``` -In this example we've modified the minumum, maximum, and default durations for TLS certificates generated by this provisioner. +The example above modifies the minumum, maximum, and default durations for X.509 certificates generated by the provisioner. +However, the `update` command can be used to modify the lifetimes, extensions, and templates of both X.509 and SSH certificates. -Provisioner configuration can be used to affect X.509 and SSH certificate lifetimes, extensions, and templates. -There are some provisioner-specific options, -which are covered by the documentation for each provisioner type, below. +Additionally, there are some provisioner-specific options, +which are covered by the documentation for each provisioner type [below](./provisioners/#provisioner-types). ## Remote Provisioner Management **This feature is disabled by default.** -When remote provisioner management is enabled, your provisioner configuration is -stored in the database, rather than in `ca.json`. -Provisioner configuration is managed by running [`step ca provisioner`](../step-cli/reference/ca/provisioner) commands locally or remotely. -These commands require you to sign in as an Admin user. +When remote provisioner management is enabled, +your provisioner configuration is stored in the database instead of in ca.json. +You can manage the provisioner configuration by running [`step ca provisioner`](../step-cli/reference/ca/provisioner) commands, +either locally or remotely. +However, you must sign in as an Admin user. ### Enable Remote Provisioner Management @@ -175,7 +194,7 @@ To enable remote provisioner management on a new CA, pass `--remote-management` #### On an Existing CA -To migrate your `ca.json` provisioners to the database, and to enable remote provisioner management on an existing CA: +To enable remote provisioner management on an existing CA and migrate your `ca.json` provisioners to the database: 1. Stop `step-ca` if it is running. 2. Update your `"authority"` block in `ca.json` to include the following: @@ -198,7 +217,7 @@ To migrate your `ca.json` provisioners to the database, and to enable remote pro * Create an initial Super Admin user, with username `step`, and link it to the administrative provisioner. 4. Remove old provisioner configurations from `ca.json`. - Once your provisioners are migrated to the database, the provisioners in `ca.json` are ignored and you can remove them from that file: + Once your provisioners are migrated to the database, the provisioners in `ca.json` are ignored and you can remove them: ```json "authority": { @@ -215,9 +234,9 @@ With remote provisioner management, #### Create An Admin User -To perform CA administrative operations, you sign into that provisioner as an Admin. +To perform CA administrative operations, you must sign into that provisioner as an Admin. -As a Super Admin, lets create an Admin user linked to the Admin JWK provisioner: +As a Super Admin, you can create an Admin user linked to the Admin JWK provisioner: ```bash step ca admin add carl "Admin JWK" @@ -241,13 +260,15 @@ An administrator is just a subject name and a provisioner name. You can authenticate as an administrator via the authentication scheme of the provisioner. For example, for the default JWK provisioner, running administrative commands in `step` will prompt for the provisioner password. -**Tip: Single Sign-On can be used for Admin users.** -To enable SSO CA administration, first add an [OIDC provisioner](#oauthoidc-single-sign-on) linked to your identity provider. -Then, add an Admin user associated with that provisioner, using your email address as the Admin's subject name. +***Tip: Single Sign-On (SS0) can be used for Admin users.*** +To enable CA administration via SSO, follow these steps: -The Admin and Super Admin privileges **are not scoped to a provisioner**: -Admins can modify any provisioner configurations. -Super Admins are Admins that can also modify Admins, regardless of provisioner. +1. Add an [OIDC provisioner](#oauthoidc-single-sign-on) linked to your identity provider. +2. Create an Admin user associated with that provisioner, using your email address as the Admin's subject name. + +It's important to note that the Admin and Super Admin privileges **are not scoped to a specific provisioner**. +Both Admins and Super Admins have the ability to modify configurations for any provisioner. +Then, Super Admins have the additional capability to modify Admins, regardless of the provisioner they are associated with. ### Use Remote Provisioner Management @@ -255,16 +276,15 @@ You're all set. 🎉 You can use the [`step ca provisioner`](../step-cli/reference/ca/provisioner) commands, from any client, to modify your CA's provisioner configuration. -#### Unattended Remote Provisioner Management +### Unattended Remote Provisioner Management -If you want to manage provisioners remotely using a script or an Infrastructure as Code (IaC) tool, -you will need an _administrative certificate_ and key. +To manage provisioners remotely using a script or an Infrastructure as Code (IaC) tool, +you need an _administrative certificate_ and key. An administrative certificate must meet the following criteria: - The Subject (or any SAN) must match the name of an Admin or Super Admin. - The certificate must be issued by the provisioner of the Admin or Super Admin. -- The certificate must be valid and unexpired. -- A passively revoked certificate is valid until it expires; for immediate revocation, remove the admin instead of revoking the certificate. +- The certificate must be valid and unexpired. A passively revoked certificate is valid until it expires; for immediate revocation, remove the admin instead of revoking the certificate. To create an admin certificate, run: @@ -282,7 +302,7 @@ Please enter the password to decrypt the provisioner key: ✔ Private Key: admin.key ``` -With that certificate, you can use it as follows: +Then, use that certificate as follows: ```bash step ca provisioner add ... --admin-cert=admin.crt --admin-key=admin.key @@ -299,14 +319,16 @@ step ca admin add ... --admin-cert=admin.crt --admin-key=admin_key ### JWK -JWK is the default provisioner type. It uses public-key cryptography to sign and +JWK is the default provisioner type. +It uses public-key cryptography to sign and validate a JSON Web Token (JWT). -The [`step`](https://github.com/smallstep/cli) CLI tool will create a JWK provisioner when [`step ca init`](../step-cli/reference/ca/init) is used. +Whenever you run [`step ca init`](../step-cli/reference/ca/init), +the [`step`](https://github.com/smallstep/cli) CLI tool creates a JWK provisioner. -#### Example +#### Examples: -Add a JWK provisioner: +#### Add a JWK provisioner: ```shell step ca provisioner add you@smallstep.com --create @@ -350,9 +372,14 @@ In the ca.json configuration file, a complete JWK provisioner example looks like } ``` -- **type**: for a JWK provisioner it must be `JWK`, this field is case insensitive. +Here's what property stands for: + +- **type**: is a case insensitive field that defines the provisioner type. For a JWK provisioner it must be `JWK`. -- **name**: identifies the provisioner, a good practice is to use an email address or a descriptive string that allows the identification of the owner, but it can be any non-empty string. +- **name**: identifies the provisioner. +It is recommended to use an email address +or a descriptive string that allows for easy identification of the owner. +However, any non-empty string works. - **key**: is the JWK (JSON Web Key) representation of a public key used to validate a signed token. @@ -362,7 +389,6 @@ It's a JWE compact string containing the JWK representation of the private key. This value is not necessary for CA operation, but is provided for the convenience of clients. Without the `encryptedKey` attribute, the private key must be provided by the client, using the `--key` flag. - - **claims**: overwrites the default claims set in the authority. See [claims](configuration.mdx#claims) for details. @@ -375,7 +401,7 @@ See [claims](configuration.mdx#claims) for details. #### Decrypting the private key -We can use [`step crypto jwe decrypt`](../step-cli/reference/crypto/jwe/decrypt) to see the private key encrypted with the password `asdf`: +You can use [`step crypto jwe decrypt`](../step-cli/reference/crypto/jwe/decrypt) to see the private key encrypted with the password `asdf`:
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. +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 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. +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. + +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. +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. +BCP212 recommends 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. +However, functionally, 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.
@@ -671,20 +708,25 @@ Bottom line, the OAuth flow implemented in `step` and `step-ca` is widely vetted ### X5C - X.509 Certificate -With the X5C provisioner, a client can authenticate a certificate request -using an existing X.509 certificate. Configure this provisioner with a root -CA certificate, and any certificate bundle that chains up to that root can +With the X5C provisioner, +a client can authenticate a certificate request using an existing X.509 certificate. +Configure this provisioner with a root CA certificate, +and any certificate bundle that chains up to that root can be used in a certificate request. +Here are some things to keep in mind when using an X5C provisioner: + - Clients may request an X.509 or SSH certificate - Clients must provide an X.509 certificate bundle whose root is trusted by the provisioner - Clients sign their request with the certificate private key - The validity period of the new certificate must fall within the validity period of the certificate used to authenticate the request -The X5C provisioner uses X5C tokens for authentication. An X5C token is a JWT, signed by the certificate private key, with an `x5c` header that contains the certificate bundle. +The X5C provisioner uses X5C tokens for authentication. +An X5C token is a JWT, signed by the certificate private key, +with an `x5c` header that contains the certificate bundle. -#### Example +#### Example: Create an X5C provisioner If you would like any certificate signed by `step-ca` to become a provisioner (have the ability to request new certificates with any name), @@ -695,8 +737,8 @@ you can create an X5C provisioner using the root certificate used by step ca provisioner add x5c-smallstep --type X5C --x5c-root $(step path)/certs/root_ca.crt ``` -Or, you can configure the X5C provisioner with an outside root, granting provisioner -capabilities to a completely separate PKI. +Or, you can configure the X5C provisioner with an outside root, +granting provisioner capabilities to a completely separate PKI. Below is an example of an X5C provisioner in the `ca.json`: @@ -766,25 +808,33 @@ see the [claims](configuration.mdx#claims) section for all the options. **This is an experimental feature.** -If you have a [Nebula overlay network](https://nebula.defined.net/docs/), you can create a Nebula provisioner and configure it with your Nebula root CA certificate. -Clients can then use their Nebula client certificate and private key to request an X.509 or SSH host certificate from `step-ca`. -The Nebula certificate they use for authentication must be issued by the Nebula root CA configured in the provisioner. +If you have a [Nebula overlay network](https://nebula.defined.net/docs/), +you can create a Nebula provisioner, +and configure it with your Nebula root CA certificate. +Clients can then use their Nebula client certificate +and private key to request an X.509 or SSH host certificate from `step-ca`. +However, the Nebula certificate used for authentication +must be issued by the Nebula root CA that is configured in the provisioner. -The Nebula client certificate is used for authorization, too: -The client is allowed to request an X.509 or SSH host certificate with the `name` or any of the `ips` appearing on the Nebula client certificate. +The Nebula client certificate can be used for authorization too. +The client is allowed to request an X.509 or SSH host certificate +with the `name` or any of the `ips` appearing on the Nebula client certificate. To be clear, Nebula certificates can contain a single `name` and a list of `ips`. The `name` field is often a DNS hostname, but it could be an email, IP, or URI. And `ips` contains a list of CIDR blocks. -In `step-ca`, the Nebula provisioner will authorize certificate subjects or SANs that include the `name`, plus IPs in any of the CIDR blocks in `ips` on the Nebula certificate. +In `step-ca`, the Nebula provisioner will authorize certificate subjects or SANs +that include the `name`, plus IPs in any of the CIDR blocks in `ips` on the Nebula certificate. -To get started, create a Nebula provisioner: +To create a Nebula provisioner, run: ```shell step ca provisioner add --type Nebula --nebula-root /etc/nebula/ca.crt ``` -Now you can get an X509 certificate with the Nebula provisioner, using a Nebula client certificate. Here's an example using the DNS name `host3.example.com`, and two IPs: +Now you can get an X509 certificate with the Nebula provisioner, +using a Nebula client certificate. +Here's an example using the DNS name `host3.example.com`, and two IPs: ```shell step ca certificate host3.example.com host3.crt host3.key \ @@ -798,7 +848,7 @@ step ca certificate host3.example.com host3.crt host3.key \ An SSHPOP provisioner allows a client to renew, revoke, or rekey an SSH certificate using that certificate for authentication with the CA. -The renew and rekey methods can only be used on SSH host certificates. +However, the renew and rekey operations are limited to SSH host certificates only. An SSHPOP provisioner is configured with the user and host root ssh certificates from the `ca.json`. The SSHPOP provisioner can only authenticate SSHPOP tokens @@ -807,18 +857,19 @@ generated using SSH certificates created by `step-ca`. An SSHPOP token is a JWT, signed by the certificate private key, with an `sshpop` header that contains the SSH certificate. -When configured with the `--ssh` option (`step ca init --ssh`), the CA -will contain a default SSHPOP provisioner named `sshpop`. +When configured with the `--ssh` option (i.e, `step ca init --ssh`), +the CA will contain a default SSHPOP provisioner named `sshpop`. -#### Example +#### Example: Add an SSHPOP provisioner: + +To create an SSHPOP provisioner, run: -Add an SSHPOP provisioner: ```shell step ca provisioner add sshpop --type SSHPOP ``` -An example SSHPOP provisioner in the `ca.json`: +An example SSHPOP provisioner in `ca.json`: ```json ... @@ -850,19 +901,25 @@ see the [claims](configuration.mdx#claims) section for all the options. ### ACME -The [ACME Protocol](https://tools.ietf.org/html/rfc8555) can authenticate Certificate Signing Requests (CSRs) in a way that enables automation. +The [ACME Protocol](https://tools.ietf.org/html/rfc8555) can authenticate Certificate Signing Requests (CSRs) +in a way that enables automation. + +ACME clients must answer challenges presented by the ACME server +to prove to the CA that they control the identifiers listed in the CSR. +ACME supports four different types of challenges: `http-01`, `dns-01`, `tls-alpn-01`, and `device-attest-01`. +These are designed for operability in different environments. -ACME clients must answer challenges presented by the ACME server to prove to the CA that they control the identifiers listed in the CSR. -ACME supports four different types of challenges: `http-01`, `dns-01`, `tls-alpn-01`, and `device-attest-01`. These are designed for operability in different environments. See [ACME Basics](./acme-basics.mdx#acme-challenges) for a description of each challenge type and their tradeoffs. -In a typical setup, an ACME server might issue server certificates via the `http-01`, `dns-01`, `tls-alpn-01` challenge types, and client certificates via the `device-attest-01` challenge type. +In a typical setup, +an ACME server might issue server certificates via the `http-01`, `dns-01`, `tls-alpn-01` challenge types, +and client certificates via the `device-attest-01` challenge type. The ACME provisioner in `step-ca` supports issuing X.509 certificates using IP, hostname, and device identifiers. -#### Example +#### Example: Add an ACME provisioner -Add an ACME provisioner: +To add an ACME provisioner: ```shell step ca provisioner add acme --type ACME @@ -941,7 +998,10 @@ for more guidance on configuring and using the ACME protocol with `step-ca`. -The `device-attest-01` challenge supports device attestations from iOS, iPadOS, tvOS, and YubiKeys. An attestation certificate is used to satisfy the ACME challenge. The CSR may include a device ID in a `permanentIdentifier` SAN ([RFC 4043](https://www.rfc-editor.org/rfc/rfc4043.html)), depending on the application. +The `device-attest-01` challenge supports device attestations from iOS, iPadOS, tvOS, and YubiKeys. +An attestation certificate is used to satisfy the ACME challenge. +The CSR may include a device ID in a `permanentIdentifier` SAN ([RFC 4043](https://www.rfc-editor.org/rfc/rfc4043.html)), +depending on the application. ##### Managed Device Attestation for Apple Devices @@ -962,13 +1022,13 @@ step ca provisioner add acme-da \ -In your Apple MDM profile, you will need: +In your Apple MDM profile, you need: * A [`CertificateRoot`](https://developer.apple.com/documentation/devicemanagement/certificateroot) payload, containing your root CA certificate PEM block, so that it's trusted by the device. * An [`ACMECertificate`](https://developer.apple.com/documentation/devicemanagement/acmecertificate) payload. For this one, set the `ClientIdentifier` to the UDID or serial number of the device. ##### Device Attestation for YubiKeys -To add a `device-attest-01` provisioner for YubiKey devices, run: +To create a `device-attest-01` provisioner for YubiKey devices, run: ```bash step ca provisioner add acme-da \ @@ -1014,11 +1074,13 @@ To get a client certificate for a hardware-bound private key on your YubiKey: ### SCEP -The SCEP provisioner can sign and renew certificates using the SCEP protocol ([RFC8894](https://datatracker.ietf.org/doc/html/rfc8894)). -SCEP is very popular for use in network equipment and mobile device management (MDM). -It runs over HTTP using POSTed binary data or base64-encoded GET parameters, -using CMS (PKCS#7) and CSR (PKCS#10) data formats. -A (shared) secret authenticates clients to the CA. +The SCEP provisioner can sign and renew certificates +using the Simple Certificate Enrollment Protocol SCEP protocol (SCEP) ([RFC8894](https://datatracker.ietf.org/doc/html/rfc8894)). +SCEP is popularly used for certificate management, +particularly in network equipment and mobile device management (MDM). +It runs over HTTP and uses POSTed binary data or base64-encoded GET parameters, +with CMS (PKCS#7) and CSR (PKCS#10) data formats, +and clients are authenticated to the CA using a shared secret. #### Requirements @@ -1026,7 +1088,8 @@ Your CA must use an RSA intermediate CA, even if your client supports ECDSA. The RSA intermediate is used to decrypt the contents of the SCEP `pkcsPKIEnvelope` containing the certificate request. 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. +[`step ca init`](../step-cli/reference/ca/init) creates an ECDSA chain by default, +so you must [convert your CA to use an RSA CA chain](../tutorials/rsa-chain.mdx) before using the SCEP provisioner.
@@ -1037,9 +1100,9 @@ Because [`step ca init`](../step-cli/reference/ca/init) creates an ECDSA chain b
-#### Configure the Provisioner +#### Configure the SCEP Provisioner -In this example, we will add a SCEP provisioner using challenge secret `secret1234` and `AES-256-CBC` as the [encryption algorithm](https://github.com/smallstep/pkcs7/blob/33d05740a3526e382af6395d3513e73d4e66d1cb/encrypt.go#L63): +In this example, the command below adds a SCEP provisioner using challenge secret `secret1234` and `AES-256-CBC` as the [encryption algorithm](https://github.com/smallstep/pkcs7/blob/33d05740a3526e382af6395d3513e73d4e66d1cb/encrypt.go#L63): ```shell step ca provisioner add my_scep_provisioner \ From 34951305a363fe7553273dc84394e88f7861ae88 Mon Sep 17 00:00:00 2001 From: Linda Ikechukwu <32891838+Linda-Ikechukwu@users.noreply.github.com> Date: Fri, 19 May 2023 20:46:08 +0100 Subject: [PATCH 2/7] Update provisioners.mdx --- step-ca/provisioners.mdx | 137 +++++++++++++++++++++++---------------- 1 file changed, 81 insertions(+), 56 deletions(-) diff --git a/step-ca/provisioners.mdx b/step-ca/provisioners.mdx index 0b298a26..3e948643 100644 --- a/step-ca/provisioners.mdx +++ b/step-ca/provisioners.mdx @@ -326,9 +326,7 @@ validate a JSON Web Token (JWT). Whenever you run [`step ca init`](../step-cli/reference/ca/init), the [`step`](https://github.com/smallstep/cli) CLI tool creates a JWK provisioner. -#### Examples: - -#### Add a JWK provisioner: +#### Create a JWK provisioner: ```shell step ca provisioner add you@smallstep.com --create @@ -372,7 +370,7 @@ In the ca.json configuration file, a complete JWK provisioner example looks like } ``` -Here's what property stands for: +Here's what each property stands for: - **type**: is a case insensitive field that defines the provisioner type. For a JWK provisioner it must be `JWK`. @@ -427,7 +425,7 @@ Please enter the password to decrypt the content encryption key: 1. Retrieve the current encrypted key. - Run the command below, changing the provisioner name `you@smallstep.com` to match your configuration: + Run the command below, changing the provisioner name `you@smallstep.com` to match your configuration: ```shell OLD_ENCRYPTED_KEY=$(step ca provisioner list \ @@ -436,7 +434,7 @@ Please enter the password to decrypt the content encryption key: 2. Update the encrypted key password. - Run: + Run: ```shell ENCRYPTED_KEY=$(echo $OLD_ENCRYPTED_KEY | \ @@ -449,7 +447,7 @@ Please enter the password to decrypt the content encryption key: 3. Update the provisioner. - Run the command below, changing the provisioner name to match your configuration: + Run the command below, changing the provisioner name `you@smallstep.com` to match your configuration: ```shell step ca provisioner update you@smallstep.com \ @@ -486,7 +484,7 @@ Please enter the password to decrypt the content encryption key: The encrypted private key stored in the JWK provisioner configuration and published to the public `/provisioners` endpoint is provided for client convenience. -It is not required for `step-ca` to operate. +However,`step-ca` does not require it to operate, so it can be removed. To remove this key: @@ -513,7 +511,8 @@ For this, `step-ca` supports single sign-on (SSO) integration with identity prov such as Google, Okta, Azure Active Directory, Keycloak, or any other provider that supports the OpenID Connect (OIDC) extension of OAuth 2.0. -OIDC adds an identity layer to OAuth 2.0, enabling providers to issue identity tokens, known as "ID tokens," to OAuth clients. +OIDC adds an identity layer to OAuth 2.0, +enabling providers to issue identity tokens, known as "ID tokens," to OAuth clients. These tokens are JSON Web Tokens (JWTs) that contain user identity information, such as full name, username, and email address. Like certificates, OIDC tokens have a validity period, @@ -549,7 +548,9 @@ The value of the token's _email_ claim is also included as an email _Subject Alt _Fig. 3: Diagram of how step works with individuals using a single sign-on provisioner_ -From the user's perspective, when requesting a certificate, `step` detects the OIDC provisioner and initiates the OAuth login flow automatically: +From the user's perspective, when requesting a certificate, +`step` detects the OIDC provisioner, +and initiates the OAuth login flow automatically:
- By default, the `X5C` provisioner will issue a certificates for any Subject names. - If you want to limit or modify the subject names this provisioner will issue, + By default, the `X5C` provisioner will issue certificates for any Subject names. + If you wish to restrict or modify the subject names that this provisioner can issue, you can use a certificate template. For example, say your users will use the X5C provisioner to exchange an X.509 client certificate for an SSH user certificate. @@ -823,9 +828,11 @@ with the `name` or any of the `ips` appearing on the Nebula client certificate. To be clear, Nebula certificates can contain a single `name` and a list of `ips`. The `name` field is often a DNS hostname, but it could be an email, IP, or URI. And `ips` contains a list of CIDR blocks. + In `step-ca`, the Nebula provisioner will authorize certificate subjects or SANs that include the `name`, plus IPs in any of the CIDR blocks in `ips` on the Nebula certificate. +#### Create a Nebula Provisioner To create a Nebula provisioner, run: ```shell @@ -847,7 +854,7 @@ step ca certificate host3.example.com host3.crt host3.key \ ### SSHPOP - SSH Certificate An SSHPOP provisioner allows a client to renew, revoke, or rekey an SSH -certificate using that certificate for authentication with the CA. +certificate using same SSH certificate for authentication with the CA. However, the renew and rekey operations are limited to SSH host certificates only. An SSHPOP provisioner is configured with the user and host root ssh certificates @@ -860,16 +867,15 @@ header that contains the SSH certificate. When configured with the `--ssh` option (i.e, `step ca init --ssh`), the CA will contain a default SSHPOP provisioner named `sshpop`. -#### Example: Add an SSHPOP provisioner: +#### Create an SSHPOP provisioner: To create an SSHPOP provisioner, run: - ```shell step ca provisioner add sshpop --type SSHPOP ``` -An example SSHPOP provisioner in `ca.json`: +Here's an example SSHPOP provisioner in `ca.json`: ```json ... @@ -886,6 +892,7 @@ An example SSHPOP provisioner in `ca.json`: } } ``` +And, here's what each property stands for: * **type**: indicates the provisioner type and must be `SSHPOP`. @@ -917,7 +924,7 @@ and client certificates via the `device-attest-01` challenge type. The ACME provisioner in `step-ca` supports issuing X.509 certificates using IP, hostname, and device identifiers. -#### Example: Add an ACME provisioner +#### Create an ACME provisioner To add an ACME provisioner: @@ -959,6 +966,8 @@ An example of an ACME provisioner in the `ca.json`: } ``` +And, here's what each property stands for: + * **type**: indicates the provisioner type and must be `ACME`. * **name**: a string used to identify the provider when the CLI is @@ -1084,7 +1093,9 @@ and clients are authenticated to the CA using a shared secret. #### Requirements -Your CA must use an RSA intermediate CA, even if your client supports ECDSA. +To create a SCEP provisioner on your CA, +your CA must use an RSA intermediate CA, +even if your client supports ECDSA. The RSA intermediate is used to decrypt the contents of the SCEP `pkcsPKIEnvelope` containing the certificate request. This operation cannot be performed using an ECDSA key. @@ -1126,15 +1137,19 @@ Here's an example of a SCEP provisioner in `$(step path)/config/ca.json`: } ``` -- The `forceCN` parameter is optional. -It behaves the same as `forceCN` in the ACME provisioner, and it defaults to false. -- `challenge` is the secret shared between the provisioner and SCEP clients. By default no secret is used. -- The `minimumPublicKeyLength` parameter can be used to set the minimum length of public keys submitted by a client. Defaults to 2048. -- When `includeRoot` is set to true, the root CA certificate will be returned in responses to `GetCACert` requests in addition to the intermediate CA certificate. This option was added to support a specific use case for the macOS SCEP client (see [certificates#746](https://github.com/smallstep/certificates/issues/746) for more details). Defaults to false. -- The `encryptionAlgorithmIdentifier` parameter can be used to change the [encryption algorithm](https://github.com/smallstep/pkcs7/blob/33d05740a3526e382af6395d3513e73d4e66d1cb/encrypt.go#L63) used for encrypting the request content. Defaults to 0: `DES-CBC` for legacy compatibility. +And, here's what each property stands for: -If you don't want to rely on a single, static secret, you can [configure a `SCEPCHALLENGE` webhook](./webhooks.mdx#x509-request-body) instead. -When a SCEP client requests a certificate, the webhook server will receive a request with the `scepChallenge` and `scepTransactionID` properties from the SCEP request. +- **`forceCN`**: parameter is optional. +It behaves the same as `forceCN` in the ACME provisioner, and it defaults to false. +- **`challenge`**: is the secret shared between the provisioner and SCEP clients. By default no secret is used. +- **`minimumPublicKeyLength`**: parameter can be used to set the minimum length of public keys submitted by a client. Defaults to 2048. +- **`includeRoot`**: is set to true, the root CA certificate will be returned in responses to `GetCACert` requests in addition to the intermediate CA certificate. This option was added to support a specific use case for the macOS SCEP client (see [certificates#746](https://github.com/smallstep/certificates/issues/746) for more details). Defaults to false. +- **`encryptionAlgorithmIdentifier`**: parameter can be used to change the [encryption algorithm](https://github.com/smallstep/pkcs7/blob/33d05740a3526e382af6395d3513e73d4e66d1cb/encrypt.go#L63) used for encrypting the request content. Defaults to 0: `DES-CBC` for legacy compatibility. + +If you don't want to rely on a single, static secret, +you can [configure a `SCEPCHALLENGE` webhook](./webhooks.mdx#x509-request-body) instead. +When a SCEP client requests a certificate, +the webhook server will receive a request with the `scepChallenge` and `scepTransactionID` properties from the SCEP request. The webhook server can then decide if the request is allowed or not. #### Enable the HTTP Server @@ -1164,27 +1179,28 @@ A K8sSA provisioner allows a client to request a certificate from the server using a Kubernetes Service Account Token. As of the time when this provisioner was coded, the Kubernetes Service Account -API for retrieving the token from a running instance was still in beta. Therefore, +API for retrieving a token from a running instance was still in beta. Therefore, our K8sSA provisioner must be configured with the public key that will be used to validate K8sSA tokens. -K8sSA tokens are very minimal. There is no place for SANs, or other details that -a user may want validated in a CSR. It is essentially a bearer token. Therefore, -at this time a K8sSA token can be used to sign a CSR with any SANs. Said -differently, the **K8sSA provisioner does little to no validation on the CSR +K8sSA (Kubernetes Service Account) tokens can only hold very minimal information, +and do not provide a place to specify SANs or other details +that users may want validated in a Certificate Signing Request (CSR). +This means that a K8sSA token can be used to sign a CSR with any SANs, +as the **K8sSA provisioner does little to no validation on the CSR before signing it**. You should only configure and use this provisioner if you know what you are doing. If a malicious user obtains the private key they will -be able to create certificates with any SANs and Subject. +be able to create certificates with any SANs or Subject. -#### Example +#### Create a K8sSA provisioner -Add a K8sSA provsioner: +To add a K8sSA provsioner, run: ```shell step ca provisioner add my-kube-provisioner --type K8sSA --pem-keys key.pub ``` -An example of a K8sSA provisioner in the `ca.json`: +Here's an example of a K8sSA provisioner in the `ca.json`: ```json ... @@ -1203,6 +1219,7 @@ An example of a K8sSA provisioner in the `ca.json`: } } ``` +And, here's what each property stands for: * **type**: indicates the provisioner type and must be `K8sSA`. @@ -1221,8 +1238,10 @@ see the [claims](configuration.mdx#claims) section for all the options. ## Cloud Provisioners -`step-ca` can be configured to use instance identity documents (IIDs) to authorize certificate signing requests from cloud VMs running on AWS, GCP, or Azure. -IIDs are signed JSON tokens, created when the instance is launched, and made available via the instance metadata API. +`step-ca` can be configured to use instance identity documents (IIDs) +to authorize certificate signing requests from cloud VMs running on AWS, GCP, or Azure. +IIDs are signed JSON tokens, created when the instance is launched, +and made available via the instance metadata API. Here's the contents of an example IID from AWS: @@ -1308,7 +1327,7 @@ The [`step`](https://github.com/smallstep/cli) CLI will generate a custom JWT token containing the instance identity document and its signature and the CA will grant a certificate after validating it. -#### Example +#### Create an AWS Provisioner Find your AWS [account ID](https://docs.aws.amazon.com/general/latest/gr/acct-identifiers.html) to restrict access to our VMs: @@ -1342,6 +1361,8 @@ In the `ca.json`, an AWS provisioner looks like: } ``` +And, here's what each property stands for: + - **type**: indicates the provisioner type and must be `AWS`. - **name**: a string used to identify the provider when the CLI is @@ -1375,7 +1396,7 @@ The GCP provisioner grants certificates to Google Compute Engine instance using its [identity](https://cloud.google.com/compute/docs/instances/verifying-instance-identity) token. The CA will validate the JWT and grant a certificate. -#### Example +#### Create a GCP Provisioner On the host running `step-ca`, add an GCP provisioner to your configuration by running: @@ -1409,6 +1430,8 @@ In the `ca.json`, a GCP provisioner looks like: } ``` +And, here's what each property stands for: + - **type**: indicates the provisioner type and must be `GCP`. - **name**: a string used to identify the provider when the CLI is used. @@ -1446,7 +1469,7 @@ The Azure provisioner grants certificates to Microsoft Azure instances using the [managed identities tokens](https://docs.microsoft.com/en-us/azure/active-directory/managed-identities-azure-resources/how-to-use-vm-token). The CA will validate the JWT and grant a certificate. -#### Example +#### Create an Azure Provisioner On the host running `step-ca`, add an Azure provisioner to your configuration by running: @@ -1479,6 +1502,8 @@ In the `ca.json`, an Azure provisioner looks like: } ``` +And, here's what each property stands for: + - **type**: indicates the provisioner type and must be `Azure`. - **name**: a string used to identify the provider when the CLI is used. From efd82d9ac31a313db312b4fcc77f48f77051a79c Mon Sep 17 00:00:00 2001 From: Linda Ikechukwu <32891838+Linda-Ikechukwu@users.noreply.github.com> Date: Thu, 25 May 2023 13:50:33 +0100 Subject: [PATCH 3/7] Update step-ca/provisioners.mdx Co-authored-by: Carl Tashian --- step-ca/provisioners.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/step-ca/provisioners.mdx b/step-ca/provisioners.mdx index 3e948643..426ac853 100644 --- a/step-ca/provisioners.mdx +++ b/step-ca/provisioners.mdx @@ -75,7 +75,7 @@ and can be configured in the OIDC provisione To illustrate how to interpret this table, let's take the `JWK` and `SSHPOP` provisioner. A `JWK` provisioner _can_ sign, renew, and revoke X.509 certificates, as well as sign user and host SSH certificates. -However, it _cannot_ renew or rekey SSH certificates. +However, it _cannot_ renew SSH user certificates. On the other hand, an `SSHPOP` provisioner _can_ revoke and rekey SSH certificates and renew SSH host certificates. From 2736735530d37620a26ad15148483ae35c372e5f Mon Sep 17 00:00:00 2001 From: Linda Ikechukwu <32891838+Linda-Ikechukwu@users.noreply.github.com> Date: Thu, 25 May 2023 15:21:46 +0100 Subject: [PATCH 4/7] Update step-ca/provisioners.mdx Co-authored-by: Carl Tashian --- step-ca/provisioners.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/step-ca/provisioners.mdx b/step-ca/provisioners.mdx index 426ac853..dccb96eb 100644 --- a/step-ca/provisioners.mdx +++ b/step-ca/provisioners.mdx @@ -260,7 +260,7 @@ An administrator is just a subject name and a provisioner name. You can authenticate as an administrator via the authentication scheme of the provisioner. For example, for the default JWK provisioner, running administrative commands in `step` will prompt for the provisioner password. -***Tip: Single Sign-On (SS0) can be used for Admin users.*** +***Tip: Single Sign-On (SSO) can be used for Admin users.*** To enable CA administration via SSO, follow these steps: 1. Add an [OIDC provisioner](#oauthoidc-single-sign-on) linked to your identity provider. From 0b05934318db8758650f6e40d3299d2eb154f2b8 Mon Sep 17 00:00:00 2001 From: Linda Ikechukwu <32891838+Linda-Ikechukwu@users.noreply.github.com> Date: Thu, 25 May 2023 15:22:05 +0100 Subject: [PATCH 5/7] Update step-ca/provisioners.mdx Co-authored-by: Carl Tashian --- step-ca/provisioners.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/step-ca/provisioners.mdx b/step-ca/provisioners.mdx index dccb96eb..640fcf3e 100644 --- a/step-ca/provisioners.mdx +++ b/step-ca/provisioners.mdx @@ -1085,8 +1085,8 @@ To get a client certificate for a hardware-bound private key on your YubiKey: The SCEP provisioner can sign and renew certificates using the Simple Certificate Enrollment Protocol SCEP protocol (SCEP) ([RFC8894](https://datatracker.ietf.org/doc/html/rfc8894)). -SCEP is popularly used for certificate management, -particularly in network equipment and mobile device management (MDM). +SCEP is commonly used for certificate management +in network equipment and mobile device management (MDM). It runs over HTTP and uses POSTed binary data or base64-encoded GET parameters, with CMS (PKCS#7) and CSR (PKCS#10) data formats, and clients are authenticated to the CA using a shared secret. From 717283928f78b2f4c993cddb2732659104abbb1b Mon Sep 17 00:00:00 2001 From: Linda Ikechukwu <32891838+Linda-Ikechukwu@users.noreply.github.com> Date: Thu, 25 May 2023 15:55:39 +0100 Subject: [PATCH 6/7] Update provisioners.mdx --- step-ca/provisioners.mdx | 52 ++++++++++++++++++++++------------------ 1 file changed, 29 insertions(+), 23 deletions(-) diff --git a/step-ca/provisioners.mdx b/step-ca/provisioners.mdx index 426ac853..af1994ef 100644 --- a/step-ca/provisioners.mdx +++ b/step-ca/provisioners.mdx @@ -86,37 +86,41 @@ It's important to understand the capabilities and limitations when selecting a provisioner for a given workload. ## Provisioner Management +By default, provisioner configurations reside in the `$(step path)/config/ca.json` file. +However, if Remote Provisioner Management is enabled, +provisioner configurations are stored in the database instead of `ca.json`, +while the global CA configuration remains in `ca.json`. + +Remote Provisioner Management is ideal if you have multiple CA administrators, +[run several load-balanced](./certificate-authority-server-production.mdx#load-balancing-or-proxying-step-ca-traffic) `step-ca` instances, +or if you want to manage your provisioners remotely (eg. with Infrastructure as Code (IaC) tools; [see below](#unattended-remote-provisioner-management)). +See [Remote Provisioner Management](#remote-provisioner-management) for more info on tradeoofs and benefits. -To add, remove, or modify provisioner configurations, -use the [`step ca provisioner`](../step-cli/reference/ca/provisioner) command group. -You must run these commands directly on your CA machine, +The [`step ca provisioner`](../step-cli/reference/ca/provisioner) command group are used for provisioner management. +They can be used to add, remove, or modify provisioner configurations. +Note, you must run these commands directly on your CA machine, as they need to modify the `$(step path)/config/ca.json` configuration file. +When you run any step ca provisioner command, it will try to detect where the provisioner configuration is stored. +It will either modify the `ca.json` file or it will update the database, +depending on whether you have enabled Remote Provisioner Management. +

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.

+

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. +

-Within `ca.json` you can define an optional claims property for each provisioner. +Within `ca.json` you can define an optional `claims` property for each provisioner. The settings defined in the `claims` property of individual provisioners under an authority override the global defaults set for that authority. For a list of global options, see the `claims` object under the authority configuration block in the [configuration guide](./configuration/#example-configuration). -If you -have multiple CA administrators, -[run several load-balanced](./certificate-authority-server-production.mdx#load-balancing-or-proxying-step-ca-traffic) `step-ca` instances, -or if you want to manage your provisioners remotely (eg. with Infrastructure as Code (IaC) tools; [see below](#unattended-remote-provisioner-management)), you can enable the remote provisioner management API, which is disabled by default. - -With remote provisioner management enabled, -provisioner configurations are stored in the database instead of `ca.json`, -while the global CA configuration remains in `ca.json`. - -See [Remote Provisioner Management](#remote-provisioner-management) for more. - ### Common Provisioner Operations Common provisioner operations include: @@ -171,7 +175,7 @@ The example above modifies the minumum, maximum, and default durations for X.509 However, the `update` command can be used to modify the lifetimes, extensions, and templates of both X.509 and SSH certificates. Additionally, there are some provisioner-specific options, -which are covered by the documentation for each provisioner type [below](./provisioners/#provisioner-types). +which are covered by the [documentation for each provisioner type](./provisioners/#provisioner-types). ## Remote Provisioner Management @@ -181,7 +185,7 @@ When remote provisioner management is enabled, your provisioner configuration is stored in the database instead of in ca.json. You can manage the provisioner configuration by running [`step ca provisioner`](../step-cli/reference/ca/provisioner) commands, either locally or remotely. -However, you must sign in as an Admin user. +However, ***you must sign in as an Admin user***. ### Enable Remote Provisioner Management @@ -213,7 +217,8 @@ To enable remote provisioner management on an existing CA and migrate your `ca.j When `step-ca` starts up, it will: * Migrate the provisioners from your `ca.json` to the database - * Repurpose the first JWK provisioner in your `ca.json` as an administrative provisioner. If no JWK provisioner exists, it will add a [JWK](#jwk) provisioner called Admin JWK to the database. You will be prompted for a password that will encrypt the new provisioner key. + * Repurpose the first JWK provisioner in your `ca.json` as an administrative provisioner. +If no JWK provisioner exists, it will add a [JWK](#jwk) provisioner called Admin JWK to the database. You will be prompted for a password that will encrypt the new provisioner key. * Create an initial Super Admin user, with username `step`, and link it to the administrative provisioner. 4. Remove old provisioner configurations from `ca.json`. @@ -228,9 +233,10 @@ To enable remote provisioner management on an existing CA and migrate your `ca.j ### Managing Admin Users -With remote provisioner management, -"Admins" can remotely manage provisioners. -"Super Admins" are Admins that can also manage the list of Admins for the CA using [`step ca admin`](../step-cli/reference/ca/admin). +With remote provisioner management, there are two categories of admin users: "Admins" and "Super Admins". + +"Admins" can remotely manage provisioners. +Then, "Super Admins" are Admins that can also manage the list of Admins for the CA using [`step ca admin`](../step-cli/reference/ca/admin). #### Create An Admin User From 720fbafed3e4bc6648a9d67b035362bacea37057 Mon Sep 17 00:00:00 2001 From: Linda Ikechukwu <32891838+Linda-Ikechukwu@users.noreply.github.com> Date: Fri, 26 May 2023 17:49:46 +0100 Subject: [PATCH 7/7] Update provisioners.mdx - Add the link to database page - Add explanation for reason to delete JWK encrypted private key. --- step-ca/provisioners.mdx | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/step-ca/provisioners.mdx b/step-ca/provisioners.mdx index 303c2d12..f514566e 100644 --- a/step-ca/provisioners.mdx +++ b/step-ca/provisioners.mdx @@ -88,7 +88,7 @@ provisioner for a given workload. ## Provisioner Management By default, provisioner configurations reside in the `$(step path)/config/ca.json` file. However, if Remote Provisioner Management is enabled, -provisioner configurations are stored in the database instead of `ca.json`, +provisioner configurations are stored in [the database](./configuration/#databases) instead of `ca.json`, while the global CA configuration remains in `ca.json`. Remote Provisioner Management is ideal if you have multiple CA administrators, @@ -488,9 +488,11 @@ Please enter the password to decrypt the content encryption key: #### Removing the encrypted private key from a JWK provisioner -The encrypted private key stored in the JWK provisioner configuration -and published to the public `/provisioners` endpoint is provided for client convenience. -However,`step-ca` does not require it to operate, so it can be removed. +The `/provisioners` endpoint is not a protected resource, +so anyone with access to the URL can view the list of all provisioners as well as the encrypted private key of any JWK provisioner. + +While the exposed encrypted key poses no real danger, you can remove it if you're concerned. +`step-ca` does not require it to function, as it is only provided for the client's convenience. To remove this key: