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