Security and authorisation when launching using Core Auth

Dunmail -

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.

Screenshot 2023-07-12 at 14.44.36.png

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 `|<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.

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.


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:

Parameter Source
patient launch request
birthdate launch request
location launch request 
serviceId ODS-specific configuration maintained by Black Pear
access_token Issued by


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 ""
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.

Have more questions? Submit a request


Article is closed for comments.
Powered by Zendesk