Skip to content

README.md

Latest commit

 

History

History
114 lines (78 loc) · 6.42 KB

README.md

File metadata and controls

114 lines (78 loc) · 6.42 KB

C# Application-restricted REST API - signed JWT authentication

Overview

This tutorial shows you how to connect to an application-restricted REST API using signed JWT authentication and the C# programming language.

To call an application-restricted API, you need to tell the API which application is calling it. When using signed JWT authentication you need to authenticate your application by sending a JSON Web Token (JWT) to an authentication server, signed using your application's private key. In exchange, you receive an access token which you need to include in the API request. To learn more about signed JWT authentication, see Application-restricted RESTful APIs - signed JWT authentication .

This tutorial shows how to use C# to generate and sign a JWT, exchange this for an access token with our authentication server and call our example Hello World API using your access token.

Setting up your environment

This example project was developed using .NET version 6.0.

Checkout the GitHub Repository

You can find the code for this C# application-restricted REST API - signed JWT authentication tutorial in our GitHub repository.

This project contains:

  • a JwtHandler class. This class handles the generation and signing of the JWT
  • an AuthClientCredentials class. This class handles the exchange of JWT with an access token from the auth server
  • a HelloWorld class located in the program.cs file. This class requests an access token and then uses that access token to send a GET request to the specified endpoint

To follow this tutorial download or clone this folder.

Create an application on our developer portal and generate a key pair

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 create an application

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

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 note of your API Key.

Generate a key pair

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

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

Register your public key

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

Populate the project's environment variables

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.

Variable Name Description
TOKEN_URL The endpoint where you send your signed JWT in order to exchange for an access token. For the sandbox environment, the value is https://sandbox.api.service.nhs.uk/oauth2/token
CLIENT_ID Your application's API Key
KID The KID you chose when generating a public/private key pair
KEY_FILE The filepath pointing to where you have saved your private key
ENDPOINT The URL for the API you wish to call. In this tutorial, we make a request to the Hello World Sandbox's application-restricted endpoint: https://sandbox.api.service.nhs.uk/hello-world/hello/application

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

Run the code

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

Run the application

You should first source your environment variable file before executing your application. Assuming you are using dotnet cli tool

source .env
dotnet run

Run using Makefile

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 receive the following response from the Hello World application:

{
  "message": "Hello Application!"
}