User-restricted NHS CIS2 combined authentication and authorisation - C# tutorial

This tutorial shows you how to connect to a user-restricted REST API using NHS Care Identity Service 2 (NHS CIS2) combined authentication and authorisation and the C# programming language.

It uses Razor Pages in ASP.NET Core to create a simple web application which authenticates the end user using our mock NHS CIS2 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 CIS2 is used to authenticate when the end user is a healthcare worker. With the combined authentication and authorisation pattern, authentication is done by NHS CIS2 but is coordinated behind our OAuth2.0 authorisation server. In exchange, you receive an access token which you need to include in the API request. 

This example project was developed using .NET version 6.0, so you need to have this installed.

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

Implementation details

This project contains:

• a Program.cs file containing the application startup code which configures the OAuth flow required to authenticate. It also configures cookie authentication, which means cookies are used to store whether the user is authenticated or not, and to store received access tokens.

• a Pages folder containing the Razor Pages. Pages marked with an [Authorize] tag show that the user must be authenticated (as determined by a cookie) to access them. If an unauthenticated user tries to access these pages, it triggers the OAuth authentication handler (configured in Program.cs) to run.

• a HelloWorld Razor page located in the Pages folder. When this page is requested the stored access token is retrieved and used to send a GET request to the specified API endpoint.

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's API Key and Secret.

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 are prompted for a callback URL which is required for combined authentication and authorization. This URL is used to send users back to your application after successful (or unsuccessful) authorisation. This project is configured to run at https://localhost:7114 and the OAuth handler creates a callback endpoint at /callback. Therefore the callback URL should be set to https://localhost:7114/callback.

• make a note of your API Key and API Secret.

You should now have your application's:

• API Key
• API Secret

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.

You should first source your environment variable file before executing your application.

Assuming you are using dotnet cli tool:

source .env

dotnet run

Alternatively, you can set your environment variables in a file named .env. Then use the make command:  make run.

When you run the code, you should be able to load the application at https://localhost:7114.

1. Click the button 'Login with NHS CIS2' to be directed to our mock NHS CIS2 authorisation service.
2. Select an option to simulate a login and click 'Sign in'.
3. You are redirected back to the application and the access token you have received is displayed.
4. To use the access token in a request to the Hello World API, click 'Call API'.
5. The response from the API should read:

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