Skip to content

Commit 642ad9d

Browse files
committed
docs(QUICKSTART): link reference JSON per step
Each step that creates GET-able state now links to the corresponding sanitised snapshot in docs/reference/. Step 3's CA configuration is HTTP 405 on GET — linked to claims.json (which it does seed) with a note that the configuration itself isn't introspectable. Also adds a "Reference JSON for each step" table at the top, right after the data-model dependency diagram, so a reader knows the reference dir exists before scrolling through the steps.
1 parent 4df0357 commit 642ad9d

1 file changed

Lines changed: 47 additions & 0 deletions

File tree

QUICKSTART.md

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -54,6 +54,19 @@ references them, and the gateway CA config **must** exist before
5454
Command can register it or import templates from it. Hence steps 2 → 3
5555
→ 4 → 5 in that order.
5656

57+
### Reference JSON for each step
58+
59+
Each step that creates GET-able state has a sanitised JSON snapshot in
60+
[`docs/reference/`](docs/reference/) from a known-working lab. Linked
61+
again inline in each step's intro:
62+
63+
| Step | Reference file |
64+
|---|---|
65+
| 2 — gateway profiles | [`docs/reference/gateway/certificate-profiles.json`](docs/reference/gateway/certificate-profiles.json) |
66+
| 3 — gateway CA config | not GET-able (HTTP 405); see [`docs/reference/gateway/claims.json`](docs/reference/gateway/claims.json) for the authz table this step seeds |
67+
| 4 — Command CA | [`docs/reference/command/certificate-authority.json`](docs/reference/command/certificate-authority.json) |
68+
| 5 — Command templates | [`docs/reference/command/templates-certinext.json`](docs/reference/command/templates-certinext.json) |
69+
5770
---
5871

5972
## Prerequisites
@@ -201,6 +214,12 @@ if (-not $CmdToken) { throw "command token mint failed" }
201214

202215
## Step 2 — Create the gateway certificate profile
203216

217+
> **Reference state after this step:** see
218+
> [`docs/reference/gateway/certificate-profiles.json`](docs/reference/gateway/certificate-profiles.json)
219+
> for the final 8-profile shape (one per sandbox product) the gateway
220+
> returns from `GET /AnyGatewayREST/config/certificateprofile` after
221+
> all profiles are in place.
222+
204223
A **certificate profile** on the gateway is a top-level resource: a
205224
named key-algorithm policy that's independent of any CA. CA
206225
configurations (created in step 3) reference these profiles by name
@@ -313,6 +332,17 @@ try {
313332

314333
## Step 3 — Create the gateway CA configuration
315334

335+
> **Reference state after this step:**
336+
> [`docs/reference/gateway/claims.json`](docs/reference/gateway/claims.json)
337+
> shows the gateway authz table — the `akadmin` admin claim is added
338+
> as part of this step on the kfclab path, so authenticated human users
339+
> can hit the gateway UI without being denied.
340+
>
341+
> The CA configuration itself is **not GET-able** (the gateway returns
342+
> HTTP 405 on `GET /config/configuration` — POST/PUT only), so there's
343+
> no live JSON snapshot to compare against. The exact body shape this
344+
> step submits is documented in the script blocks below.
345+
316346
This is the **single biggest configuration step**. It creates the
317347
gateway-side CA record, which has four jobs:
318348

@@ -485,6 +515,14 @@ CertificateProfile) entries from above.
485515

486516
## Step 4 — Register the CA in Command
487517

518+
> **Reference state after this step:** see
519+
> [`docs/reference/command/certificate-authority.json`](docs/reference/command/certificate-authority.json)
520+
> for the full CA record Command returns from
521+
> `GET /KeyfactorAPI/CertificateAuthorities` (filtered to the
522+
> `LogicalName=certinext-caplugin` entry). Useful to compare against
523+
> when debugging — every field the API populates is present, and
524+
> `ClientSecret.SecretValue` is masked by Command on read.
525+
488526
Command needs to know the gateway exists and what auth to use when
489527
talking to it. The CA registration carries the OAuth client used for
490528
Command-to-gateway calls (the same gateway OAuth client from Step 1) and
@@ -583,6 +621,15 @@ curl -sk "${COMMAND_URL}/KeyfactorAPI/CertificateAuthorities" \
583621

584622
## Step 5 — Import templates into Command
585623

624+
> **Reference state after this step:** see
625+
> [`docs/reference/command/templates-certinext.json`](docs/reference/command/templates-certinext.json)
626+
> for the 8 templates Command creates from the 8 ProductIDs registered
627+
> in Step 3 (filtered from `GET /KeyfactorAPI/Templates` by
628+
> `ConfigurationTenant=certinext-caplugin`). Confirms the
629+
> `AnyCA_<ProductID>` naming convention, the `ExtendedKeyUsages` set,
630+
> the `KeyTypes` list synced from the gateway profile's `key_algs`,
631+
> and the per-template `Id` / `Oid` shape.
632+
586633
Command's `/Templates/Import` endpoint asks the registered gateway CA
587634
for its template list and creates corresponding Command-side templates
588635
named `AnyCA_<ProductID>` (e.g. `AnyCA_DV SSL`). One call covers every

0 commit comments

Comments
 (0)