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.

Launch request

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.

Verification

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.

TLS

The launch request is encrypted using TLS so that we can have confidence that the information has not been manipulated in transit.

Issuer

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.

Digital signature

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.

Timestamps

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.

Response

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.

Parameters

The contextual launch link includes parameters derived as follows:

Parameter	Source
patient	launch request
birthdate	launch request
location	launch request
serviceId	ODS-specific configuration maintained by Black Pear
access_token	Issued by https://auth.core.blackpear.com

 

Access token

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:

Field	Source
requesting_organization	launch request
requesting_user	launch request
requesting_user_name	launch request
requesting_user_role	launch request
requesting_system	launch request
reason_for_request	"directcare"
requested_scope	"patient/*.read"
sub	launch request
iat	generated
iss	"https://auth.core.blackpear.com"
aud	ODS-specific configuration maintained by Black Pear
nbf	generated
exp	generated
jti	launch request

 

Vulnerability assessment

Prior to deployment, the Launch Service will be independently assessed by WMAS Information Security and Assurance Service.