Single sign-on (SSO)
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, and patients can open their PKB medical record in the NHS App using NHS Login.
This page outlines how you can build similar functionality from your own external system. 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.
Note: these examples are written for sandbox.patientsknowbest.com; replace the URL as needed if you are connecting to a different environment.
OAuth 2.0 based solution
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).
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 standard Authorization 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.
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.
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.
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:
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 the country 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.
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 firstname.lastname@example.org.
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.