NPA-5244: Composite token and end to end testing (#46)

ellie-bound1-NHSD · web-flow · commit 3e26f39db4d4 · 2025-10-24T09:13:44.000+01:00
# Pull Request ## 🧾 Ticket Link https://nhsd-jira.digital.nhs.uk/browse/NPA-5244 --- ## 📄 Description/Summary of Changes  - Added support for mock composite token - Added happy and unhappy path end to end tests - Enabled end to end tests for PR check workflow and CI/CD internal-qa workflow - Added documentation on manual steps required for enabling mock composite token against ephemeral developments - Added documentation for NHS developer hub - Added documentation for alternative Proxygen installation method - Updated vale acceptance list - Updated uv version --- ## 🧪 Developer Testing Carried Out    - [Successful CI/CD run](https://github.com/NHSDigital/im1-pfs-auth/actions/runs/18531838040) - [Successful PR check run](https://github.com/NHSDigital/im1-pfs-auth/actions/runs/18534306013) --- ## ✅ Developer Checklist  - [x] I have set the PR title to follow the format: `NPA-XXXX: <short-description>` - [x] My branch name follows the convention: `<type>/NPA-XXXX/<short-description>` - [x] My commit messages follow the template: `NPA-XXXX: <short-description>` - [x] I have updated the documentation accordingly - [x] I have set assignees and added appropriate labels --- ## 👀 Reviewer Checklist  - [ ] Changes meet the acceptance criteria of the Jira ticket - [ ] Code is able to be merged (no conflicts and adheres to coding standards) - [ ] Sufficient test evidence is provided (manual and/or automated) --- ## Sensitive Information Declaration To ensure the utmost confidentiality and protect your and others privacy, we kindly ask you to NOT including [PII (Personal Identifiable Information) / PID (Personal Identifiable Data)](https://digital.nhs.uk/data-and-information/keeping-data-safe-and-benefitting-the-public) or any other sensitive data in this PR (Pull Request) and the codebase changes. We will remove any PR that do contain any sensitive information. We really appreciate your cooperation in this matter. - [x] I confirm that neither PII/PID nor sensitive data are included in this PR and the codebase changes.
diff --git a/.github/actions/run-end-to-end-tests/action.yaml b/.github/actions/run-end-to-end-tests/action.yaml
@@ -2,6 +2,9 @@ name: "Run End to End Tests"
 description: Run End to End Tests
 
 inputs:
+  PROXY_NAME:
+    description: "The name of the proxy, e.g. 'im1-pfs-auth'"
+    required: true
   APIGEE_PROXY_NAME:
     description: "The name of the proxy to test, e.g. 'im1-pfs-auth--internal-dev--im1-pfs-auth-pr-31'"
     required: true
diff --git a/.github/workflows/cicd-stage-1-deploy-to-internal-qa.yml b/.github/workflows/cicd-stage-1-deploy-to-internal-qa.yml
@@ -19,7 +19,34 @@ jobs:
       PROXYGEN_KEY_ID: ${{ secrets.PROXYGEN_KEY_ID }}
       PROXYGEN_PRIVATE_KEY: ${{ secrets.PROXYGEN_PRIVATE_KEY }}
 
-  # Add int end-to-end tests
+  run-end-to-end-tests:
+    name: "Run End to End Tests"
+    runs-on: ubuntu-latest
+    needs: deploy-qa-app
+    steps:
+      - name: Checkout Repository
+        uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+      - name: Setup Python Dependencies
+        uses: ./.github/actions/setup-python-dependencies
+      - name: Setup proxygen
+        uses: ./.github/actions/setup-proxygen
+        with:
+          PROXYGEN_CLIENT_ID: ${{ secrets.PROXYGEN_CLIENT_ID }}
+          PROXYGEN_KEY_ID: ${{ secrets.PROXYGEN_KEY_ID }}
+          PROXYGEN_PRIVATE_KEY: ${{ secrets.PROXYGEN_PRIVATE_KEY }}
+      - name: Run End to End Tests
+        uses: ./.github/actions/run-end-to-end-tests
+        env:
+          PROXYGEN_URL_PATH: "im1-pfs-auth"
+          PROXY_NAME: "im1-pfs-auth"
+          APIGEE_PROXY_NAME: "im1-pfs-auth--internal-qa--im1-pfs-auth"
+          TEST_APP_KEYCLOAK_CLIENT_ID: ${{ secrets.TEST_APP_KEYCLOAK_CLIENT_ID }}
+          TEST_APP_KEYCLOAK_CLIENT_SECRET: ${{ secrets.TEST_APP_KEYCLOAK_CLIENT_SECRET }}
+          TEST_APP_API_KEY: ${{ secrets.TEST_APP_API_KEY }}
+          TEST_APP_PRIVATE_KEY: ${{ secrets.TEST_APP_PRIVATE_KEY }}
 
   # TODO: Reuse docker container for sandbox deployment, don't rebuild docker container
   deploy-qa-sandbox:
diff --git a/.github/workflows/pull-request-checks.yml b/.github/workflows/pull-request-checks.yml
@@ -38,30 +38,34 @@ jobs:
       PROXYGEN_KEY_ID: ${{ secrets.PROXYGEN_KEY_ID }}
       PROXYGEN_PRIVATE_KEY: ${{ secrets.PROXYGEN_PRIVATE_KEY }}
 
-  # Uncomment the following section to enable end-to-end tests once the tests are fixed in NPA-5244
-  # run-end-to-end-tests:
-  #   name: "Run End to End Tests"
-  #   runs-on: ubuntu-latest
-  #   needs: deploy-dev-app
-  #   steps:
-  #     - name: Checkout Repository
-  #       uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
-  #       with:
-  #         fetch-depth: 0
-  #         persist-credentials: false
-  #     - name: Setup Python Dependencies
-  #       uses: ./.github/actions/setup-python-dependencies
-  #     - name: Setup proxygen
-  #       uses: ./.github/actions/setup-proxygen
-  #       with:
-  #         PROXYGEN_CLIENT_ID: ${{ secrets.PROXYGEN_CLIENT_ID }}
-  #         PROXYGEN_KEY_ID: ${{ secrets.PROXYGEN_KEY_ID }}
-  #         PROXYGEN_PRIVATE_KEY: ${{ secrets.PROXYGEN_PRIVATE_KEY }}
-  #     - name: Run End to End Tests
-  #       uses: ./.github/actions/run-end-to-end-tests
-  #       env:
-  #         PROXYGEN_URL_PATH: ${{ needs.deploy-dev-app.outputs.proxygen_url_path }}
-  #         APIGEE_PROXY_NAME: "im1-pfs-auth--internal-dev--${{ needs.deploy-dev-app.outputs.proxygen_url_path }}"
+  run-end-to-end-tests:
+    name: "Run End to End Tests"
+    runs-on: ubuntu-latest
+    needs: deploy-dev-app
+    steps:
+      - name: Checkout Repository
+        uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+      - name: Setup Python Dependencies
+        uses: ./.github/actions/setup-python-dependencies
+      - name: Setup proxygen
+        uses: ./.github/actions/setup-proxygen
+        with:
+          PROXYGEN_CLIENT_ID: ${{ secrets.PROXYGEN_CLIENT_ID }}
+          PROXYGEN_KEY_ID: ${{ secrets.PROXYGEN_KEY_ID }}
+          PROXYGEN_PRIVATE_KEY: ${{ secrets.PROXYGEN_PRIVATE_KEY }}
+      - name: Run End to End Tests
+        uses: ./.github/actions/run-end-to-end-tests
+        env:
+          PROXYGEN_URL_PATH: ${{ needs.deploy-dev-app.outputs.proxygen_url_path }}
+          PROXY_NAME: "im1-pfs-auth"
+          APIGEE_PROXY_NAME: "im1-pfs-auth--internal-dev--${{ needs.deploy-dev-app.outputs.proxygen_url_path }}"
+          TEST_APP_KEYCLOAK_CLIENT_ID: ${{ secrets.TEST_APP_KEYCLOAK_CLIENT_ID }}
+          TEST_APP_KEYCLOAK_CLIENT_SECRET: ${{ secrets.TEST_APP_KEYCLOAK_CLIENT_SECRET }}
+          TEST_APP_API_KEY: ${{ secrets.TEST_APP_API_KEY }}
+          TEST_APP_PRIVATE_KEY: ${{ secrets.TEST_APP_PRIVATE_KEY }}
 
   deploy-dev-sandbox:
     name: "Deploy Pull Request Sandbox Environment"
diff --git a/Makefile b/Makefile
@@ -166,12 +166,17 @@ sandbox-unit-test:
 # Runs End to End tests against a deployed environment
 e2e-tests end-to-end-tests:
 # Mandatory arguments:
+# TEST_APP_KEYCLOAK_CLIENT_ID: Client Id issued to the mocked authorisation provider client. Obtained by the GET Keycloak credentials endpoint.
+# TEST_APP_KEYCLOAK_SECRET: Secret assigned to the mocked authorisation provider client. Obtained by the GET Keycloak credentials endpoint.
+# TEST_APP_API_KEY: API Key for test application in the developer portal (https://dos-internal.ptl.api.platform.nhs.uk/MyApplications)
+# TEST_APP_PRIVATE_KEY: Private Key from key pair for test application in the developer portal (https://dos-internal.ptl.api.platform.nhs.uk/MyApplications)
 # APIGEE_ACCESS_TOKEN: "proxygen pytest-nhsd-apim --api=im1-pfs-auth get-token | jq -r .pytest_nhsd_apim_token"
 # APIGEE_PROXY_NAME: The name of the proxy to test (e.g., im1-pfs-auth--internal-dev--im1-pfs-auth-pr-31)
 # PROXYGEN_URL_PATH: The URL path for the Proxygen API (e.g. im1-pfs-auth-pr-31)
 	uv run pytest tests/end_to_end \
 		--api-name=im1-pfs-auth --proxy-name=${APIGEE_PROXY_NAME} \
-		--disable-warnings -o log_cli_level=INFO
+		--disable-warnings -o log_cli_level=INFO \
+		${PYTEST_ARGS}
 
 # ==============================================================================
 
diff --git a/README.md b/README.md
@@ -149,9 +149,17 @@ To run end to end tests use the following commands:
 
 ```shell
 export APIGEE_ACCESS_TOKEN=$(proxygen pytest-nhsd-apim --api=im1-pfs-auth get-token | jq -r .pytest_nhsd_apim_token)
-make end-to-end-test PROXYGEN_URL_PATH=<proxygen_url_path> PROXY_NAME=<proxy_name> APIGEE_PROXY_NAME=<apigee_proxy_name>
+export TEST_APP_KEYCLOAK_CLIENT_ID=KEYCLOAK_CLIENT_ID
+export TEST_APP_KEYCLOAK_CLIENT_SECRET=KEYCLOAK_SECRET
+export TEST_APP_API_KEY=APP_CLIENT_API_KEY
+export TEST_APP_PRIVATE_KEY=$(cat {path_to_private_key.pem})
+make end-to-end-tests PROXYGEN_URL_PATH=im1-pfs-auth-pr-46 PROXY_NAME=im1-pfs-auth APIGEE_PROXY_NAME=im1-pfs-auth--internal-dev--im1-pfs-auth-pr-46
 ```
 
+- `TEST_APP_KEYCLOAK_CLIENT_ID`: Client Id issued to the mocked authorisation provider client. Obtained by the GET Keycloak credentials endpoint.
+- `TEST_APP_KEYCLOAK_CLIENT_SECRET`: Secret assigned to the mocked authorisation provider client. Obtained by the GET Keycloak credentials endpoint.
+- `TEST_APP_API_KEY`: API Key for test application in the developer portal (https://dos-internal.ptl.api.platform.nhs.uk/MyApplications)
+- `TEST_APP_PRIVATE_KEY`: Private Key from key pair for test application in the developer portal (https://dos-internal.ptl.api.platform.nhs.uk/MyApplications)
 - `PROXYGEN_URL_PATH`: The URL path for the Proxygen API (e.g. im1-pfs-auth-pr-31)
 - `PROXY_NAME`: The name of the proxy (e.g. im1-pfs-auth)
 - `APIGEE_PROXY_NAME`: The name of the proxy to test (e.g., im1-pfs-auth--internal-dev--im1-pfs-auth-pr-31)
diff --git a/app/api/app.py b/app/api/app.py
@@ -31,7 +31,7 @@ def authentication() -> Response:
         response = route_and_forward(forward_request)
         return make_response(
             jsonify(response.model_dump()),
-            HTTPStatus.OK,
+            HTTPStatus.CREATED,
         )
     except ApiError as e:
         return make_response(jsonify(message=e.message), e.status_code)
diff --git a/app/api/tests/test_app.py b/app/api/tests/test_app.py
@@ -40,7 +40,7 @@ def test_authentication_post(
     actual_result = client.post("/authentication")
 
     # Assert
-    assert actual_result.status_code == 200
+    assert actual_result.status_code == 201
     assert actual_result.get_json() == mocked_forward_request_response
     mock_forward_request.assert_called_once()
     mock_route_and_forward.assert_called_once_with(mock_forward_request.return_value)
diff --git a/docs/user-guides/NHS_developer_hub.md b/docs/user-guides/NHS_developer_hub.md
@@ -0,0 +1,25 @@
+# Guide: NHS developer hub
+
+## Overview
+
+The NHS developer hub is the platform for managing applications which interact with NHS APIs. The primary use case for IM1 is for the management of API keys and credentials used in accessing the mock credentials service used in testing.
+
+## Registration
+
+There are two instances of NHS developer hub, [production](https://onboarding.prod.api.platform.nhs.uk) and [internal](https://dos-internal.ptl.api.platform.nhs.uk). Developers are encouraged to register for both platforms however, for the purposes of IM1 development, the internal instance is of higher priority.
+
+## Proxy Dev Team
+
+Once registered with the developer hub, developers must be added to the `Proxy Dev Team`. This must be done by the one of the `Proxy Dev Team` owners.
+
+## IM1 PFS Auth Developer Test App
+
+The `Proxy Dev Team` maintains the IM1 PFS Auth Developer Test App on the internal NHS developer hub. This application is responsible for the management of API keys and public signing key.
+
+### API keys
+
+From the application page, the API key can be accessed via `Security details` -> `Active API keys` -> `Edit`. Here keys can be rotated, created, and revoked. This key is used as `TEST_APP_API_KEY` in our environment variables.
+
+### Public key
+
+The public signing key can be changed via `Security details` -> `Public key URL` -> `Edit`, where generation of the public key is documented under [Section 3](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation/user-restricted-restful-apis-nhs-login-separate-authentication-and-authorisation#step-3-generate-a-key-pair) of [User-restricted RESTful APIs - NHS login separate authentication](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation/user-restricted-restful-apis-nhs-login-separate-authentication-and-authorisation).
diff --git a/docs/user-guides/Proxygen_CLI.md b/docs/user-guides/Proxygen_CLI.md
@@ -28,6 +28,18 @@ The proxygen CLI is a dedicated command-line interface tool designed to streamli
    pip install proxygen-cli
    ```
 
+   Alternative proxygen install
+
+   Proxygen currently, 2025-10-09, fails to build with Python 3.13, the version used in the IM1 repository, due to an inability to build `lxml==4.9.4`.
+
+   A workaround is to create a separate virtual environment at a lower Python version, then build proxygen for that environment, and transfer the binary to the IM1 repository virtual environment.
+
+   ```shell
+   uv venv -p 3.12 # In a directory not containing the IM1 repository
+   uv pip install proxygen-cli
+   cp .venv/bin/proxygen <IM1 Repository>/.venv/bin/
+   ```
+
 2. Confirm the installation by checking the version:
 
    ```shell
diff --git a/docs/user-guides/Setup_end_to_end_tests.md b/docs/user-guides/Setup_end_to_end_tests.md
@@ -0,0 +1,52 @@
+# Guide: Setup end to end tests
+
+- [Guide: Setup end to end tests](#guide-setup-end-to-end-tests)
+  - [Overview](#overview)
+  - [Associating ephemeral deployments with IM1 PFS Auth Developer Test App](#associating-ephemeral-deployments-with-im1-pfs-auth-developer-test-app)
+    - [Launching the ephemeral deployment](#launching-the-ephemeral-deployment)
+    - [Associating the deployment with the developer app](#associating-the-deployment-with-the-developer-app)
+  - [Testing](#testing)
+
+## Overview
+
+When performing end to end tests, a composite authentication token is retrieved from APIM's `mock-jwks` API. Composite tokens are currently, 2025-10-13, only enabled for the `internal-dev` environment. Therefore they cannot be ran against `internal-qa` in the CI/CD pipeline.
+
+End to end tests can be ran from `internal-dev`, including ephemeral deployments created by PRs. For ephemeral deployments however, this requires associating the API Product with the IM1 PFS Auth Developer Test App, which has access to the correct instance of `mock-jwks`, as outlined below.
+
+## Associating ephemeral deployments with IM1 PFS Auth Developer Test App
+
+### Launching the ephemeral deployment
+
+<!-- markdownlint-disable-next-line no-inline-html -->
+
+A deployment is automatically span up upon the [creation of a PR](./Workflows.md#core-workflows) with the naming pattern `im1-pfs-auth-pr-<pr_number>`. The deployment can be verified by searching for `im1` in the APIGEE > Develop > API Proxies UI, the API proxy will be shown as `im1-pfs-auth--internal-dev--im1-pfs-auth-pr-<pr_number>`.
+
+### Associating the deployment with the developer app
+
+To allow the ephemeral deployment to access the `mock-jwks` service, it must be associated with the IM1 PFS Auth Developer Test App. To do so you must first be added to the `Proxy Dev Team` on the [NHS Internal Developer Hub](./NHS_developer_hub.md).
+
+Once added to the `Proxy Dev Team`, the deployment can be associated to the developer app using [Apigee](https://apigee.com/edge) under the `nhsd-nonprod` organisation. To associate the deployment with the developer app:
+
+- Navigate to `Publish` -> `Apps`
+- Search for `IM1`
+  - Note: searching can be a slow process due to indexing time)
+- Select IM1 PFS Auth Developer Test App
+- Select `Edit` in the top right of the page
+- Under `Credentials` select `Add product`
+- Search for `pr-<pr_number>`
+- Add the `IM1 PFS Auth API - IM1 PFS Auth - P9 User Restriced Access (dev) (Internal Development)` product
+  - Note: This is **not** the `(Internal Development Sandbox)` product
+- Finalise the change by selecting `Save` in the top right of the page
+
+## Testing
+
+The deployment should now be associated with the app and end to end tests can be run as part of the [pull request checks GitHub workflow](../../.github/workflows/pull-request-checks.yml).
+
+For the general overview of running end to end tests locally, see the relevant section of the README. The additional required inputs are:
+
+- `PROXYGEN_URL_PATH`: `im1-pfs-auth-pr-<pr_number>`
+- `APIGEE_PROXY_NAME` `im1-pfs-auth--internal-dev--im1-pfs-auth-pr-<pr_number>`
+
+### `TEST_APP_PRIVATE_KEY`
+
+The private key counterpart to the key pair registered on the internal NHS Developer Hub platform is required. This can be requested from the development team.
diff --git a/pyproject.toml b/pyproject.toml
@@ -25,7 +25,7 @@ dev = [
 ]
 
 [tool.uv]
-required-version = "~=0.8.0"
+required-version = "~=0.9.0"
 package = false
 default-groups = "all"
 override-dependencies = ["typing-extensions==4.12.2", "requests==2.32.5"]
diff --git a/scripts/config/vale/styles/config/vocabularies/words/accept.txt b/scripts/config/vale/styles/config/vocabularies/words/accept.txt
@@ -5,10 +5,12 @@ Bitwarden
 Bloomreach
 Cyber
 Dependabot
+(?i)dev
 Gitleaks
 Grype
 Gunicorn
 Jira
+Keycloak
 OAuth
 Octokit
 Podman
diff --git a/tests/end_to_end/authentication/POST/test_201.py b/tests/end_to_end/authentication/POST/test_201.py
@@ -12,7 +12,10 @@
 
 
 @pytest.mark.positive
-def test_happy_path(request: pytest.FixtureRequest, api_url: str) -> None:
+@pytest.mark.parametrize("forward_to_url", ["https://emis.com"])
+def test_happy_path(
+    request: pytest.FixtureRequest, api_url: str, forward_to_url: str
+) -> None:
     """Test the happy path for the API.
 
     Test Scenario:
@@ -21,22 +24,25 @@ def test_happy_path(request: pytest.FixtureRequest, api_url: str) -> None:
         Then: the response status code is 200
         And: the response body contains the expected data
 
-    NOTE: This test does not work due to missing composite derived access token.
     """
     # Arrange
     uuid = str(uuid4())
+    proxy_identifier = "9912003071"  # P9 User with composite token
     headers = {
-        "Authorization": get_authentication_token(request),
+        "Authorization": get_authentication_token(proxy_identifier, request),
         "X-Application-ID": request.node.name,
         "X-Request-ID": uuid,
-        "X-Forward-To": "",
-        "X-ODS-Code": "",
+        "X-Forward-To": forward_to_url,
+        "X-ODS-Code": "ODS123",
         "X-Correlation-ID": uuid,
     }
     # Act
     response = post(api_url, headers=headers, timeout=5)
     # Assert
-    logger.info(
-        f"API response: status_code {response.status_code}, response: {response.json()}"
-    )
-    assert response.status_code == 200
+    assert response.status_code == 201
+    assert response.json() == {
+        "patients": [{"first_name": "Jeremy", "surname": "Jones", "title": "Mr"}],
+        "proxy": {"first_name": "Betty", "surname": "Jones", "title": "Ms"},
+        "session_id": "123",
+        "supplier": "EMIS",
+    }
diff --git a/tests/end_to_end/authentication/POST/test_400.py b/tests/end_to_end/authentication/POST/test_400.py
diff --git a/tests/end_to_end/authentication/POST/test_401.py b/tests/end_to_end/authentication/POST/test_401.py
diff --git a/tests/end_to_end/utils/apigee_authentication.py b/tests/end_to_end/utils/apigee_authentication.py

Original file line number	Diff line number	Diff line change
`@@ -31,7 +31,7 @@ def authentication() -> Response:`
`31`	`31`	`response = route_and_forward(forward_request)`
`32`	`32`	`return make_response(`
`33`	`33`	`jsonify(response.model_dump()),`
`34`		`- HTTPStatus.OK,`
	`34`	`+ HTTPStatus.CREATED,`
`35`	`35`	`)`
`36`	`36`	`except ApiError as e:`
`37`	`37`	`return make_response(jsonify(message=e.message), e.status_code)`