NHS Booking and Referral Standard

Environments

The principle environment for development and testing is the INT (integration) environment. This is a like-live environment, harnessing full security and functionality that can expect to be encountered in Production. In addition, the BaRS API specification links to the Sandbox environment, which is capable of demonstrating the key functionality but without the security overhead.

Path-to-Live has full details of all available testing environments and the functionality they offer.

Onboarding

API-M provides the security model 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.

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) connectivity.

Sender

• Follow the steps here to get set up

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 ( 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

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 chains (Note: these may be out of date)
  • Prod Certificate 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.

You can apply for your domain here, ensuring that you complete Section 5: For website or application records visible on the public internet.

Once you have your domain registered, you can then begin the process to obtain your certificate by generating a certificate request.

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.

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.

openssl genpkey -algorithm RSA -out private.key -aes256

Then, to 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.

Integration (INT)

• Request a ‘certificate only’ from ITOC
  • 
  • Certificate Only (No endpoint)
  • Integration environment
  • FQDN must match your domain and CN on the cert e.g. 'BaRS-INT-<ODS Code>.<Supplier name>.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 england.bookingandreferralstandard@nhs.net 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 dir@nhs.net, indicating this is for a BaRS Receiver endpoint
  • Format for FQDN on PROD for:
    • Supplier hosted solutions is ‘BaRS-PROD-<ODS Code>.<Supplier name>.thirdparty.nhs.uk’
      • This option is used for multi-tenanted solutions.
    • Service Provider hosted solutions is ‘BaRS-PROD-<ODS Code>.<Provider name>.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 england.bookingandreferralstandard@nhs.net 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.

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)

// Configure Kestrel to use the certificate
builder.WebHost.ConfigureKestrel(options =>
{
    options.ListenAnyIP(8080, listenOptions =>
    {
        listenOptions.UseHttps(certPath, certPassword);
    });
});

TKW

What is TKW?

TKW - Toolkit Workbench - is a tool to assist development and assurance of supplier solutions to meet BaRS (Booking and Referral Standard) requirements.

The tool supports testing of key high-level workflows e.g. a booking routine, including some of asynchronous ones, but is also capable of inspecting low level technical requirements. It reports the output in Validation Reports which clearly indicates to the reader where and why a test has failed. In addition, it supports consistent error states which are often difficult to create but required for development and assurance.

The BaRS TKW tooling is embedded into the INT environment, encompassing all the same end-to-end BaRS infrastructure that is mirrored in Production, rather than being downloaded and used in isolation. This ensures the same steps to deploy solutions to Production are followed during deployment to INT, and allowing testing of requests/responses to occur under Production-like conditions. Similarly, we're able to incorporate other key components, similar to those used in Production workflows, such as the UserTest Directory of Services (DoS). In the current BaRS Applications, the TKW tool relies on values in the UserTest DoS to elicit particular behavioural responses. The Sender will populate what are termed 'sentinel' values, such as the NHSD-Target-Identifier, with a particular value and TKW will respond with a certain Capability Statement, MessageDefinition etc. (See the 'Scenarios' section for detail).

It is important for Senders to remember TKW is a stateless receiver and is not checking the relationship between requests (except in a handful of stateful scenarios - outlined below). This is important when developing workflows such as linking a booking and referral and transactional Integrity.

Using TKW Portal

Suppliers must register a Portal account to start working with TKW but Senders and Receivers will use the tool in slightly different ways due to the nature of the requests/responses they require. Senders, needing somewhere to send requests and Receivers needing something to make requests of their solution.

During the registration process, the 'Target Identifier' and 'ODS Code' values are important to ensure requests are sent and received appropriately. As a Sender (to TKW), the HTTP Header NHSD-End-User-Organisation must include the ODS Code they registered with because TKW will collate requests based on this value. When reports are downloaded and viewed, only requests with that specific ODS Code in the header will be visible. As a Receiver, once logged into the portal and selecting the request(s) TKW is required to make of your endpoint, they will be directed to the Target Identifier registered against and, equally, downloaded reports will only relate to that specific value.

• Navigate to https://maitportal.testlab.nhs.uk/
• Click Register and complete the form below

• Email bookingandreferralstandard@nhs.net for a Target Identifier (this represents you on the Endpoint Catalogue)
• MAIT Team will need enable your account, email bookingandreferralstandard@nhs.net to advise this has been created
• Verify the account via email
• Configure Multi-Factor Authentication
• Access Portal Home screen

Sender

Once registered, requests can be made of TKW in any given workflow e.g. booking, validation etc. and the tool will record and provide downloadable validation reports for each request made.

The Scenarios (including Stateful Scenarios) outlined below highlight how to elicit particular behaviour required, note the specific sentinel values for NHSD-Target-Identifier and patient NHS Number. As a Sender, the various requests can be made and TKW will repond accoridngly.

NB: It is important for Senders to remember TKW is a stateless receiver and is not checking the relationship between requests (except in a handful of stateful scenarios - outlined below). This is important when developing workflows such as linking a booking and referral and transactional Integrity.

Receiver

A receiver can access the portal (once registered) to send either individual tests or an entire suite of tests to themselves. From the top menu bar, click 'Receive Requests' and the screen below will present -

The receiver selects the request they wish the TKW to make of their endpoint and clicks 'Execute Selected Tests' (bottom of the page). TKW will indicate when the requests have been processed.

Once all requested tests have been completed, the Validation Report can be downloaded -

• from the top menu, select 'Download Reports'
• then click on the button 'Download Reports' (this packages the report and makes it available to download locally)
• from the top me, select 'Receiver Reports'
• click on the hyperlink of the required report to download locally (.zip format)

Scenarios

The TKW will respond to the scenarios outlined below. It does not hold the state of any prior request (unless specified in the Stateful scenarios) and the specific 'sentinel' values (in bold) must be used to elicit the required response where stated.

NB: where 'Any' NHSD-Target-Identifier is specified, only those highlighted in "UserTest DoS Services" table below will work for TKW.

NB: the endpoints for TKW are case sensitive eg use the following /metadata /MessageDefinition /$process-message /Slot /Appointment /ServiceRequest

Headers

The follow is a list of headers needed for the requests, these follow the pattern needed by BARS as follows Headers

        bash
        curl --location 'https://int.api.service.nhs.uk/booking-and-referral/FHIR/R4/metadata' \
        --header 'X-Request-Id: 99672436-ae1e-42e4-81a6-5a298563ccfa' \
        --header 'X-Correlation-Id: f44f6c3c-fdd5-4c8c-a091-d825eca1d763' \
        --header 'NHSD-Target-Identifier: eyJzeXN0ZW0iOiJodHRwczovL2ZoaXIubmhzLnVrL0lkL2Rvcy1zZXJ2aWNlLWlkIiwidmFsdWUiOiIyMDAwMDcyNDg5In0=' \
        --header 'NHSD-End-User-Organisation: ewogICJyZXNvdXJjZVR5cGUiOiAiT3JnYW5pemF0aW9uIiwKICAiaWRlbnRpZmllciI6IFsKICAgIHsKICAgICAgInZhbHVlIjogIldBU1AiLAogICAgICAic3lzdGVtIjogImh0dHBzOi8vZmhpci5uaHMudWsvSWQvb2RzLW9yZ2FuaXphdGlvbi1jb2RlIgogICAgfQogIF0sCiAgIm5hbWUiOiAiTXkgc2VydmljZSBwcm92aWRlciBuYW1lIgp9' \
        --header 'Authorization: Bearer yourBearerToken'
    

Capability

MessageDef

Booking

Referral

Validation

Response

UserTest DoS Services

The sentinel values linked to UserTest DoS services can be found by searching with the following criteria.

INT Test Patient (traceable on SPINE)

The patient.Identifier sentinel values used to trigger Scenarios in TKW can be found on the INT Spine. The full patient details are outlined below.

Stateful Scenarios

TKW supports a limited stateful response for 111 to ED requests. This is a simulation of the real-world receiving end-point and mimics the expected behaviour of a Reciever solution.

This stateful behaviour is only demonstrated for a specific patient (NHS Number 9707606312) and per NHSD-End-User-Organisation - i.e. state will be persisted only between requests made by the same End User Organisation.

Note The stateful server will reset each night which will return all users back to the initial state.

State Transition Table indicating the responses the stateful TKW scenarios will support and the expected responses-