From 41b40bc1892095415a79f13c0721fbf12b0d4c96 Mon Sep 17 00:00:00 2001 From: Jack Plowman <62281988+JackPlowman@users.noreply.github.com> Date: Wed, 18 Jun 2025 12:15:06 +0100 Subject: [PATCH 1/5] NPA-5116 Add Generic Authorisation Documentation --- .../validated-relationships-service-api.yaml | 41 ++++++++++++++----- 1 file changed, 31 insertions(+), 10 deletions(-) diff --git a/specification/validated-relationships-service-api.yaml b/specification/validated-relationships-service-api.yaml index e41beaa9..c3d5be08 100644 --- a/specification/validated-relationships-service-api.yaml +++ b/specification/validated-relationships-service-api.yaml @@ -72,20 +72,41 @@ info: For more details see [Network access for APIs](https://digital.nhs.uk/developer/guides-and-documentation/network-access-for-apis). - ## Security and authorisation + ## Access Modes - This API is [user-restricted](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation#user-restricted-apis), meaning an end user must be present, authenticated and authorised. + This API supports both [user-restricted](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation#user-restricted-apis) and [application-restricted](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation#application-restricted-apis) access modes. - The end user must be: - * a patient who receives health and social care or makes use of NHS services - * strongly authenticated, using [NHS login](https://digital.nhs.uk/services/nhs-login) + - [User-restricted access](#user-restricted-access) meaning an end user must be present, authenticated and authorised. + - [Application-restricted access](#application-restricted-access) meaning we authenticate the calling application but not the end user - To use this access mode, use one of the following security patterns: + For more information on access modes and how to use them, see the developer [security and authorisation guide](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation). - | Security pattern | Technical details | Advantages | Disadvantages | - |-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| ----------------------------------------------------| ------------------------------------------------------------|---------------------------------------------------------| - |[NHS login - combined authentication and authorisation](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation/user-restricted-restful-apis-nhs-login-combined-authentication-and-authorisation) |OAuth 2.0 authorisation code with API key and secret |No need to integrate and onboard separately with NHS login. |No access to user information. | - |[NHS login - separate authentication and authorisation](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation/user-restricted-restful-apis-nhs-login-separate-authentication-and-authorisation) |OAuth 2.0 token exchange with signed JWT |Gives access to user information. |Need to integrate and onboard separately with NHS login. | + ### User-restricted access + + User-restricted access meaning an end user must be present, authenticated and authorised. + + #### Patient access mode + If the end user is a patient then you must use this access mode. + + [Review all patient access modes](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation#patient-access-mode) + + Validated Relationships Service checks the patient is P9 verified and has a high [vector of trust](https://nhsconnect.github.io/nhslogin/vectors-of-trust/) (VOT). + + Allowed vectors of trust are: + - `P9.Cp.Cd` + - `P9.Cp.Ck` + - `P9.Cm` + + #### Healthcare worker access mode + If the end user is a healthcare worker then you must use this access mode. + + [Review all CIS2 healthcare worker access modes](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation#healthcare-worker-access-mode) + + ### Application-restricted access + + This API is application-restricted, meaning we authenticate the calling application but not the end user. + + [Review all application-restricted access modes](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation#application-restricted-apis) ## Headers This API is case-insensitive when processing request headers, meaning it will accept headers regardless of the letter casing used. (e.g. X-Request-Id, x-request-id are treated the same). When sending headers back in the response, we preserve the exact casing as received in the original request. From 5de7180c76431b836e400a5ccd724488e17c8a7b Mon Sep 17 00:00:00 2001 From: Jack Plowman <62281988+JackPlowman@users.noreply.github.com> Date: Wed, 18 Jun 2025 12:27:40 +0100 Subject: [PATCH 2/5] NPA-5116 Docuemnt each endpoint authentication allowed methods --- .../validated-relationships-service-api.yaml | 40 +++++++++++++++++++ 1 file changed, 40 insertions(+) diff --git a/specification/validated-relationships-service-api.yaml b/specification/validated-relationships-service-api.yaml index c3d5be08..04b59dbf 100644 --- a/specification/validated-relationships-service-api.yaml +++ b/specification/validated-relationships-service-api.yaml @@ -183,6 +183,11 @@ paths: For the most part demographics information doesn't need to be provided in the access request since it can be pulled from PDS. + ## Access modes + + This endpoint supports the following access modes: + - Patient access + ## Sandbox test scenarios | Scenario | Request | Response | @@ -288,6 +293,12 @@ paths: A valid reference code must be provided as a query parameter. This reference code is returned when a QuestionnaireResponse is initially submitted via the POST endpoint. + ## Access modes + + This endpoint supports the following access modes: + - Patient access + - Healthcare worker access + ## Sandbox test scenarios | Scenario | Request | Response | @@ -377,6 +388,12 @@ paths: You can (optionally) include the `_include=RelatedPerson:patient` request parameter to include the patient's details in the response. + ## Access modes + + This endpoint supports the following access modes: + - Patient access + - Healthcare worker access + ## Sandbox test scenarios | Scenario | Request | Response | @@ -496,6 +513,13 @@ paths: You can (optionally) include the `_include=Consent:patient` request parameter to include the patient's details in the response. + ## Access modes + + This endpoint supports the following access modes: + - Patient access + - Healthcare worker access + - Application-restricted access + ## Sandbox test scenarios | Scenario | Request | Response | @@ -639,6 +663,11 @@ paths: ## Overview Use this endpoint to create a new proxy role between a patient and a related person (proxy). + ## Access modes + + This endpoint supports the following access modes: + - Healthcare worker access + ## Sandbox test scenarios The sandbox supports a limited number of scenarios, and does not attempt to validate requests. The returned result is dependant on the `performer.identifier.value`. @@ -765,6 +794,11 @@ paths: You can (optionally) include the `_include=Consent:patient` request parameter to include the patient's details in the response. + ## Access modes + + This endpoint supports the following access modes: + - Healthcare worker access + ## Sandbox test scenarios The sandbox supports a limited number of scenarios, and does not attempt to validate requests. The returned result is dependant on the `ID` for the consent resource. @@ -878,6 +912,12 @@ paths: * JSON Patch operations must be valid according to RFC 6902 * Status changes must use valid status codes from + ## Access modes + + This endpoint supports the following access modes: + - Patient access + - Healthcare worker access + ## Sandbox test scenarios The sandbox supports a limited number of scenarios, and does not attempt to validate requests. The returned response is dependant on the `id` parameters. From 105fdcd5e21a22906b4b162fcd97ccd4c8842456 Mon Sep 17 00:00:00 2001 From: Jack Plowman <62281988+JackPlowman@users.noreply.github.com> Date: Wed, 18 Jun 2025 13:05:06 +0100 Subject: [PATCH 3/5] NPA-5116 Improve Wording --- specification/validated-relationships-service-api.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/validated-relationships-service-api.yaml b/specification/validated-relationships-service-api.yaml index 04b59dbf..2fe520d8 100644 --- a/specification/validated-relationships-service-api.yaml +++ b/specification/validated-relationships-service-api.yaml @@ -90,7 +90,7 @@ info: [Review all patient access modes](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation#patient-access-mode) - Validated Relationships Service checks the patient is P9 verified and has a high [vector of trust](https://nhsconnect.github.io/nhslogin/vectors-of-trust/) (VOT). + Validated Relationships Service API checks the patient is P9 verified and has a high [vector of trust](https://nhsconnect.github.io/nhslogin/vectors-of-trust/) (VOT). Allowed vectors of trust are: - `P9.Cp.Cd` From c40c598e8737c517f6e84181fa255c8bc1d76cdc Mon Sep 17 00:00:00 2001 From: Jack Plowman <62281988+JackPlowman@users.noreply.github.com> Date: Wed, 18 Jun 2025 13:14:24 +0100 Subject: [PATCH 4/5] NPA-5116 Improve Links and Titles --- specification/validated-relationships-service-api.yaml | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/specification/validated-relationships-service-api.yaml b/specification/validated-relationships-service-api.yaml index 2fe520d8..289f91fe 100644 --- a/specification/validated-relationships-service-api.yaml +++ b/specification/validated-relationships-service-api.yaml @@ -72,12 +72,12 @@ info: For more details see [Network access for APIs](https://digital.nhs.uk/developer/guides-and-documentation/network-access-for-apis). - ## Access Modes + ## Security and authorisation This API supports both [user-restricted](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation#user-restricted-apis) and [application-restricted](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation#application-restricted-apis) access modes. - - [User-restricted access](#user-restricted-access) meaning an end user must be present, authenticated and authorised. - - [Application-restricted access](#application-restricted-access) meaning we authenticate the calling application but not the end user + - [User-restricted access](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation#user-restricted-apis) + - [Application-restricted access](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation#application-restricted-apis) For more information on access modes and how to use them, see the developer [security and authorisation guide](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation). From 1e093b621f1d9b644560dddc2d4172d4203b4a3d Mon Sep 17 00:00:00 2001 From: Jack Plowman <62281988+JackPlowman@users.noreply.github.com> Date: Wed, 18 Jun 2025 13:37:36 +0100 Subject: [PATCH 5/5] NPA-5116 Update Security and authorisation contents --- specification/validated-relationships-service-api.yaml | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/specification/validated-relationships-service-api.yaml b/specification/validated-relationships-service-api.yaml index 289f91fe..f02452b2 100644 --- a/specification/validated-relationships-service-api.yaml +++ b/specification/validated-relationships-service-api.yaml @@ -74,10 +74,13 @@ info: ## Security and authorisation - This API supports both [user-restricted](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation#user-restricted-apis) and [application-restricted](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation#application-restricted-apis) access modes. + This API supports both [user-restricted](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation#user-restricted-apis) and [application-restricted](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation#application-restricted-apis) access types with the following access modes: - - [User-restricted access](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation#user-restricted-apis) - - [Application-restricted access](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation#application-restricted-apis) + | Access mode | Access type | + |-------------------------------|------------------------| + | Patient access | User-restricted | + | Healthcare worker access | User-restricted | + | Application-restricted access | Application-restricted | For more information on access modes and how to use them, see the developer [security and authorisation guide](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation).