first build

docs/adcs.md

@@ -0,0 +1,68 @@
+# AD CS Web Enrollment and certificate template
+
+The portal submits CSRs to **Active Directory Certificate Services Web Enrollment** (`certsrv`), not NDES, not `certreq`, and not `ICertRequest` COM.
+
+## Web Enrollment
+
+On the CA (or a dedicated enrollment host):
+
+1. Install the **Certification Authority Web Enrollment** role service.
+2. Require HTTPS on the `certsrv` application.
+3. Allow the portal service account to authenticate (Windows Integrated / NTLM). Basic auth is not used.
+4. From the Linux host, `curl -I https://ca.example.com/certsrv/` should not fail TLS. A 401 is expected without NTLM.
+
+The portal:
+
+- `POST {CERTSRV_URL}/certfnsh.asp` with `Mode=newreq`, the PEM CSR, and `CertAttrib=CertificateTemplate:{CERTSRV_TEMPLATE}`
+- On success, `GET {CERTSRV_URL}/certnew.cer?ReqID={id}&Enc=b64`
+
+If the HTML does not look like “Certificate Issued”, the portal errors out. **Pending** (manager approval) is treated as failure — the template should auto-issue.
+
+## Service account
+
+Use a dedicated domain user (for example `EXAMPLE\cert-portal`):
+
+- **Enroll** on the certificate template
+- **Request Certificates** on the CA (often already granted to Authenticated Users)
+- Allowed to use the `certsrv` IIS app
+
+This account is what AD CS records as the requester. That is expected. User identity is in the certificate SAN, not the requester field.
+
+## Template
+
+Create a template (example name `UserWifi` — use the **template common name**, not the display name, in `CERTSRV_TEMPLATE`).
+
+Required so the CSR SAN survives issuance:
+
+- Subject name: **Supply in the request**
+- Do **not** build subject from Active Directory
+- SAN: allow the enrollee to supply SAN (the “enroll subject from request” / `ENROLLEE_SUPPLIES_SUBJECT` style flags)
+
+Typical user-auth / Wi-Fi client settings:
+
+- Category: User (or as your org requires)
+- Extension: Application Policy Client Authentication
+- Key usage: per your NPS/EAP-TLS needs (Windows templates often want Digital Signature and/or Key Encipherment)
+- Validity: as policy allows
+- No manager approval (or the portal will raise `CertsrvPendingError`)
+- Publish to AD: optional; not required for Apple clients
+
+Compatibility: Windows Server 2016+ for URI SAN strong mapping as described below.
+
+## Strong mapping (SID URI)
+
+The CSR includes:
+
+```
+URI:tag:microsoft.com,2022-09-14:sid:S-1-5-21-…
+```
+
+and UPN otherName `1.3.6.1.4.1.311.20.2.3`.
+
+That URI is the form Microsoft documents for mapping certificates to AD objects when the CA did not stamp `szOID_NTDS_CA_SECURITY_EXT` itself (offline / “supply in request” workflows). Confirm with `certutil -dump` on a test cert that both SAN values are present.
+
+If the issued cert is missing the URI, the template is still overwriting subject/SAN from Active Directory — fix the template before issuing to phones.
+
+## Testing without the portal
+
+From a domain-joined Windows box you can still use `certreq` to prove the template. The portal’s path is only `certsrv`. If `certreq` works but the portal fails, check NTLM, HTTPS, Enroll ACL, and the HTML parser (pending vs issued).