User-restricted NHS login separate authentication and authorisation - C# tutorial

This tutorial shows you how to connect to a user-restricted REST API using NHS login separate authentication and authorisation and the C# programming language. It uses .NET Core to create a simple web application which authenticates the end user using our sandbox NHS login environment, 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 login is used to authenticate when the end user is a patient. With the separate authentication and authorisation pattern, authentication and authorisation are done separately. You might authenticate the user when they sign in but only get authorisation to call the API if and when you need it. You do authentication directly with NHS login and then separately do authorisation with our OAuth2.0 authorisation service.

This example project was developed using .NET 6.0.102 so you need to have this installed.

You can find the code for this C# user-restricted REST API NHS login separate authentication and authorisation tutorial in our GitHub repository.

Implementation details

This project contains:

• A Program.cs file that initialises the client application and creates a globally accessible Config class.
• A Startup.cs file that configures the authentication providers as well as other services.
• A JWT/JwtHandler.cs file that generates and signs JSON Web Tokens
• A Pages directory that contains each Razor Page used by the example client, each page contains its own html view and controller logic.

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 example tutorial, you need to set the following environment variables.

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 dotnet from the command line:

• source .env
• dotnet run

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 be able to load the application at http://localhost:5001.

1. Click the button 'Login with NHS login' to be directed to Keycloak.
2. Sign in with your user credentials for the client.
3. You are be redirected back to the application. The access token you have received is used to make a request to the Hello World API.
4. The response from the API should read:

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