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.

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 the 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. TKW is deployed to the INT environment and, therefore, requests/responses will occur under Production like conditions.

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.

• 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 sharif.ullah1@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 this table will work for TKW. Any of the NHSD-Target-Identifiers configured for TKW. 

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-

Onboarding

API-M provide the security model for BaRS.

There are two roles; Sender and Receiver, and most BaRS Applications will require a solution to support both, despite being predominantly one or the other, because of the response workflow steps. In responses flows, the original Sender becomes and Receiver and 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, secure via TLS-MA (Transport Layer Security-Mutual Authentication).

Sender

Prerequiste steps to follow -

• Create Developer account
• Sign in, create a team by selecting "My teams", and then "+ New Team":

• Assign members to your Team
• Create an App
  • Owner of the App should be the Team created above
  • You will need a callback URL (bottom of page)
  • Enable or request the API's you wish to use for your application
    • "Booking and Referral FHIR API (Sandbox Environment)" - for Sandbox
    • "Booking and Referral FHIR API (Integration Testing Environment)" - for INT
  • Generate an API Key for your application
• Define your Key Identifier (KID) to be used within your JWTs
  • KID Naming Convention (Development Systems) - <Supplier>-<Environment>-<rotation> i.e. MySupplier-INT-1
  • KID Naming Convention (Provider Systems) - <Provider>-<Environment>-<rotation> i.e. Provider-INT-1
• Generate a key pair (.pem)
  • Windows based apps
  • Alternatively, this website can also generate Key Pairs
• Provide details to register your key
  • For INT : Register Public key with API Management
    • Email - api.management@nhs.net with:
      • Environment - Sandbox, Development, Integration Test or Production
      • App ID and Name from the portal
      • Public key
        • As an attachment, PEM-Encoded
      • The KID you have defined for this public key
      • APIs you want to use
  • For Production (each provider needs their own key).
    • Email -
      • Specify Live
      • App ID and Name from the portal for both Production and the INT Suppliers Development environment.
      • Public key for the providers Production instance.
        • As an attachment, PEM-Encoded.
      • The KID defined for this public key.
      • The APIs you want to use.
• Generate a signed JWT using your private key

  • The header:

    • alg: The algorithm used
    • typ: "JWT" in this instance
    • kid: Your KID as provided to API Management above
    • example:

            {
                "alg":"RS512"
                "typ":"JWT"
                "kid":"BaRS-Sandbox-1"
            }
    
    

  • The payload:

    • iss: The API Key you generated in the portal
    • sub: The API Key you generated in the portal
    • aud: The full URL of the endpoint you are calling (example: https://sandbox.api.service.nhs.uk/oauth2/token )
    • jti: UUID/GUID, different for each request
    • exp: Epoch time, to be no more than 5 minutes in the future, indicating when your token will expire
    • example:

            {
                "iss":"IwrOdg62kM9LN1oFhlHAhWPHAhWPbV62",
                "sub":"IwrOdg62kM9LN1oFhlHAhWPHAhWPbV62",
                "kid":"BaRS-Sandbox-1",
                "aud":"https://sandbox.api.service.nhs.uk/oauth2/token",
                "jti":"b7ae4c12-3c04-465a-8877-c2e80f0126a3"
                "exp":"1635263528"
            }
    
    

  • Post your JWT to the OAuth endpoint to receive a Token

    • Note: A token is not required for the Sandbox environment

    • Your request body should be x-www-form-urlencoded with the following fields

      • grant_typegrant_type = "client_credentials"
      • client_assertion_type = "urn:ietf:params:oauth:client-assertion-type:jwt-bearer"
      • client_assertion = <Your signed JWT>
      • example:

          curl --location --request POST 'https://sandbox.api.service.nhs.uk/oauth2/token' \
          --header 'Content-Type: application/x-www-form-urlencoded' \
          --data-urlencode 'grant_type=client_credentials' \
          --data-urlencode 'client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer' \
          --data-urlencode 'client_assertion=eyJ0eXAiOiJKV1QiLCJraWQiOiJCYVJTLVNhbmRib3gtMSIsImFsZyI6IlJTNTEyIn0.
          eyJpc3MiOiJJd3JPZGc2MmtNOUxOMW9GaGw4UnlVUmJIQWhXUFY2MiIsInN1YiI6Ikl3ck9kZzYya005TE4xb0ZobDhSeVVSYkhBaFdQVjYyIiwia2lkIjoiQmFSUy1TYW5kYm94LTEiLCJhdWQiOiJodHRwczovL3NhbmRib3guYXBpLnNlcnZpY2UubmhzLnVrL29hdXRoMi90b2tlbiIsImp0aSI6IlQtWjdhTm1UODUybE1uVGtZb1NaRiIsImlhdCI6MTYzNTI2MjI2MiwibmJmIjoxNjM1MjYyMjYyLCJleHAiOjE2MzUyNjI1NjZ9.aUQSqvkzjAMRR21lNiE6YnksynPWx9wkXdEFJZ_muzGfeyuS3ooh-uXlOccQFSDS790Wrne49vMsf72NILK3iDjWyH2z8D8R_B_xYy2e3ZOktqQFNx5vZ0svC-_v1ranJKJJU8NiQog7JvRtXNwKcdExpge2bkhV2JN3bQtzPY0F7CxPohILmCIUvi3yEyr-nm3kxdB8LkifQAz132qpuO_1iENGmbqUgASYBZMTQIdD4aO8Vv9sJ9rvyIQyniw_DeY6SEMx4CHDiEb0NWmcOmpdBS1DDkuMiUohSpz8OXEYR1cZcL27dyibDJBY57FGCMBn1AVb43olYSumOIwg'
      
      

  • The expected success response from the Post should be a status 200 with a 3 field JSON response:

    • access_token: Your access token
    • expires_in: When it expires
    • token_type: "Bearer"
    • issued_at: Time issued
    • example:

            {
                'access_token': 'Sr5PGv19wTEHJdDr2wx2f7IGd0cw',
                'expires_in': '599',
                'token_type': 'Bearer'
                'issued_at': '1675784384503'
            }
    
    

  • A failure response will have a response code appropriate for the reason and the following 3 fields:

    • error: The error thrown
    • error_description: Diagnostics text to tell you why the error was thrown
    • message_id: A unique id for the interaction
    • example:

            {
                "error": "public_key error",
                "error_description": "You need to register a public key to use this authentication method - please contact support to configure",
                "message_id": "rrt-8923968319386160140-b-geu2-23765-558685-1"
            }
    
    

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
  • Prod Certificate chains
• 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, 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 public internet

Once you have 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

At this point you should have a .key and a .csr files. 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 below sections for each environment under 'Configuring endpoints for different environments'

• If your client certificate will be implemented in any PTL environment then you should send the .csr file to itoc.supportdesk@nhs.net
• If your client certificate will be implemented in the PROD environment then the .csr file needs to be sent to the DIR team at dir@nhs.net and they will issue the certificate after validating your request with the Live Services Pipeline at liveservices.gate@nhs.net

Integration (INT)

• Request a ‘certificate only’ from ITOC
  • 
  • Certificate Only (No endpoint)
  • Integration environment
  • Format for development systems FQDN on INT is ‘BaRS-INT-<ODS Code>.<Supplier name>.thirdparty.nhs.uk’
  • Format for provider systems FQDN on INT is ‘BaRS-INT-<ODS Code>.<Provider name>.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
  • In the .csr, the ‘email’ field must be blank
• Receive certificate from ITOC
• Email dnsteam@nhs.net with FQDN and public facing IP to register DNS
• Email bookingandreferralstandard@nhs.net with Receiver URL for BaRS/API-M to add to the Endpoint Catalogue

Production (Prod)

• Once Solution Assurance issue the supplier with the Technical Conformance certificate Production endpoints can be requested
• Sends .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 dnsteam@nhs.net with FQDN and public facing IP to register DNS
• Email 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 (for both INT and Prod) will originate from 34.89.0.111 & 34.89.69.6