SPT-55 Added DID processing information

chris-dco commented 6 months ago

Why

Currently the developer documentation (here: Prove your user's identity - One Login ) says the following, however we are now adding an endpoint to enable users to download the Public Key directly.

Our support team will give you the public key you must use to validate this JWT.

What

Added the following information to the prove-users-identity.html.md.erb documentation:

That the keys are published in DID document
The URL of both the integration and production DID documents
The significance of the kid and how to parse it to select the correct key from the DID document
The fact that the DID document may contain more than one key and why
What will happen during a rotation, including changes to the DID document
The use of HTTP cache-control headers to avoid constant retrieval of the DID document.
What to do if if errors occur while retrieving the document (i.e. fall back on the cached version)

Technical writer support

Yes

How to review

See original ticket https://govukverify.atlassian.net/browse/SPT-55

Changelog

N/A

Confirm

[x] I have checked if any docs change here also requires updates to other repositories (ADRs / RFCs, README.md, Team Manual, elsewhere in these docs)
[x] Where there is any overlap I have updated or opened a PR for corresponding changes

PippaClarkGDS commented 6 months ago

hi - happy to help with this. LMK when the PR is agreed from a technical POV for me to have a look

chris-dco commented 4 months ago

We have worked with @PippaClarkGDS to update this document into a more useable and better worded form. This document is now ready for review again.

PippaClarkGDS commented 4 months ago

This will need a review from tech writers before going live/after testing

chrisclayson commented 3 months ago

Closing as superseded by #237 .

govuk-one-login / tech-docs