How does it work?
An authenticated and authorised user of a third party application requests to open a Black Pear app in the context of a specific patient, for example by clicking a button.
The third party application sends a message to a Launch endpoint provided by Black Pear. This redirects the request to Black Pear Core.
Authorisation and subsequent access to Black Pear systems is dependent on trusting that the third party application provides reliable authentication and authorisation AND that this information can be securely shared with Black Pear.
The third party makes a POST request to the launch endpoint (`<Core Auth URL>/launch/v1`) with an `application/x-www-form-urlencoded` payload containing the following fields:
- client_assertion - The generated client assertion.
- subject_token - The generated subject token.
- patient - the identifier of the patient, as `https://fhir.nhs.uk/Id/nhs-number|<NHS Number>`
- birthdate - the birthdate of the patient, as a FHIR date
The client_assertion and subject_token are JWTs (JSON Web Tokens) as described in API access with auto-enrolment.
The launch request is verified before a launch url is issued.
IP address check
The IP address is checked to confirm that the request was received from the HSCN Secure Boundary or the IP address of a recognised NHS organisation. This provides reasonable confidence that the request originated from within a recognised NHS organisation. Whilst sender IP addresses could be spoofed, any response would be sent to the spoofed IP address.
The launch request is encrypted using TLS so that we can have confidence that the information has not been manipulated in transit.
The iss (Issuer) claim for both client_assertion and subject_token are checked against a preconfigured list, proving that the JWT was issued by a third party trusted by Black Pear.
The digital signature of the JWT for both client_assertion and subject_token are checked, proving that the request originated within the third party system because it is digitally signed using a secret known only to the third party. We can therefore have confidence in the information contained within the request.
The nbf (Not Before) and exp (Expiration Time) claims for both client_assertion and subject_token are verified against the current time so that we can have some confidence that the request has not been replayed.
If the launch request is verified, Black Pear responds to the message with a 302 redirect containing a Location header referencing a contextual launch link including SSO token.
The contextual launch link includes parameters derived as follows:
|serviceId||ODS-specific configuration maintained by Black Pear|
|access_token||Issued by https://auth.core.blackpear.com|
Tokens extend the NHS SSP Access Token format, adding requesting_user_name, requesting_user_role claims to support UI and RBAC respectively.
The access token includes fields derived as follows:
|aud||ODS-specific configuration maintained by Black Pear|
Prior to deployment, the Launch Service will be independently assessed by WMAS Information Security and Assurance Service.