NHS login is a new way for people to prove who they are online, so they can access health and care websites or apps safely and securely.
By integrating NHS login to your website or app you can offer users self-service access. You can also choose the level and combination of verification and authentication required for user access.
NHS login is based on OpenID Connect (OIDC), which is an open standard. You can find out more about our use of OIDC by reading the external interface specification (EIS).
The goal of the OIDC authorization code flow is for the relying party (your service) to obtain an ID Token from the OIDC provider (NHS login). The ID Token contains identifying information about the user (claims), such as family name, date of birth, and NHS number. Further claims can be obtained via the userinfo endpoint. The claims returned are based on the scopes specified in the original auth request - see table 11 of the EIS for more information. The ID Token also contains information about authentication mechanisms used and the level to which a user’s identity has been verified - these are called vectors of trust, see the EIS for more information.
The first step involves the client sending a request to NHS login with the desired parameters (example included here). These include your identifying information, such as client_id, and scopes, which will ultimately determine the returned claims.
NHS login will return an authorization code, which you then use to obtain the ID Token. This is done by making a request to the NHS login token endpoint. The token endpoint requires authentication via private_key_jwt method. The returned ID Token must be validated before it can be used within your service.
We have a stub and a sandpit that development teams can use to familiarise themselves with NHS login.
We have developed a lightweight stub that is a representation of our OIDC endpoints. You can find out more about the stub and access it here: https://stub.signin.nhs.uk/client. The stub is entirely self-service and requires no registration.
Our sandpit is a deployment of much of the production code, with some elements of the registration process removed e.g. matching to NHS number and checking ID documents.
We’ll need to setup your service on NHS login sandpit. Please provide the below information to [email protected]
Required information:
-
A friendly name of your service e.g. what the public know you as
-
Your redirect_uri that we’ll return traffic to
-
Your public key for validating signed JWTs - see below for guidance on generating this
We aim to process these requests within 24 hours.
You will need to add an OIDC Relying Party library to your service. OpenID certified examples can be found here: https://openid.net/developers/certified/
We have provided links to a couple of example repos at the bottom of this file. We aim to add more client examples over the coming months. If you have one to add, please raise an issue or PR.
Depending on the library you pick you’ll either need:
-
the configuration endpoint: https://auth.sandpit.signin.nhs.uk/.well-known/openid-configuration
-
or the specific endpoints, which can be found at the configuration endpoint
Before testing the registration flow you should ensure a login flow can be completed. This involves all of the interaction points, such as the token and userinfo endpoints.
There are a number of users already configured that you can use to test the login flow. We'll send you the test pack when we configure your client.
We currently have two methods to complete registration:
- Existing GP Online details
- Online ID check with video selfie
We do not support testing of GP Online method in the sandpit, but you can test the online ID checking process.
When registering a new user you will need to provide a unique email address (using the + trick in emails can help if you want to test a number of times). You can reuse your mobile number for multiple users.
Do not use any other personal information when completing registration. This includes NHS number and ID photo - take a picture of anything you like, within reason!
We don’t tend to approve new registrations in this environment. If you need us to do this please get in touch via slack - see below for joining info.
IM1 Suppliers have the option to test either the GP online or Prove your identity journey in the Integration Environment.
- NHS login provide a set of patient records that exist on the Spine Integration Environment which IM1 suppliers can use
- IM1 suppliers should create new records in their local GP system based on the patient details provided by NHS login
- IM1 suppliers should then create linkage key, account ID and ODS code details against the records created in the local GP system. These details should then be shared with NHS login
- IM1 suppliers should also create new NHS login accounts by registering with an email and password
- NHS login will update the linkage key, account ID, ODS code and IM1 token in the NAM Stub
- IM1 supplier should be able to login successfully and proceed through either the GP Online or Prove your identity journey.
- Once submitted suppliers should notify NHS login to approve the requests
- IM1 supplier should be able to login successfully and be redirect to respected service with patient record which exists in the local GP system
Non-IM1 suppliers can choose to use the basic patient records provided to proceed through the Prove your identity journey. Non-IM1 suppliers now also have the abiliy to test the GP online journey by using details from the NAM Stub.
- NHS login provide a set of patient records that exist in the NAM Stub, the details include Linkage Key, account ID and ODS code
- Non-IM1 suppliers can create new NHS login accounts and proceed through the GP Online Journey by providing valid details from the NAM Stub
- NHS login accounts verified against the NAM Stub are successfully redirected to the respected service
Please get in touch if you'd like to add FIDO UAF (TouchID etc.) to your app.
We have a public slack where you can contact us for support.
You will need to provide a public key when registering your service. This is required for the authentication mechanism on the token endpoint. The steps below explain how to generate that public key and corresponding private key.
Full details can be found here: https://en.wikibooks.org/wiki/Cryptography/Generate_a_keypair_using_OpenSSL
Generate private_key.pem:
openssl genpkey -algorithm RSA -out private_key.pem -pkeyopt
rsa_keygen_bits:2048
Generate corresponding public_key.pem:
openssl rsa -pubout -in private_key.pem -out public_key.pem
You should now have your key pair. Only send the contents of public_key.pem file when requesting access to a new environment.
The NHS login button is available as a downloadable package.
You must follow the NHS login button guidelines.