Device IdP troubleshooting guide (PRO-608)

[joshdrake]

For PRO-608: Netflix wants their ops team to identify the next troubleshooting step from our audit log, without opening a support request.

What this adds

A new page, Device IdP Troubleshooting Guide (platform/troubleshooting-device-idp.mdx), in the sidebar under Configure Devices for Smallstep, next to the existing Troubleshooting Guide. The existing guide's "Where to begin?" list now links to it. The page covers:

• Where to begin, organized by what the person sees: the Smallstep failure page with a reference, a browser TLS error, a plain-text error, or a rejection from the identity provider after a successful check.
• How the device check works: the order of the checks, since each one fails for a different reason.
• Finding the event in Audit: the Device IdP category and type filters, what the search box does and doesn't match, and matching the fail page's reference to the event's Request ID.
• What the event contains: Error, Resource ID (the client ID), and each context field.
• One section per reason with its next step, plus tables for identity provider configuration errors and /token errors.
• Failures with no Audit event: TLS handshake failures and unknown client IDs.
• The identity provider rejects a successful check: when user.email doesn't match the sign-in username.
• Failures when a person enrolls the factor.

Everything was checked against deviceidp main (after smallstep/deviceidp#151) and the console's Audit page on web master. The TLS behavior was observed with read-only probes against smallsteplabs.id.smallstep.com: the acceptable-CA list, the unknown ca alert for an untrusted client certificate, and the internal error alert for an unknown team slug. The alert for an expired certificate comes from Go's crypto/tls source. The step certificate verify usage was tested with a leaf + intermediate bundle, and with the leaf alone.

PRO-608 validation items

• Registration (enrollment) failures: covered. Okta's IdP authenticator enrollment uses the same /authorize device check and records the same events. This follows from how the OIDC flow works; I haven't watched an Okta enrollment attempt end to end.
• TLS-handshake failures: not visible in Audit. The guide gives a device-side diagnosis (the openssl s_client acceptable-CA list and the TLS alert names), but Netflix's ops team still can't see these failures in the console. This is the remaining visibility gap for PRO-608.

Product follow-ups this guide works around

1. deviceidp: a TLS handshake failure (an untrusted, expired, or invalid client certificate) records no event. Recording one would mean switching to RequestClientCert and verifying in VerifyPeerCertificate, with the team taken from the server name.
2. moody / Audit search: the search box matches only message and error, not request_id, so the fail page's reference can't be pasted into search. The guide tells people to filter by category and time, then compare the Request ID. The fix is one more OR request_id = $N in service/search_events.go.
3. deviceidp: the agent's device certificates carry urn:smallstep:host:id:<uuid>, which deviceidp doesn't parse. Those certificates resolve only when their common name equals the inventory serial. The guide's "contact support if it's the certificate the agent issued" step is there because of this.

Questions for review

• "hostid must equal the device's host ID": does the console show a device's host ID? If not, readers can't do that comparison.
• The Audit link uses https://smallstep.com/app/?next=/audit, following the docs' existing ?next= pattern. The link checker only confirmed a 200, not where it lands.

Linting

vale --no-wrap reports nothing on the new page, run against the repo's committed .vale styles. markdown-link-check passes for both changed pages, including every in-page anchor.

Heads-up: vale sync overwrites the committed .vale/styles/Google/* files with the upstream package versions. The same uncommitted changes are sitting in the main docs checkout, so a lint run there doesn't use the repo's own rules.

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}