From 6e985d9f8c253382b00cb6f096296b94215deb81 Mon Sep 17 00:00:00 2001 From: luci-davies Date: Mon, 20 Oct 2025 17:47:22 +0100 Subject: [PATCH 1/4] Update Onboarding.page.md --- .../Onboarding.page.md | 78 +++++++++---------- 1 file changed, 37 insertions(+), 41 deletions(-) diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Build/Testing-and-Environments/Onboarding.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Build/Testing-and-Environments/Onboarding.page.md index 68b3ca2a..55edd183 100644 --- a/guides/Live-ImplementationGuide-BaRS/Home/Build/Testing-and-Environments/Onboarding.page.md +++ b/guides/Live-ImplementationGuide-BaRS/Home/Build/Testing-and-Environments/Onboarding.page.md @@ -4,18 +4,21 @@ topic: onboarding ## {{page-title}} -API-M provides the [security model](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation/application-restricted-restful-apis-signed-jwt-authentication) for BaRS. - -There are two roles: Sender and Receiver. Most BaRS Applications will require a solution to support both roles, despite being predominantly one or the other, because of the response workflow steps. In response flows, the original Sender becomes a Receiver and the original Receiver becomes a Sender. +In each BaRS workflow there are two roles: Sender and Receiver. In applications with response workflows, both parties act as a Sender and a Receiver, and will need to follow the instructions to onboard as both. The Sender obtains a token from the API-M platform to make requests of the BaRS API Proxy, which brokers the request through the Receiver, secured via TLS-MA (Transport Layer Security-Mutual Authentication). BaRS is based on internet-first principles and there is no requirement for [Health and Social Care Network (HSCN)](https://digital.nhs.uk/services/health-and-social-care-network) connectivity. -### Sender -* [Follow the steps here to get set up](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation/user-restricted-restful-apis-nhs-login-separate-authentication-and-authorisation#step-1-register-your-application-with-nhs-login) +### Sender Onboarding + +API-M provides the [security model](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation/application-restricted-restful-apis-signed-jwt-authentication) for BaRS. + +To onboard as a sender follow these steps: + +Step 1: follow the NHS Developer authenitication and authorisation process [NHS Developer authentication and authorisation](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation/user-restricted-restful-apis-nhs-login-separate-authentication-and-authorisation#step-1-register-your-application-with-nhs-login) -The sender will also need to trust the Certificate Authorities mentioned below. For INT this will be downloadable from http://pki.nhs.uk/int/G2/auth/NHSINTAuthG2.crt +Step 2: trust the Certificate Authorities (CA) mentioned below. For INT this will be downloadable from http://pki.nhs.uk/int/G2/auth/NHSINTAuthG2.crt ( you can examine the .cer file if you have one ) ``` openssl x509 -in barsintreceiver.cer -text -noout @@ -40,61 +43,54 @@ sudo cp ca-chain.pem /usr/local/share/ca-certificates/ sudo update-ca-certificat This will ensure that your system trusts the certificates issued by the CA. -### Receiver -BaRS will utilise TLS-MA to communicate with Receiving endpoints. Receiving endpoints will require a certificate under the NHS Root CA to facilitate TLS-MA. - -* The receiver must request a certificate under the NHS Root CA - * There are different certificate chains for INT and Prod - * [INT Certificate](https://digital.nhs.uk/services/path-to-live-environments/integration-environment#rootca-and-subca-certificates) chains (**Note:** _these may be out of date_) - * [Prod Certificate](https://digital.nhs.uk/services/path-to-live-environments/live-environment) chains (**Note:** _these may be out of date_) -* The receiving endpoint will present the certificate obtained for TLS-MA -* The receiving endpoint will need to trust the Root CAs and SubCAs for their respective environments -* The receiving endpoint will only accept requests presented with certificates from their respective chains - -As the certificates are using the NHS Root CA, the FQDN must be an nhs.uk address. This is the case for both INT and Prod. +### Receiver Onboarding +BaRS will utilise TLS-MA to communicate with Receiving endpoints. Receiving endpoints will require a certificate under the NHS Root CA to facilitate TLS-MA. The receiver will need to follow these steps for Integration and Production environments. -You can apply for your domain [here](https://digital.nhs.uk/services/networking-addressing/apply-for-an-nhs.uk-domain-for-websites-and-web-applications), ensuring that you complete Section 5: For website or application records visible on the public internet. +To onboard as a receiver follow these steps: -Once you have your domain registered, you can then begin the process to obtain your certificate by generating a certificate request. +Step 1: Apply for your domain [apply for a new nhs.uk domain](https://digital.nhs.uk/services/networking-addressing/apply-for-an-nhs.uk-domain-for-websites-and-web-applications). You must complete Section 5: For website or application records visible on the public internet. -Certificate requests will need to be signed for your endpoint. Note that the fully qualified domain (FQDN) name is equal to the certificate name (CN) by convention. +Step 2: Request a certificate under the NHS Root CA. The FQDN must be an nhs.uk address. + * There are different certificate chains for INT and Prod + * [INT Certificate](https://digital.nhs.uk/services/path-to-live-environments/integration-environment#rootca-and-subca-certificates) chains (**Note:** _these may be out of date_) + * [Prod Certificate](https://digital.nhs.uk/services/path-to-live-environments/live-environment) chains (**Note:** _these may be out of date_)stered, you can then begin the process to obtain your certificate by generating a certificate request. +The fully qualified domain name (FQDN) is equal to the certificate name (CN) by convention. -You need to create a Certificate Signing Request (*.csr). This is the file you will send to us so we can generate a signed certificate for your endpoints. The first step is to create a private key; a password is optional. +Step 3: Create a Certificate Signing Request (*.csr). This is the file you will send to us so we can generate a signed certificate for your endpoints. Create a private key; a password is optional. ``` openssl genpkey -algorithm RSA -out private.key -aes256 ``` -Then, to create the *.csr, use the following command:
+Create the *.csr, use the following command:
**Note:** _Generate the CSR with only the common name field populated, which must match the FQDN. All other fields can remain blank. The email field MUST be blank. Please note FQDNs MUST be in the .nhs.uk domain as we can only issue certificates in this domain._ ``` openssl req -new -key private.key -out request.csr ``` -At this point, you should have a .key and a .csr file. The next step will be to send the .csr file to be signed by the NHS and get the client certificate. For full steps, see the sections below for each environment. +Step 4: Send the .csr file to be signed by the NHS and get the client certificate. To do this, follow these environment specific steps: -#### Integration (INT) -* [Request](https://digital.nhs.uk/services/path-to-live-environments/path-to-live-forms/combined-endpoint-and-service-registration-request) a ‘certificate only’ from ITOC - * {{render:Onboarding FORM.png}} - * Certificate Only (No endpoint) - * Integration environment +#### Client certificate: Integration (INT) +Step 1: Contact ITOC to make a [Combined endpoint and service registration request](https://digital.nhs.uk/services/path-to-live-environments/path-to-live-forms/combined-endpoint-and-service-registration-request) + {{render:Onboarding FORM.png}} + In the form: + * Select Create/renew a certificate only (No endpoint) + * Specify Integration environment * FQDN must match your domain and CN on the cert e.g. '**BaRS-INT-\.\.thirdparty.nhs.uk**' - * Ensure it is clear this is a request for a ‘BaRS’ certificate - * ‘N/A’ in the Party Key section because there is no relation to SDS endpoints -* Receive certificate from ITOC -* Email with Receiver URL for BaRS/API-M to add to the Endpoint Catalogue - -#### Production (Prod) -* Once Solution Assurance issues the supplier with the Technical Conformance certificate, Production endpoints can be requested -* Send the .csr to , indicating this is for a BaRS Receiver endpoint + * In Additional comments/notes, state ‘BaRS’ certificate request + * Add ‘N/A’ in the Party Key field because there is no relation to SDS endpoints +Step 2: Receive certificate from ITOC +Step 3: Email with Receiver URL for BaRS/API-M to add to the Endpoint Catalogue + +#### Client certificate: Production (Prod) +Production endpoints can only be requested when Solution Assurance issue the supplier with the Technical Conformance certificate, +Step1: Send the .csr to , indicating this is for a BaRS Receiver endpoint * Format for FQDN on PROD for: * Supplier hosted solutions is ‘**BaRS-PROD-\.\.thirdparty.nhs.uk**’ * This option is used for multi-tenanted solutions. * Service Provider hosted solutions is ‘**BaRS-PROD-\.\.nhs.uk**’ * This option is used for non multi-tenanted solutions. If multiple endpoints are needed, the ODS code can be appended with an identifier for the setting. * It may be that the provider already has a 'nhs.uk' standard domain DNS entry. If one exists, it should be used for this new subdomain. -* Receive certificate from DIR Team -* Email with Receiver URL for BaRS/API-M to add to the Endpoint Catalogue - -**Note:** **Receiver Firewall Amendments** - Requests from the BaRS API Proxy will originate from **INT** on **35.197.254.55** & **35.246.55.143** and **PROD** on **34.89.0.111** & **34.89.69.6**. +Step 2: Receive certificate from DIR Team +Step 3: Email with Receiver URL for BaRS/API-M to add to the Endpoint Catalogue Once you have the certificate from the NHS service desk, copy the text for the cert with the `-----BEGIN CERTIFICATE` as the first line and `END CERTIFICATE-----` as the last. Save this text locally as a file called barsinreceiver.cer (change the name to suit). From 280ce3dbf51916a59ed76dab6a7d3c1f58355112 Mon Sep 17 00:00:00 2001 From: luci-davies Date: Mon, 20 Oct 2025 17:54:20 +0100 Subject: [PATCH 2/4] Firewall exceptions --- .../DirectoryOfServiceConfiguration.md | 2 ++ .../Deploy/Technical deployment/Firewallexceptions.md | 10 ++++++++++ ... deployment.page.md => Technicaldeployment.page.md} | 0 .../Home/Deploy/Technical deployment/toc.yaml | 6 ++++-- 4 files changed, 16 insertions(+), 2 deletions(-) create mode 100644 guides/Live-ImplementationGuide-BaRS/Home/Deploy/Technical deployment/Firewallexceptions.md rename guides/Live-ImplementationGuide-BaRS/Home/Deploy/Technical deployment/{Technical deployment.page.md => Technicaldeployment.page.md} (100%) diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Deploy/Technical deployment/DirectoryOfServiceConfiguration.md b/guides/Live-ImplementationGuide-BaRS/Home/Deploy/Technical deployment/DirectoryOfServiceConfiguration.md index 57912959..ea7d32f2 100644 --- a/guides/Live-ImplementationGuide-BaRS/Home/Deploy/Technical deployment/DirectoryOfServiceConfiguration.md +++ b/guides/Live-ImplementationGuide-BaRS/Home/Deploy/Technical deployment/DirectoryOfServiceConfiguration.md @@ -1,5 +1,7 @@ ## {{page-title}} +**Note:** **Receiver Firewall Amendments** - Requests from the BaRS API Proxy will originate from **INT** on **35.197.254.55** & **35.246.55.143** and **PROD** on **34.89.0.111** & **34.89.69.6**. + If the provider operates within Urgent and Emergency Care (UEC), they are likely to have a UEC Directory of Services (DoS) entry. DoS leads must configure Service Providers who wish to use BaRS in the standard way, as the service dictates, but their DoS ID will also need to exist in the BaRS Endpoint Catalogue. Steps to configure the provider on the BaRS Endpoint Catalogue:- - note the Service ID on DoS diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Deploy/Technical deployment/Firewallexceptions.md b/guides/Live-ImplementationGuide-BaRS/Home/Deploy/Technical deployment/Firewallexceptions.md new file mode 100644 index 00000000..529cbc23 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Deploy/Technical deployment/Firewallexceptions.md @@ -0,0 +1,10 @@ +## {{page-title}} + +BaRS receivers need to configure firewall exceptions for both Integration and Production environments. + +Requests from the BaRS API Proxy will originate from: + +* **INT** on **35.197.254.55** & **35.246.55.143** +* **PROD** on **34.89.0.111** & **34.89.69.6**. + +
diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Deploy/Technical deployment/Technical deployment.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Deploy/Technical deployment/Technicaldeployment.page.md similarity index 100% rename from guides/Live-ImplementationGuide-BaRS/Home/Deploy/Technical deployment/Technical deployment.page.md rename to guides/Live-ImplementationGuide-BaRS/Home/Deploy/Technical deployment/Technicaldeployment.page.md diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Deploy/Technical deployment/toc.yaml b/guides/Live-ImplementationGuide-BaRS/Home/Deploy/Technical deployment/toc.yaml index 03d6de22..f4bcfd0d 100644 --- a/guides/Live-ImplementationGuide-BaRS/Home/Deploy/Technical deployment/toc.yaml +++ b/guides/Live-ImplementationGuide-BaRS/Home/Deploy/Technical deployment/toc.yaml @@ -1,6 +1,8 @@ - name: Index filename: Index.page.md - name: Technical deployment - filename: Technical deployment.page.md + filename: Technicaldeployment.page.md - name: DoS Configuration - filename: DirectoryOfServiceConfiguration.md \ No newline at end of file + filename: DirectoryOfServiceConfiguration.md +- name: Firewall exceptions + filename: Firewallexceptions.md \ No newline at end of file From 949f198c2d8455261c0d623a32b69220ec43da95 Mon Sep 17 00:00:00 2001 From: luci-davies Date: Tue, 21 Oct 2025 13:41:51 +0100 Subject: [PATCH 3/4] App 5 disclaimer and further onboarding work --- .../Applications/BaRS-APP5/Index.page.md | 2 +- .../Onboarding.page.md | 106 ------------------ .../ReceiverOnboarding.page.md | 80 +++++++++++++ .../SenderOnboarding.page.md | 19 ++++ .../Build/Testing-and-Environments/toc.yaml | 4 + 5 files changed, 104 insertions(+), 107 deletions(-) create mode 100644 guides/Live-ImplementationGuide-BaRS/Home/Build/Testing-and-Environments/ReceiverOnboarding.page.md create mode 100644 guides/Live-ImplementationGuide-BaRS/Home/Build/Testing-and-Environments/SenderOnboarding.page.md diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP5/Index.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP5/Index.page.md index 42131a45..f7eec57c 100644 --- a/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP5/Index.page.md +++ b/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP5/Index.page.md @@ -27,7 +27,7 @@ topic: Application5 - +Any suppliers building to this application (Application 5) must engage with NHS England's Pharmacy First/DSIC teams prior to building application 5. ## Use Cases Supported diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Build/Testing-and-Environments/Onboarding.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Build/Testing-and-Environments/Onboarding.page.md index 55edd183..6c503222 100644 --- a/guides/Live-ImplementationGuide-BaRS/Home/Build/Testing-and-Environments/Onboarding.page.md +++ b/guides/Live-ImplementationGuide-BaRS/Home/Build/Testing-and-Environments/Onboarding.page.md @@ -10,109 +10,3 @@ The Sender obtains a token from the API-M platform to make requests of the BaRS BaRS is based on internet-first principles and there is no requirement for [Health and Social Care Network (HSCN)](https://digital.nhs.uk/services/health-and-social-care-network) connectivity. -### Sender Onboarding - -API-M provides the [security model](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation/application-restricted-restful-apis-signed-jwt-authentication) for BaRS. - -To onboard as a sender follow these steps: - -Step 1: follow the NHS Developer authenitication and authorisation process [NHS Developer authentication and authorisation](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation/user-restricted-restful-apis-nhs-login-separate-authentication-and-authorisation#step-1-register-your-application-with-nhs-login) - -Step 2: trust the Certificate Authorities (CA) mentioned below. For INT this will be downloadable from http://pki.nhs.uk/int/G2/auth/NHSINTAuthG2.crt -( you can examine the .cer file if you have one ) -``` -openssl x509 -in barsintreceiver.cer -text -noout -``` -### Some commands that might help to get the Root CA and chain - -To get a cert from an endpoint -``` -openssl s_client -showcerts -connect BaRS-INT-X26.BarsReceiver.thirdparty.nhs.uk:443 < /dev/null | openssl x509 -outform PEM > server-cert.pem -``` -Then to list info from the .pem -``` -openssl x509 -in server-cert.pem -text -noout -``` - -You can use the output from this command to get the full CA chain. - -``` -sudo cp ca-chain.pem /usr/local/share/ca-certificates/ sudo update-ca-certificates -``` - -This will ensure that your system trusts the certificates issued by the CA. - - -### Receiver Onboarding -BaRS will utilise TLS-MA to communicate with Receiving endpoints. Receiving endpoints will require a certificate under the NHS Root CA to facilitate TLS-MA. The receiver will need to follow these steps for Integration and Production environments. - -To onboard as a receiver follow these steps: - -Step 1: Apply for your domain [apply for a new nhs.uk domain](https://digital.nhs.uk/services/networking-addressing/apply-for-an-nhs.uk-domain-for-websites-and-web-applications). You must complete Section 5: For website or application records visible on the public internet. - -Step 2: Request a certificate under the NHS Root CA. The FQDN must be an nhs.uk address. - * There are different certificate chains for INT and Prod - * [INT Certificate](https://digital.nhs.uk/services/path-to-live-environments/integration-environment#rootca-and-subca-certificates) chains (**Note:** _these may be out of date_) - * [Prod Certificate](https://digital.nhs.uk/services/path-to-live-environments/live-environment) chains (**Note:** _these may be out of date_)stered, you can then begin the process to obtain your certificate by generating a certificate request. -The fully qualified domain name (FQDN) is equal to the certificate name (CN) by convention. - -Step 3: Create a Certificate Signing Request (*.csr). This is the file you will send to us so we can generate a signed certificate for your endpoints. Create a private key; a password is optional. -``` -openssl genpkey -algorithm RSA -out private.key -aes256 -``` -Create the *.csr, use the following command:
-**Note:** _Generate the CSR with only the common name field populated, which must match the FQDN. All other fields can remain blank. The email field MUST be blank. Please note FQDNs MUST be in the .nhs.uk domain as we can only issue certificates in this domain._ -``` -openssl req -new -key private.key -out request.csr -``` - -Step 4: Send the .csr file to be signed by the NHS and get the client certificate. To do this, follow these environment specific steps: - -#### Client certificate: Integration (INT) -Step 1: Contact ITOC to make a [Combined endpoint and service registration request](https://digital.nhs.uk/services/path-to-live-environments/path-to-live-forms/combined-endpoint-and-service-registration-request) - {{render:Onboarding FORM.png}} - In the form: - * Select Create/renew a certificate only (No endpoint) - * Specify Integration environment - * FQDN must match your domain and CN on the cert e.g. '**BaRS-INT-\.\.thirdparty.nhs.uk**' - * In Additional comments/notes, state ‘BaRS’ certificate request - * Add ‘N/A’ in the Party Key field because there is no relation to SDS endpoints -Step 2: Receive certificate from ITOC -Step 3: Email with Receiver URL for BaRS/API-M to add to the Endpoint Catalogue - -#### Client certificate: Production (Prod) -Production endpoints can only be requested when Solution Assurance issue the supplier with the Technical Conformance certificate, -Step1: Send the .csr to , indicating this is for a BaRS Receiver endpoint - * Format for FQDN on PROD for: - * Supplier hosted solutions is ‘**BaRS-PROD-\.\.thirdparty.nhs.uk**’ - * This option is used for multi-tenanted solutions. - * Service Provider hosted solutions is ‘**BaRS-PROD-\.\.nhs.uk**’ - * This option is used for non multi-tenanted solutions. If multiple endpoints are needed, the ODS code can be appended with an identifier for the setting. - * It may be that the provider already has a 'nhs.uk' standard domain DNS entry. If one exists, it should be used for this new subdomain. -Step 2: Receive certificate from DIR Team -Step 3: Email with Receiver URL for BaRS/API-M to add to the Endpoint Catalogue - -Once you have the certificate from the NHS service desk, copy the text for the cert with the `-----BEGIN CERTIFICATE` as the first line and `END CERTIFICATE-----` as the last. Save this text locally as a file called barsinreceiver.cer (change the name to suit). - -You will probably need to make a .pfx file so you can serve HTTPS (TLS) endpoints. You can use the command below to export a *.pfx file from the *.key file you made earlier (when you made the *.csr file) along with the *.cer file you were emailed. - -``` -openssl pkcs12 -export -out barsintreceiver.pfx -inkey barsintreceiver.key -in barsintreceiver.cer -``` - -You will be prompted for a password for your .pfx file. You will need to use this password along with the .pfx file. - -Once you have the *.pfx file you can use it the following way (C# example, Other launguages will vary but be similar) - -``` c# - -// Configure Kestrel to use the certificate -builder.WebHost.ConfigureKestrel(options => -{ - options.ListenAnyIP(8080, listenOptions => - { - listenOptions.UseHttps(certPath, certPassword); - }); -}); - -``` \ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Build/Testing-and-Environments/ReceiverOnboarding.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Build/Testing-and-Environments/ReceiverOnboarding.page.md new file mode 100644 index 00000000..242fce42 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Build/Testing-and-Environments/ReceiverOnboarding.page.md @@ -0,0 +1,80 @@ +--- +topic: receiveronboarding +--- + +## {{page-title}} + +BaRS uses TLS-MA to communicate with Receiving endpoints. Receiving endpoints need a certificate under the NHS Root CA to facilitate TLS-MA. The receiver needs to follow these steps for Integration and Production environments. + +To onboard as a receiver follow these steps: + +Step 1: Apply for your domain [apply for a new nhs.uk domain](https://digital.nhs.uk/services/networking-addressing/apply-for-an-nhs.uk-domain-for-websites-and-web-applications). You must complete Section 5: For website or application records visible on the public internet. + +Step 2: Request a certificate under the NHS Root CA. The FQDN must be an nhs.uk address. + * There are different certificate chains for INT and PROD + * [INT Certificate](https://digital.nhs.uk/services/path-to-live-environments/integration-environment#rootca-and-subca-certificates) chains (**Note:** _these may be out of date_) + * [PROD Certificate](https://digital.nhs.uk/services/path-to-live-environments/live-environment) chains (**Note:** _these may be out of date_)stered, you can then begin the process to obtain your certificate by generating a certificate request. +The fully qualified domain name (FQDN) is equal to the certificate name (CN) by convention. + +Step 3: Create a Certificate Signing Request (*.csr). This is the file you will send to us so we can generate a signed certificate for your endpoints. Create a private key; a password is optional. +``` +openssl genpkey -algorithm RSA -out private.key -aes256 +``` +Create the *.csr, use the following command:
+**Note:** _Generate the CSR with only the common name field populated, which must match the FQDN. All other fields can remain blank. The email field MUST be blank. Please note FQDNs MUST be in the .nhs.uk domain as we can only issue certificates in this domain._ +``` +openssl req -new -key private.key -out request.csr +``` + +Step 4: Send the .csr file to be signed by the NHS and get the client certificate. To do this, follow these environment specific steps: + +#### Client certificate: Integration (INT) +Step 1: Contact ITOC to make a [Combined endpoint and service registration request](https://digital.nhs.uk/services/path-to-live-environments/path-to-live-forms/combined-endpoint-and-service-registration-request) + {{render:Onboarding FORM.png}} + In the form: + * Select Create/renew a certificate only (No endpoint) + * Specify Integration environment + * FQDN must match your domain and CN on the cert e.g. '**BaRS-INT-\.\.thirdparty.nhs.uk**' + * In Additional comments/notes, state ‘BaRS’ certificate request + * Add ‘N/A’ in the Party Key field because there is no relation to SDS endpoints +Step 2: Receive certificate from ITOC +Step 3: Email with Receiver URL for BaRS/API-M to add to the Endpoint Catalogue + +#### Client certificate: Production (PROD) +Production endpoints can only be requested when Solution Assurance issue the supplier with the Technical Conformance certificate, +Step1: Send the .csr to , indicating this is for a BaRS Receiver endpoint + * Format for FQDN on PROD for: + * Supplier hosted solutions is ‘**BaRS-PROD-\.\.thirdparty.nhs.uk**’ + * This option is used for multi-tenanted solutions. + * Service Provider hosted solutions is ‘**BaRS-PROD-\.\.nhs.uk**’ + * This option is used for non multi-tenanted solutions. If multiple endpoints are needed, the ODS code can be appended with an identifier for the setting. + * It may be that the provider already has a 'nhs.uk' standard domain DNS entry. If one exists, it should be used for this new subdomain. +Step 2: Receive certificate from DIR Team +Step 3: Email with Receiver URL for BaRS/API-M to add to the Endpoint Catalogue + +Step 4: INT and PROD copy the cert text inlcuding `-----BEGIN CERTIFICATE` as the first line and `END CERTIFICATE-----` as the last. Save this text locally as a file called barsinreceiver.cer (change the name to suit). + +Step 5: Create a .pfx file so you can serve HTTPS (TLS) endpoints. You can use the command below to export a *.pfx file from the *.key file you made earlier (when you made the *.csr file) along with the *.cer file you were emailed. + +``` +openssl pkcs12 -export -out barsintreceiver.pfx -inkey barsintreceiver.key -in barsintreceiver.cer +``` + +Step 6: Create a password for your .pfx file. + +Step 7: Make configuration changes to reference the *.pfx file and password + +(C# example, Other launguages will vary but be similar) + +``` c# + +// Configure Kestrel to use the certificate +builder.WebHost.ConfigureKestrel(options => +{ + options.ListenAnyIP(8080, listenOptions => + { + listenOptions.UseHttps(certPath, certPassword); + }); +}); + +``` \ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Build/Testing-and-Environments/SenderOnboarding.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Build/Testing-and-Environments/SenderOnboarding.page.md new file mode 100644 index 00000000..b0d89593 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Build/Testing-and-Environments/SenderOnboarding.page.md @@ -0,0 +1,19 @@ +--- +topic: senderonboarding +--- + +## {{page-title}} + +API-M provides the [security model](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation/application-restricted-restful-apis-signed-jwt-authentication) for BaRS. + +To onboard as a sender follow these steps: + +Step 1: follow the NHS Developer authenitication and authorisation process [NHS Developer authentication and authorisation](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation/user-restricted-restful-apis-nhs-login-separate-authentication-and-authorisation#step-1-register-your-application-with-nhs-login) + +Step 2: trust the Certificate Authorities (CA) mentioned below. For INT this will be downloadable from http://pki.nhs.uk/int/G2/auth/NHSINTAuthG2.crt +( you can examine the .cer file if you have one ) +``` +openssl x509 -in barsintreceiver.cer -text -noout +``` + + diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Build/Testing-and-Environments/toc.yaml b/guides/Live-ImplementationGuide-BaRS/Home/Build/Testing-and-Environments/toc.yaml index 8466ef2b..f97d41f8 100644 --- a/guides/Live-ImplementationGuide-BaRS/Home/Build/Testing-and-Environments/toc.yaml +++ b/guides/Live-ImplementationGuide-BaRS/Home/Build/Testing-and-Environments/toc.yaml @@ -4,5 +4,9 @@ filename: Environments.page.md - name: Onboarding filename: Onboarding.page.md +- name: Sender Onboarding + filename: SenderOnboarding.page.md +- name: Receiver Onboarding + filename: ReceiverOnboarding.page.md - name: TKW filename: TKW.page.md From 7a40131d80d883418913eca4f2cc2c8104a51692 Mon Sep 17 00:00:00 2001 From: luci-davies Date: Tue, 21 Oct 2025 16:28:55 +0100 Subject: [PATCH 4/4] Changes made as per suggestions --- ....page.md => Connect-as-a-receiver.page.md} | 23 +++++++++++-------- ...ng.page.md => Connect-as-a-sender.page.md} | 4 ++-- .../Onboarding.page.md | 2 +- .../Build/Testing-and-Environments/toc.yaml | 10 ++++---- .../DirectoryOfServiceConfiguration.md | 0 .../Firewallexceptions.md | 0 .../Index.page.md | 0 .../Technicaldeployment.page.md | 0 .../toc.yaml | 0 9 files changed, 21 insertions(+), 18 deletions(-) rename guides/Live-ImplementationGuide-BaRS/Home/Build/Testing-and-Environments/{ReceiverOnboarding.page.md => Connect-as-a-receiver.page.md} (80%) rename guides/Live-ImplementationGuide-BaRS/Home/Build/Testing-and-Environments/{SenderOnboarding.page.md => Connect-as-a-sender.page.md} (90%) rename guides/Live-ImplementationGuide-BaRS/Home/Deploy/{Technical deployment => Technical-deployment}/DirectoryOfServiceConfiguration.md (100%) rename guides/Live-ImplementationGuide-BaRS/Home/Deploy/{Technical deployment => Technical-deployment}/Firewallexceptions.md (100%) rename guides/Live-ImplementationGuide-BaRS/Home/Deploy/{Technical deployment => Technical-deployment}/Index.page.md (100%) rename guides/Live-ImplementationGuide-BaRS/Home/Deploy/{Technical deployment => Technical-deployment}/Technicaldeployment.page.md (100%) rename guides/Live-ImplementationGuide-BaRS/Home/Deploy/{Technical deployment => Technical-deployment}/toc.yaml (100%) diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Build/Testing-and-Environments/ReceiverOnboarding.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Build/Testing-and-Environments/Connect-as-a-receiver.page.md similarity index 80% rename from guides/Live-ImplementationGuide-BaRS/Home/Build/Testing-and-Environments/ReceiverOnboarding.page.md rename to guides/Live-ImplementationGuide-BaRS/Home/Build/Testing-and-Environments/Connect-as-a-receiver.page.md index 242fce42..f4359b0c 100644 --- a/guides/Live-ImplementationGuide-BaRS/Home/Build/Testing-and-Environments/ReceiverOnboarding.page.md +++ b/guides/Live-ImplementationGuide-BaRS/Home/Build/Testing-and-Environments/Connect-as-a-receiver.page.md @@ -1,12 +1,12 @@ --- -topic: receiveronboarding +topic: Connect-as-a-receiver --- ## {{page-title}} -BaRS uses TLS-MA to communicate with Receiving endpoints. Receiving endpoints need a certificate under the NHS Root CA to facilitate TLS-MA. The receiver needs to follow these steps for Integration and Production environments. +BaRS uses TLS-MA to communicate with Receiving endpoints. Receiving endpoints need a certificate under the NHS Root CA to facilitate TLS-MA. The receiver needs to follow these steps to access Integration (INT) and Production (PROD) environments. -To onboard as a receiver follow these steps: +To connect to the BaRS proxy as a receiver follow these steps: Step 1: Apply for your domain [apply for a new nhs.uk domain](https://digital.nhs.uk/services/networking-addressing/apply-for-an-nhs.uk-domain-for-websites-and-web-applications). You must complete Section 5: For website or application records visible on the public internet. @@ -26,7 +26,7 @@ Create the *.csr, use the following command:
openssl req -new -key private.key -out request.csr ``` -Step 4: Send the .csr file to be signed by the NHS and get the client certificate. To do this, follow these environment specific steps: +Step 4: Send the .csr file to be signed by NHS England and get the client certificate. To do this, follow these environment specific steps: #### Client certificate: Integration (INT) Step 1: Contact ITOC to make a [Combined endpoint and service registration request](https://digital.nhs.uk/services/path-to-live-environments/path-to-live-forms/combined-endpoint-and-service-registration-request) @@ -41,7 +41,7 @@ Step 2: Receive certificate from ITOC Step 3: Email with Receiver URL for BaRS/API-M to add to the Endpoint Catalogue #### Client certificate: Production (PROD) -Production endpoints can only be requested when Solution Assurance issue the supplier with the Technical Conformance certificate, +**Production endpoints can only be requested when Solution Assurance issue the supplier with the Technical Conformance certificate** Step1: Send the .csr to , indicating this is for a BaRS Receiver endpoint * Format for FQDN on PROD for: * Supplier hosted solutions is ‘**BaRS-PROD-\.\.thirdparty.nhs.uk**’ @@ -51,18 +51,20 @@ Step1: Send the .csr to , indicating this is for a BaRS Receiver en * It may be that the provider already has a 'nhs.uk' standard domain DNS entry. If one exists, it should be used for this new subdomain. Step 2: Receive certificate from DIR Team Step 3: Email with Receiver URL for BaRS/API-M to add to the Endpoint Catalogue +Step 4: Make changes to your [firewall exceptions](https://simplifier.net/guide/nhsbookingandreferralstandard/Home/Deploy/Technical-deployment\Firewallexceptions) to receive messages from the BaRS proxy. -Step 4: INT and PROD copy the cert text inlcuding `-----BEGIN CERTIFICATE` as the first line and `END CERTIFICATE-----` as the last. Save this text locally as a file called barsinreceiver.cer (change the name to suit). +#### Installing and configuring your application to use the certificate +Step 1: INT and PROD copy the cert text inlcuding `-----BEGIN CERTIFICATE` as the first line and `END CERTIFICATE-----` as the last. Save this text locally as a file called barsinreceiver.cer (change the name to suit). -Step 5: Create a .pfx file so you can serve HTTPS (TLS) endpoints. You can use the command below to export a *.pfx file from the *.key file you made earlier (when you made the *.csr file) along with the *.cer file you were emailed. +Step 2: Create a .pfx file so you can serve HTTPS (TLS) endpoints. You can use the command below to export a *.pfx file from the *.key file you made earlier (when you made the *.csr file) along with the *.cer file you were emailed. ``` openssl pkcs12 -export -out barsintreceiver.pfx -inkey barsintreceiver.key -in barsintreceiver.cer ``` -Step 6: Create a password for your .pfx file. +Step 3: Create a password for your .pfx file. -Step 7: Make configuration changes to reference the *.pfx file and password +Step 4: Make configuration changes to reference the *.pfx file and password (C# example, Other launguages will vary but be similar) @@ -77,4 +79,5 @@ builder.WebHost.ConfigureKestrel(options => }); }); -``` \ No newline at end of file +``` + diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Build/Testing-and-Environments/SenderOnboarding.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Build/Testing-and-Environments/Connect-as-a-sender.page.md similarity index 90% rename from guides/Live-ImplementationGuide-BaRS/Home/Build/Testing-and-Environments/SenderOnboarding.page.md rename to guides/Live-ImplementationGuide-BaRS/Home/Build/Testing-and-Environments/Connect-as-a-sender.page.md index b0d89593..f21430ca 100644 --- a/guides/Live-ImplementationGuide-BaRS/Home/Build/Testing-and-Environments/SenderOnboarding.page.md +++ b/guides/Live-ImplementationGuide-BaRS/Home/Build/Testing-and-Environments/Connect-as-a-sender.page.md @@ -1,12 +1,12 @@ --- -topic: senderonboarding +topic: connect-as-a-sender --- ## {{page-title}} API-M provides the [security model](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation/application-restricted-restful-apis-signed-jwt-authentication) for BaRS. -To onboard as a sender follow these steps: +To connect to the BaRS proxy as a sender follow these steps: Step 1: follow the NHS Developer authenitication and authorisation process [NHS Developer authentication and authorisation](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation/user-restricted-restful-apis-nhs-login-separate-authentication-and-authorisation#step-1-register-your-application-with-nhs-login) diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Build/Testing-and-Environments/Onboarding.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Build/Testing-and-Environments/Onboarding.page.md index 6c503222..bb63ab87 100644 --- a/guides/Live-ImplementationGuide-BaRS/Home/Build/Testing-and-Environments/Onboarding.page.md +++ b/guides/Live-ImplementationGuide-BaRS/Home/Build/Testing-and-Environments/Onboarding.page.md @@ -4,7 +4,7 @@ topic: onboarding ## {{page-title}} -In each BaRS workflow there are two roles: Sender and Receiver. In applications with response workflows, both parties act as a Sender and a Receiver, and will need to follow the instructions to onboard as both. +In each BaRS workflow there are two roles: Sender and Receiver. In applications with response workflows, both parties act as a Sender and a Receiver, and will need to follow the instructions to connect to environments as both. The Sender obtains a token from the API-M platform to make requests of the BaRS API Proxy, which brokers the request through the Receiver, secured via TLS-MA (Transport Layer Security-Mutual Authentication). diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Build/Testing-and-Environments/toc.yaml b/guides/Live-ImplementationGuide-BaRS/Home/Build/Testing-and-Environments/toc.yaml index f97d41f8..f9deafc2 100644 --- a/guides/Live-ImplementationGuide-BaRS/Home/Build/Testing-and-Environments/toc.yaml +++ b/guides/Live-ImplementationGuide-BaRS/Home/Build/Testing-and-Environments/toc.yaml @@ -2,11 +2,11 @@ filename: Index.page.md - name: Environments filename: Environments.page.md -- name: Onboarding +- name: Connecting to environments filename: Onboarding.page.md -- name: Sender Onboarding - filename: SenderOnboarding.page.md -- name: Receiver Onboarding - filename: ReceiverOnboarding.page.md +- name: Connect as a Sender + filename: Connect-as-a-sender.page.md +- name: Connect as a Receiver + filename: Connect-as-a-receiver.page.md - name: TKW filename: TKW.page.md diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Deploy/Technical deployment/DirectoryOfServiceConfiguration.md b/guides/Live-ImplementationGuide-BaRS/Home/Deploy/Technical-deployment/DirectoryOfServiceConfiguration.md similarity index 100% rename from guides/Live-ImplementationGuide-BaRS/Home/Deploy/Technical deployment/DirectoryOfServiceConfiguration.md rename to guides/Live-ImplementationGuide-BaRS/Home/Deploy/Technical-deployment/DirectoryOfServiceConfiguration.md diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Deploy/Technical deployment/Firewallexceptions.md b/guides/Live-ImplementationGuide-BaRS/Home/Deploy/Technical-deployment/Firewallexceptions.md similarity index 100% rename from guides/Live-ImplementationGuide-BaRS/Home/Deploy/Technical deployment/Firewallexceptions.md rename to guides/Live-ImplementationGuide-BaRS/Home/Deploy/Technical-deployment/Firewallexceptions.md diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Deploy/Technical deployment/Index.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Deploy/Technical-deployment/Index.page.md similarity index 100% rename from guides/Live-ImplementationGuide-BaRS/Home/Deploy/Technical deployment/Index.page.md rename to guides/Live-ImplementationGuide-BaRS/Home/Deploy/Technical-deployment/Index.page.md diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Deploy/Technical deployment/Technicaldeployment.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Deploy/Technical-deployment/Technicaldeployment.page.md similarity index 100% rename from guides/Live-ImplementationGuide-BaRS/Home/Deploy/Technical deployment/Technicaldeployment.page.md rename to guides/Live-ImplementationGuide-BaRS/Home/Deploy/Technical-deployment/Technicaldeployment.page.md diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Deploy/Technical deployment/toc.yaml b/guides/Live-ImplementationGuide-BaRS/Home/Deploy/Technical-deployment/toc.yaml similarity index 100% rename from guides/Live-ImplementationGuide-BaRS/Home/Deploy/Technical deployment/toc.yaml rename to guides/Live-ImplementationGuide-BaRS/Home/Deploy/Technical-deployment/toc.yaml