CCM-12075 - Added JWT Bearer token script, instructions and fix for r… (#248)

* CCM-12075 - Added JWT Bearer token script, instructions and fix for ref environment

* Update container and git ignore

Author: nhsd-david-wass

.gitignore

@@ -27,3 +27,4 @@ dist
 /sandbox/*.log
 /sandbox-staging
 /specification/api/components/examples
+/scripts/JWT/*.pem

scripts/JWT/README.md

@@ -0,0 +1,43 @@
+# Environments – Notify Supplier
+
+## Environment Matrix
+
+| Environment Name | Apigee Instance | Proxy URL | Application | Security Level | Private Key | KID | Notes / Env Code |
+|------------------|-----------------|-----------|--------------|----------------|--------------|------|------------------|
+| **Internal dev – PRs** | Internal | internal-dev.api.service.nhs.uk/nhs-notify-supplier-PR-XXX | Notify-Supplier-App-Restricted – Internal Dev 2 | level 0 | — | — | internal-dev PRs |
+| **Internal dev – Main** | Internal | internal-dev.api.service.nhs.uk/nhs-notify-supplier | Notify Supplier – Application Restricted – Internal Dev Main | level 3 | [internal-dev-test-1.pem](https://eu-west-2.console.aws.amazon.com/systems-manager/parameters/%252Fnhs%252Fjwt%252Fkeys%252Finternal-dev-test-1.pem/description?region=eu-west-2&tab=Table) | internal-dev-test-1 | dev |
+| **Ref** | Internal | ref.api.service.nhs.uk/nhs-notify-supplier | Notify Supplier – Application Restricted – Ref | level 3 | [ref-test-1.pem](https://eu-west-2.console.aws.amazon.com/systems-manager/parameters/%252Fnhs%252Fjwt%252Fkeys%252Fref-test-1.pem/description?region=eu-west-2&tab=Table) | ref-test-1 | prod |
+| **Int** | External | int.api.service.nhs.uk/nhs-notify-supplier | Notify Supplier – Integration Testing | level 3 | [int-test-1.pem](https://eu-west-2.console.aws.amazon.com/systems-manager/parameters/%252Fnhs%252Fint%252Fjwt%252Fint-test-1.pem/description?region=eu-west-2&tab=Table) | int-test-1 | int |
+
+---
+
+## How to Get the JWT Access Token
+
+1. Download the private key from AWS Systems Manager and save it locally as `$KID.pem`, for example `ref-test-1.pem`.
+
+2. Get the Apigee API key via one of the following:
+   - [Apigee Edge Console](https://apigee.com/edge)
+   - [Internal developer account](https://onboarding.prod.api.platform.nhs.uk/Index)
+   - [External developer account](https://dos-internal.ptl.api.platform.nhs.uk/Index)
+
+3. Run the Python script `get_bearer_token.py` with the parameters:
+
+   ```bash
+   python get_bearer_token.py --kid <KID> --env <ENVIRONMENT> --appid <APIKEY>
+   ```
+
+   Example:
+
+   ```bash
+   python get_bearer_token.py --kid ref-test-1 --env ref --appid 8Np3gFEw21JX7AGuokId0QEFTaOhG4Z2
+   ```
+
+4. The access token will be returned in the response
+
+5. Add the access token to your API requests as a header:
+
+   | Header Name | Header Value |
+   |--------------|--------------|
+   | Authorization | `Bearer <access token>` |
+
+---

scripts/JWT/get_bearer_token.py

@@ -0,0 +1,66 @@
+import uuid
+import argparse
+from time import time
+import requests
+import jwt  # https://github.com/jpadilla/pyjwt
+
+ENV_TOKEN_URLS = {
+    "int":  "https://int.api.service.nhs.uk/oauth2/token",
+    "internal-dev":  "https://internal-dev.api.service.nhs.uk/oauth2-mock/token",
+    "prod": "https://api.service.nhs.uk/oauth2/token",
+    "ref": "https://ref.api.service.nhs.uk/oauth2/token",
+}
+
+def main():
+    ap = argparse.ArgumentParser(description="Fetch NHS access token using a signed client assertion (JWT).")
+    ap.add_argument("--kid", required=True,
+                    help="Base name used for both the private key file (<id>.pem) and the JWT header kid.")
+    ap.add_argument("--env", choices=ENV_TOKEN_URLS.keys(), required=True,
+                    help="Environment to hit: int, internal-dev, or prod.")
+    ap.add_argument("--appid", help="Apigee Application ID (used for both sub and iss).")
+    args = ap.parse_args()
+
+    kid = args.kid
+    private_key_file = f"{kid}.pem"
+    token_url = ENV_TOKEN_URLS[args.env]
+
+    with open(private_key_file, "r") as f:
+        private_key = f.read()
+
+    claims = {
+        "sub": args.appid,
+        "iss": args.appid,
+        "jti": str(uuid.uuid4()),
+        "aud": token_url,
+        "exp": int(time()) + 300, # 5mins in the future
+    }
+
+    additional_headers = {"kid": kid}
+
+    signed_jwt = jwt.encode(
+        claims, private_key, algorithm="RS512", headers=additional_headers
+    )
+# ----- 2) Exchange JWT for an access token -----
+    form = {
+        "grant_type": "client_credentials",
+        "client_assertion_type": "urn:ietf:params:oauth:client-assertion-type:jwt-bearer",
+        "client_assertion": signed_jwt,
+    }
+
+    resp = requests.post(
+        token_url,
+        headers={"content-type": "application/x-www-form-urlencoded"},
+        data=form,
+        timeout=30,
+    )
+
+    # Raise for non-2xx responses, then print the token payload
+    resp.raise_for_status()
+    token_payload = resp.json()
+
+    print("access_token:", token_payload.get("access_token"))
+    print("expires_in:", token_payload.get("expires_in"))
+    print("token_type:", token_payload.get("token_type"))
+
+if __name__ == "__main__":
+    main()

scripts/config/vale/styles/config/vocabularies/words/accept.txt

@@ -1,18 +1,18 @@
-API
+API|api
 [A-Z]+s
 Bitwarden
 bot
 Cognito
 Cyber
+[Dd]ev
 Dependabot
-Dev
 devcontainer
 draw.io
 drawio
+[Ee]nv
 endcapture
 endfor
 endraw
-env
 Git[Hh]ub
 Gitleaks
 Grype

scripts/devcontainer/postcreatecommand.sh

@@ -8,6 +8,8 @@ source ~/.zshrc
 make _install-dependencies # required before config to ensure python is available due to race between config:: make targets
 make config
 
+pip install --user requests pyjwt cryptography
+
 sudo gem install jekyll bundler
 jekyll --version && cd docs && bundle install
 

specification/api/components/x-nhsd-apim/target-ref.yml

@@ -1,6 +1,6 @@
 type: external
 healthcheck: /_status
-url: https://suppliers.ref.nhsnotify.national.nhs.uk
+url: https://main.suppliers.nonprod.nhsnotify.national.nhs.uk
 security:
   type: mtls
-  secret: nhs-notify-supplier-mtls-ref
+  secret: notify-supplier-mtls-ref