From ab445340de7658c0f24f581a6fc84c95aae4929e Mon Sep 17 00:00:00 2001 From: Elliot Hallam <20362314+ehallam@users.noreply.github.com> Date: Thu, 23 Apr 2026 11:58:59 +0100 Subject: [PATCH 1/3] NPA-6550: added proxygen key rotation docs --- .../Rotating_proxygen_keys.md | 85 +++++++++++++++++++ 1 file changed, 85 insertions(+) create mode 100644 docs/developer-guides/Rotating_proxygen_keys.md diff --git a/docs/developer-guides/Rotating_proxygen_keys.md b/docs/developer-guides/Rotating_proxygen_keys.md new file mode 100644 index 0000000..2470ecc --- /dev/null +++ b/docs/developer-guides/Rotating_proxygen_keys.md @@ -0,0 +1,85 @@ +# Setting up Proxygen + +## Generating a key pair + +You'll need to generate a public and private key pair before raising a service now request to create the proxygen API + +From the [APIM slack message](https://nhsuk.slack.com/archives/C016JRWN6AY/p1773828313442569): +```Follow the new Key ID (KID) structure: + +YYYY-mm-dd-PTL-<> +YYYY-mm-dd-Prod-<> +This enforces a 12-month expiry for all public keys (The date should be expiry date of the Public Key) +``` + +[These docs](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation/application-restricted-restful-apis-signed-jwt-authentication#step-2-generate-a-key-pair) walkthrough how to generate the key pair. + + +## Creating the proxygen deployment + +Once you have this key pair, you can raise a [service now request](https://nhsdigitallive.service-now.com/csm?id=sc_cat_item&sys_id=b5e2c7ee9777a610dd80f2df9153af87&sysparm_category=63f4716697731e90dd80f2df9153affe) with the information you used to create the key pair to "Create an API on Proxygen". + +Once APIM have done this, they will provide you with a client ID in the service now request, e.g. im1-pfs-auth-client which you will need to setup machine access to the API. + +## Setting up machine access + +### Downloading proxygen-cli + +proxygen-cli can be installed using pip + +``` +pip install proxygen-cli +``` + +To verify the installation + +``` +proxygen --version +``` + +This may not work initially - if it can't find proxygen then we need to find the install location and add it to our PATH + +``` +find ~ -name "proxygen" 2>/dev/null +``` + +You're looking for one that looks like `/Users/elliot/Library/Python/3.13/bin/proxygen` + +Once you have this path, you can add it to your .zshrc with `export PATH="$PATH:/Users/elliot/Library/Python/3.13/bin/"` + +Remember to `source ~/.zshrc` + +Rerun the above `proxygen --version` command to verify it's working + +### .proxygen config files + +To fully setup machine access, you will need a credentials.yaml and settings.yaml file inside of ~/.proxygen + +credentials.yaml +``` +base_url: https://identity.{ptl | prod}.api.platform.nhs.uk/realms/api-producers +client_id: {Client ID} +key_id: {Key ID} +private_key_path: {Absolute path to private key} +``` + +settings.yaml +``` +api: {API name} +endpoint_url: https://proxygen.{ptl | prod}.api.platform.nhs.uk +spec_output_format: yaml +``` + +## Pushing up a spec from your local machine + +To verify you've set everything up correctly locally, you can run +``` +proxygen instance deploy {Environment name e.g. internal-dev} {API Name} {path to spec} +``` + +To retrieve the spec you just published, you can run +``` +proxygen instance get {Environment name e.g. internal-dev} {API Name} +``` + +## Deploying the spec via a pipeline From a54eeb7d18b6f1a0ad3131434ab40c735f1ec878 Mon Sep 17 00:00:00 2001 From: Elliot Hallam <20362314+ehallam@users.noreply.github.com> Date: Thu, 23 Apr 2026 12:01:08 +0100 Subject: [PATCH 2/3] NPA-6550: slight docs change --- docs/developer-guides/Rotating_proxygen_keys.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/developer-guides/Rotating_proxygen_keys.md b/docs/developer-guides/Rotating_proxygen_keys.md index 2470ecc..8482303 100644 --- a/docs/developer-guides/Rotating_proxygen_keys.md +++ b/docs/developer-guides/Rotating_proxygen_keys.md @@ -12,8 +12,7 @@ YYYY-mm-dd-Prod-<> This enforces a 12-month expiry for all public keys (The date should be expiry date of the Public Key) ``` -[These docs](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation/application-restricted-restful-apis-signed-jwt-authentication#step-2-generate-a-key-pair) walkthrough how to generate the key pair. - +[These docs](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation/application-restricted-restful-apis-signed-jwt-authentication#step-2-generate-a-key-pair) walkthrough how to generate the key pair. Once you've created your JWKS file called YOUR_KID.json you can move onto creating the proxygen deployment ## Creating the proxygen deployment From c35b1ac2c285631123f540d275c129629ad5373f Mon Sep 17 00:00:00 2001 From: Elliot Hallam <20362314+ehallam@users.noreply.github.com> Date: Thu, 23 Apr 2026 13:07:57 +0100 Subject: [PATCH 3/3] NPA-6550: fix docs --- docs/developer-guides/Rotating_proxygen_keys.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/developer-guides/Rotating_proxygen_keys.md b/docs/developer-guides/Rotating_proxygen_keys.md index 8482303..dd992ec 100644 --- a/docs/developer-guides/Rotating_proxygen_keys.md +++ b/docs/developer-guides/Rotating_proxygen_keys.md @@ -5,7 +5,8 @@ You'll need to generate a public and private key pair before raising a service now request to create the proxygen API From the [APIM slack message](https://nhsuk.slack.com/archives/C016JRWN6AY/p1773828313442569): -```Follow the new Key ID (KID) structure: +``` +Follow the new Key ID (KID) structure: YYYY-mm-dd-PTL-<> YYYY-mm-dd-Prod-<>