Overview
It is a common request for an external system to be able to launch PKB for a given user (whether patient or clinician), without the user needing to manually re-enter their PKB credentials.
PKB already supports some externally defined workflows for such behaviour. For example, GPs can click through to PKB from EMIS or from SystmOne.
Additionally, PKB already allows patients to open their PKB medical record using NHS login.
This page outlines implementation details of two additional SSO mechanisms:
NHS login SSO solution. This mechanism will allow your NHS login-authenticated users to launch PKB without entering additional credentials, and likewise for PKB's NHS login-authenticated users to launch your external system without entering additional credentials.
PKB's One Time Password (OTP). This mechanism allows users of your external system to link their PKB account such that you are able to launch them into PKB on request by retrieving an OTP from our Custom REST API.
NHS login solution
PKB is working on implementing the NHS SSO model.
https://nhsconnect.github.io/nhslogin/single-sign-on/
It is hoped that this design will allow external systems to launch into PKB, and to be launched from PKB.
NHS login with assertedLoginIdentity
We also accept asserted_login_identity tokens as means of authenticating a user. To use this method, the following parameters need to be added to the URL:
assertedLoginIdentity: containing the login identity token.prompt(optional): optionally set to force a login prompt from the user.
The user will be automatically logged in via NHS using the token provided.
OTP solution
Note: these examples are written for http://sandbox.patientsknowbest.com ; replace the URL as needed if you are connecting to a different environment.
OAuth 2.0 allows a user to authenticate against the PKB REST API. The steps below indicate how an external system would make use of the REST API to launch a user into the PKB GUI without that user manually re-entering their credentials (after initial pairing).
The external system, or a proxy acting on its behalf, needs to authenticate against PKB on behalf of the user it knows to be currently logged in, and then launch PKB in the correct context.
Initial pairing
A PKB user initiates a workflow on the external system (e.g. clicks a link) that indicates their desire to pair their PKB account with the external system.
The external system should then follow the standardAuthorization Code Grant workflow, to obtain an access token and refresh token from PKB, which will be associated with the user who just authenticated.
The external system then stores both of these tokens in a local database, along with whatever identifier the external system uses to identify the currently logged in user.
Ongoing usage
Obtain a One Time Password for the user
Subsequently, when the user wishes to access the PKB web application, they will initiate this workflow in the external system (e.g. clicks a link).
The external system looks up the access token associated with this user in their local database.
It is likely that the access token will have expired since it was generated; if so, the external system must use the refresh token to get a new access and refresh token pair.
With a live access token now available, the external system uses the One Time Password (OTP) API call to request a single-use token; this token is needed in the next step to launch the browser.
Launch the browser
Now that the external system has an OTP for the user, they can generate a URL which will log them in to PKB.
The structure of the URL is a static base component, followed by the OTP token as a URL parameter.
An example of a complete URL is shown below.
https://sandbox.patientsknowbest.com/otp.action?otpToken=gnUF6vXCWhZ9QgD4-7s6TE1bSiqfUniw
The OTP can only be used once and will expire after 60 seconds if not used.
After using the OTP to launch the browser, it will be invalidated by PKB and cannot be used again.
The user is now logged in to the PKB GUI. Normal rules regarding session expiry will apply - if the configured period of inactivity elapses, the user will be logged out of the PKB GUI. They must then trigger the relevant workflow in the external system to begin a new exchange, during which a new OTP is generated.
Optional redirection
Additionally, an optional redirection URL can also be provided (using the redirect_uri parameter) to control where the user lands in PKB once they have been logged in to the system.
The redirect_uri parameter must be URL encoded; and only relative URLs will be accepted.
If you wish to link to a specific patient's context then you need to provide one of the following. Either:
National identifier
Email address
To launch a specific patient's record based on a national identifier (e.g. NHS number) then you need to provide two URL parameters:
pnidcc. This must be set to thecountry code for the corresponding national identifier. For example, GB-ENG will allow you to provide an NHS number.
pnid. This is the actual value of the national identifier.
An example URL is given below which will login the clinician whose OTP token is provided, and then redirect them to the summary page for the patient whose NHS number is 9999999999.
https://sandbox.patientsknowbest.com/otp.action?otpToken=gnUF6vXCWhZ9QgD4-7s6TE1bSiqfUniw&redirect_uri=%2Fauth%2FpatientSummary.action%3Ftab%3DpatientSummary%26pnidcc%3DGB-ENG%26pnid%3D9999999999
To launch a specific patient's record based on an email address then you need to provide only one URL parameter:
contextUserEmail. This must be set to the email address of the patient.
An example URL is given below which will login the clinician whose OTP token is provided, and then redirect them to the summary page for the patient whose email address is patient@example.com.
https://sandbox.patientsknowbest.com/otp.action?otpToken=gnUF6vXCWhZ9QgD4-7s6TE1bSiqfUniw&redirect_uri=%2Fauth%2FpatientSummary.action%3Ftab%3DpatientSummary%26contextUserEmail%3Dpatient@example.com
Prevent patient record switching
If an organisation decides to prevent patient switching, professionals using our OTP solution to log in will not be able to navigate away from the patient record that they have launched, or view another patient’s record for the duration of the session. The professional must open each patient’s record in their local system in order to open their PKB record.
To prevent patient switching, an organisation will add an optional parameter in the redirection URL when implementing SSO:
lockPatient. When this URL parameter is set to true, the professional will not see links to the patient search page, to log out and to the help page. This parameter will be propagated to any pages opened from the patient record, e.g. if an image is opened in a new tab.
https://sandbox.patientsknowbest.com/otp.action?otpToken=gnUF6vXCWhZ9QgD4-7s6TE1bSiqfUniw&redirect_uri=%2Fauth%2FpatientSummary.action%3Ftab%3DpatientSummary%26contextUserEmail%3Dpatient@example.com%2FlockPatient=true
Once the lockPatient parameter is set to true, it will remain set for the duration of the session.
Organisations may prefer to embed PKB in an iframe in their local system when preventing patient record switching.
Data availability check
For some use cases it can be helpful to indicate to the user of the external system whether any data exists in PKB for the patient in context which the user of the external system is unlikely to have seen in their own systems, e.g. data from other organisations.
The dataFromOtherOrg REST API call can be used to return a simple boolean for this purpose, which you might like to use to e.g. toggle a visual data availability indicator in your external system.
PKB customer sites:deploy |developer |information governance |procurement |manual
©Patients Know Best, Ltd. Registered in England and Wales Number: 6517382. VAT Number: GB 944 9739 67.
This API specification and design is licensed under aCreative Commons Attribution 4.0 International License.