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 PKBfrom EMIS orfrom SystmOne.
Additionally, PKB already allows patients to open their PKB medical record in the NHS App 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.
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.
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.
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.
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:
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.