PKI SCEP documentation updates #30753

stevendpclark · 2025-05-26T19:29:51Z

Description

This adds the relevant updates for the PKI SCEP feature. Adding documentation around the new SCEP auth plugin along with the new protocol paths and configuration API within the PKI mount.

VAULT-27802

TODO only if you're a HashiCorp employee

Backport Labels: If this fix needs to be backported, use the appropriate backport/ label that matches the desired release branch. Note that in the CE repo, the latest release branch will look like backport/x.x.x, but older release branches will be backport/ent/x.x.x+ent.
- LTS: If this fixes a critical security vulnerability or severity 1 bug, it will also need to be backported to the current LTS versions of Vault. To ensure this, use all available enterprise labels.
ENT Breakage: If this PR either 1) removes a public function OR 2) changes the signature
of a public function, even if that change is in a CE file, double check that
applying the patch for this PR to the ENT repo and running tests doesn't
break any tests. Sometimes ENT only tests rely on public functions in CE
files.
Jira: If this change has an associated Jira, it's referenced either
in the PR description, commit message, or branch name.
RFC: If this change has an associated RFC, please link it in the description.
ENT PR: If this change has an associated ENT PR, please link it in the
description. Also, make sure the changelog is in this PR, not in your ENT PR.

github-actions · 2025-05-26T19:30:44Z

CI Results:
All Go tests succeeded! ✅

github-actions · 2025-05-26T19:31:07Z

Build Results:
All builds succeeded! ✅

victorr

Nice work!

Reviewing with request changes as the nested bullet points need fixing.

Also left many suggestions, please discard any of them that you don't agree with.

website/content/api-docs/secret/pki/issuance.mdx

website/content/docs/auth/scep.mdx

website/content/api-docs/auth/scep.mdx

website/content/docs/secrets/pki/scep.mdx

victorr

Awesomesauce.

kitography · 2025-05-27T17:10:19Z

website/content/api-docs/auth/scep.mdx

+
+## Login
+
+This endpoint is used to authenticate against the SCEP auth method, but shouldn't be used directly,


Double but sentance construction here is a little confusing, maybe:

"This endpoint is used to authenticate against the SCEP auth method. It shouldn't be used directly, rather through delegated authentication from a PKI mount."

victorr

👍

website/content/docs/secrets/pki/scep.mdx

Co-authored-by: Yoko Hyakuna <[email protected]>

stevendpclark · 2025-06-03T19:29:19Z

@yhyakuna thanks for the suggestions/review, all your suggestions have been applied.

website/content/api-docs/auth/scep.mdx

schavis · 2025-06-05T23:34:20Z

website/content/docs/secrets/pki/scep.mdx

+The following is an example of a complete SCEP configuration using Intune authentication. Note that the
+SCEP auth mount must have a role configured with an auth_type of `intune`. For the Intune authentication
+credentials within the PKI mount's SCEP configuration, the tenant ID, client ID, and client secret can be
+provided as environment variables, leverage Azure managed identities, or hardcoded into the configuration.
+Note that all the `intune` specific fields within the `external_validation` block also accept using
+[indirect value references](/vault/docs/configuration/seal#indirect-value-references)


Suggested change

The following is an example of a complete SCEP configuration using Intune authentication. Note that the

SCEP auth mount must have a role configured with an auth_type of `intune`. For the Intune authentication

credentials within the PKI mount's SCEP configuration, the tenant ID, client ID, and client secret can be

provided as environment variables, leverage Azure managed identities, or hardcoded into the configuration.

Note that all the `intune` specific fields within the `external_validation` block also accept using

[indirect value references](/vault/docs/configuration/seal#indirect-value-references)

The following example uses SCEP with Intune authentication. Note that the

SCEP auth mount must have a role configured with `auth_type` set to `intune`.

You can choose to set your Intune authentication credentials explicilty in the

configuraiton, as environment variables, or leverage Azure managed identities.

All the `intune` specific fields within the `external_validation` block also

accept [indirect value references](/vault/docs/configuration/seal#indirect-value-references).

Style correction: write in active voice

website/content/docs/secrets/pki/scep.mdx

schavis · 2025-06-05T23:40:26Z

website/content/docs/secrets/pki/scep.mdx

+### Matching different static challenge values
+
+It is possible for a PKI mount to use different static challenge values. The SCEP auth
+mount will need multiple roles configured of `auth_type` `static-challenge`, each with a different `challenge` value.
+Within the PKI mount's SCEP configuration, the `scep_role` field will need to be left blank. With that set up the PKI
+mount login attempt will be tried against the various SCEP auth roles.


Suggested change

### Matching different static challenge values

It is possible for a PKI mount to use different static challenge values. The SCEP auth

mount will need multiple roles configured of `auth_type` `static-challenge`, each with a different `challenge` value.

Within the PKI mount's SCEP configuration, the `scep_role` field will need to be left blank. With that set up the PKI

mount login attempt will be tried against the various SCEP auth roles.

Folded into the static challenge above

schavis · 2025-06-05T23:41:15Z

website/content/docs/secrets/pki/scep.mdx

+### Intune support
+
+Intune clients add an additional `/pkiclient.exe` path to the configured SCEP request. Make sure that
+the access policies associated with the SCEP role within the SCEP auth mount provide access to this path, such as
+
+```hcl
+path “pki/scep” {
+  capabilities=[“read“, “update”, “create”]
+}
+path “pki/scep/pkiclient.exe” {
+  capabilities=[“read“, “update”, “create”]
+}
+```
+
+During internal testing, we noticed Intune clients would fail to match the CA certificate when the GetCACerts request
+returned a full certificate chain instead of the issuer CA certificate by itself. If you experience this issue, you
+can force the SCEP response to only return the issuer CA certificate by setting the `restrict_ca_chain_to_issuer` field to `true`
+within the PKI mount's SCEP configuration.


Suggested change

### Intune support

Intune clients add an additional `/pkiclient.exe` path to the configured SCEP request. Make sure that

the access policies associated with the SCEP role within the SCEP auth mount provide access to this path, such as

```hcl

path “pki/scep” {

capabilities=[“read“, “update”, “create”]

}

path “pki/scep/pkiclient.exe” {

capabilities=[“read“, “update”, “create”]

}

```

During internal testing, we noticed Intune clients would fail to match the CA certificate when the GetCACerts request

returned a full certificate chain instead of the issuer CA certificate by itself. If you experience this issue, you

can force the SCEP response to only return the issuer CA certificate by setting the `restrict_ca_chain_to_issuer` field to `true`

within the PKI mount's SCEP configuration.

Folded into the Intune tab above

schavis · 2025-06-05T23:47:30Z

website/content/docs/secrets/pki/scep.mdx

+layout: docs
+page_title: Simple Certificate Enrollment Protocol (SCEP)
+description: >-
+   Understand the configuration and limitations of Vault's PKI secrets engine implementation of the Simple Certificate Enrollment Protocol (SCEP).


Suggested change

Understand the configuration and limitations of Vault's PKI secrets engine implementation of the Simple Certificate Enrollment Protocol (SCEP).

Configure the PKI plugin to work with Simple Certificate Enrollment Protocol (SCEP).

schavis · 2025-06-06T00:26:46Z

website/content/docs/secrets/pki/scep.mdx

+## Enabling SCEP support on a Vault PKI mount
+
+The following is a list of steps required to configure an existing PKI
+mount to serve SCEP clients. Each of which can be broken down within three main
+categories.
+
+ 1. [Authentication mechanisms](#configuring-scep-authentication-mounts)
+ 2. [Updating PKI tunable parameters](#updating-the-pki-mount-tunable-parameters)
+ 3. [PKI SCEP configuration](#pki-scep-configuration)


Suggested change

## Enabling SCEP support on a Vault PKI mount

The following is a list of steps required to configure an existing PKI

mount to serve SCEP clients. Each of which can be broken down within three main

categories.

1. [Authentication mechanisms](#configuring-scep-authentication-mounts)

2. [Updating PKI tunable parameters](#updating-the-pki-mount-tunable-parameters)

3. [PKI SCEP configuration](#pki-scep-configuration)

```suggestion

## Before your start

- **You must have Vault 1.20 or later**.

- **You must use the `static-challenge` authentication type to work with JAMF Pro.**

- **To use multiple authentication methods, you must have separate PKI mounts**.

The SCEP implementation only allows one type of challenge authentication for

a given PKI mount. If you require multiple authentication methods, you msut

create separate PKI mounts, that point to either a shared SCEP auth mount or

separate SCEP auth mounts.

I'll accept this suggestion but will tweak it a little bit afterwards, replace your with you and will add Enterprise after Vault

Before you start

You must have Vault Enterprise 1.20 or later.

Co-authored-by: Sarah Chavis <[email protected]>

* most important scep docs * oops. forgot to commit everything. * Add docs around SCEP auth * More SCEP api doc updates * Add return_full_ca_chain parameter to SCEP config docs * Remove duplicated EST sections * Update missing SCEP reference within pki/index.mdx * PR feedback * PR feedback 2 * Rename return_full_ca_chain to restrict_ca_chain_to_issuer * Apply suggestions from code review Co-authored-by: Yoko Hyakuna <[email protected]> * Apply suggestions from code review Co-authored-by: Sarah Chavis <[email protected]> * Tweaks to review suggestions from Sarah * Apply suggestions from code review Co-authored-by: Sarah Chavis <[email protected]> * Fix typo * Fix typo --------- Co-authored-by: Kit Haines <[email protected]> Co-authored-by: Yoko Hyakuna <[email protected]> Co-authored-by: Sarah Chavis <[email protected]>

kitography and others added 6 commits May 21, 2025 08:03

most important scep docs

800439b

oops. forgot to commit everything.

16b2722

Add docs around SCEP auth

854705d

More SCEP api doc updates

310da0c

Add return_full_ca_chain parameter to SCEP config docs

d46983d

Remove duplicated EST sections

7d2ae2b

stevendpclark added this to the 1.20.0-rc milestone May 26, 2025

stevendpclark requested a review from a team May 26, 2025 19:29

stevendpclark self-assigned this May 26, 2025

stevendpclark requested review from a team as code owners May 26, 2025 19:29

stevendpclark requested review from scellef and davidadeleon May 26, 2025 19:29

stevendpclark added the pr/no-changelog label May 26, 2025

github-actions bot added the hashicorp-contributed-pr If the PR is HashiCorp (i.e. not-community) contributed label May 26, 2025

stevendpclark added the docs label May 26, 2025

vercel bot deployed to Preview May 26, 2025 19:33 View deployment

Update missing SCEP reference within pki/index.mdx

291eba8

vercel bot deployed to Preview May 26, 2025 20:32 View deployment

victorr requested changes May 26, 2025

View reviewed changes

PR feedback

332b8fc

vercel bot deployed to Preview May 26, 2025 21:12 View deployment

victorr previously approved these changes May 26, 2025

View reviewed changes

kitography previously approved these changes May 27, 2025

View reviewed changes

PR feedback 2

7c4a493

stevendpclark dismissed stale reviews from kitography and victorr via 7c4a493 May 27, 2025 20:04

vercel bot deployed to Preview May 27, 2025 20:11 View deployment

Rename return_full_ca_chain to restrict_ca_chain_to_issuer

7fc2636

vercel bot deployed to Preview June 2, 2025 19:41 View deployment

victorr previously approved these changes Jun 3, 2025

View reviewed changes

yhyakuna reviewed Jun 3, 2025

View reviewed changes

Apply suggestions from code review

eb73ef8

Co-authored-by: Yoko Hyakuna <[email protected]>

stevendpclark dismissed victorr’s stale review via eb73ef8 June 3, 2025 19:27

vercel bot deployed to Preview June 3, 2025 19:34 View deployment

schavis requested changes Jun 5, 2025

View reviewed changes

schavis requested changes Jun 6, 2025

View reviewed changes

stevendpclark and others added 2 commits June 6, 2025 09:42

Apply suggestions from code review

6471c1c

Co-authored-by: Sarah Chavis <[email protected]>

Tweaks to review suggestions from Sarah

e358061

vercel bot deployed to Preview June 6, 2025 13:49 View deployment

vercel bot deployed to Preview June 6, 2025 13:58 View deployment

stevendpclark and others added 2 commits June 6, 2025 10:01

Apply suggestions from code review

5e36d1f

Co-authored-by: Sarah Chavis <[email protected]>

Fix typo

d324f4c

vercel bot deployed to Preview June 6, 2025 14:13 View deployment

Fix typo

4ceb4df

vercel bot deployed to Preview June 6, 2025 14:31 View deployment

schavis approved these changes Jun 6, 2025

View reviewed changes

Merge branch 'main' into SCEP-DOCS

77b5126

elliesterner approved these changes Jun 6, 2025

View reviewed changes

vercel bot deployed to Preview June 6, 2025 17:09 View deployment

stevendpclark merged commit b91470a into main Jun 6, 2025
34 checks passed

stevendpclark deleted the SCEP-DOCS branch June 6, 2025 17:46

stevendpclark added the backport/1.20.x label Jun 6, 2025

hc-github-team-secure-vault-core mentioned this pull request Jun 6, 2025

Backport of PKI SCEP documentation updates into release/1.20.x #30894

Merged

6 tasks


		## Login

		This endpoint is used to authenticate against the SCEP auth method, but shouldn't be used directly,

	Understand the configuration and limitations of Vault's PKI secrets engine implementation of the Simple Certificate Enrollment Protocol (SCEP).
	Configure the PKI plugin to work with Simple Certificate Enrollment Protocol (SCEP).

-## Enabling SCEP support on a Vault PKI mount
-The following is a list of steps required to configure an existing PKI
-mount to serve SCEP clients. Each of which can be broken down within three main
-categories.
-. [Authentication mechanisms](#configuring-scep-authentication-mounts)
-. [Updating PKI tunable parameters](#updating-the-pki-mount-tunable-parameters)
-. [PKI SCEP configuration](#pki-scep-configuration)
+```suggestion
+## Before your start
+- **You must have Vault 1.20 or later**.
+- **You must use the `static-challenge` authentication type to work with JAMF Pro.**
+- **To use multiple authentication methods, you must have separate PKI mounts**.
+  The SCEP implementation only allows one type of challenge authentication for
+  a given PKI mount. If you require multiple authentication methods, you msut
+  create separate PKI mounts, that point to either a shared SCEP auth mount or
+  separate SCEP auth mounts.

PKI SCEP documentation updates #30753

PKI SCEP documentation updates #30753

Uh oh!

Conversation

stevendpclark commented May 26, 2025

Description

TODO only if you're a HashiCorp employee

Uh oh!

github-actions bot commented May 26, 2025

Uh oh!

github-actions bot commented May 26, 2025

Uh oh!

victorr left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

victorr left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

victorr left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

stevendpclark commented Jun 3, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Before you start

Uh oh!

Uh oh!

Uh oh!