User-restricted NHS CIS2 separate authentication and authorisation - Java tutorial

This tutorial shows you how to connect to a user-restricted REST API using NHS Care Identity Service 2 separate authentication and authorisation and the Java programming language. It uses Spring to create a simple web application which authenticates the end user using our mock NHS Care Identity Service 2 authorisation service, receives an access token from our authorisation server and calls the user restricted endpoint of our Hello World API.

To call a user-restricted API, the end user must be authenticated. NHS Care Identity Service 2 is used to authenticate when the end user is a healthcare worker. With the separate authentication and authorisation pattern, authentication is done by NHS Care Identity Service 2 (CIS2). In exchange, you receive an ID token which you need to exchange it with an access token. You need to include this access token in the API request.

We developed this example project using Java 17 and maven 3.8.6, so you need to have those installed.

You can find the code for this Java user-restricted REST API NHS Care Identity Service 2 separate authentication and authorisation tutorial in our GitHub repository.

Implementation details

This project contains:

• an App.java file. This contains the application startup code

• a controllers folder containing a MainController.java file. This handles the authentication.

• a auth folder containing a set of classes that perform authentication, signing JWT and sending the token request.

To follow this tutorial download or clone this repository.

You need to create an application using our Developer portal.

This gives you access to your application ID and API key which you need to generate a JWT.

You also need to create a public and private key pair.

You register your public key with our authentication server and sign your JWT using your private key.

To do this, follow Step 1 'Create an application'.

Notes:

• when creating a new app, you need to select the 'Environment'. For this tutorial select 'Sandbox'
• when editing your application details and selecting the API you want to use, select 'Hello World (Sandbox)'. You might be prompted for a callback URL which is not required for the signed JWT authentication method, so you can enter a dummy value such as https://www.example.com.
• make a note of your API Key 

To do this, follow Step 2 'Generate a key pair'.

Make a note of the Key Identifier (KID) you have chosen.

To do this, follow Step 3 'Register your public key with us'.

You should now have:

• your application's API Key
• a KID that you have chosen
• your private key

To run the tutorial project, you need to set the following environment variables. Variables with PROVIDER_ prefix refers to the identity provider. In this tutorial we use a mocked CIS2 provider. There is already an application created for the hello-world tutorials so, you don't need to create one. In real production you must register your application with the required provider. All the required values for the mock provider is given to you and, you can find them in the env.sample file. The private key that you need to sign your JWT is also provided. In real application you should keep all these values as secrets and not include them in your project. Variables with SERVICE_ prefix refers to the application that you created in the NHS Digital portal i.e. previous steps.

You can set your environment variables in a file named .env. This project contains a sample env file to use:

• rename env.sample to .env and modify it
• source it by running source .env

Once you set the environment variables, you are ready to run the project.

Use the following commands to run the project using maven from the command line:

• mvn clean install - this compiles, tests and packages your code.
• source .env
• - this runs the executable jar file produced in the previous step.

Alternatively you can set your environment variables in a file named .env. Then use the make command:  make run. See the README for more info.

When you run the code, you should receive the following response from the Hello World application, showing you succeeded:

When you run the code, you should be able to call the application at https://localhost:8080

1. Enter this url: http://localhost:8080/hello/user
2. You will be redirected to the provider login page. Enter provided tutorialuser as username and the same as password
3. Upon successful authentication you will be redirected to the main page. You should the see response from hello-world service hello/user endpoint

To get started with our tutorials and APIs, you need to create a developer account.