Digital Staff Passport API standard - authorisation using OAuth 2.0 private key JWT

How to secure external applications for the Digital Staff Passport using OAuth 2.0 private key JWT.

Overview

The Digital Staff Passport API standard requires external systems to secure their API using OAuth 2.0 private key JWT. This page explains how to do that.

OAuth 2.0 is an open standard for API authorisation and is generally considered to be the best way to secure modern RESTful APIs.

Private key JWT is a type of OAuth 2.0 authorisation where the calling application strongly authenticates itself by creating and signing a JSON Web Token (JWT). Unlike some other types of OAuth 2.0, an end user is not involved - this is a system-to-system, or 'application-restricted', form of authentication.

This approach is deemed suitable for APIs that handle personal or sensitive data within the NHS in England.

How this pattern works

In this pattern, Digital Staff Passport (DSP) authenticates itself by sending a signed JSON Web Token (JWT) to an OAuth 2.0 authorisation server that you provide.

DSP provides you with its public key and signs the JWT with its private key. In return, your OAuth 2.0 server gives DSP an access token, which it then includes with each API request.

The following diagram illustrates the pattern:

Diagram illustrating the data flows when authorisation using OAuth 2.0 private key JWT

The following sequence diagram shows how the various components interact:

Diagram illustrating how components interact when authorisating using OAuth 2.0 private key JWT

In words:

The end user, if present, launches the calling application - in this case DSP.
Time passes, until the user needs to access an application-restricted API.
The calling application generates and signs a JWT, using its own private key.
The calling application calls the OAuth 2.0 token endpoint with the signed JWT. In particular, this uses the OAuth 2.0 client credentials flow.
The OAuth 2.0 server checks the signature against the application's public key, and returns an access token to the calling application.
The calling application calls the application-restricted API, including the access token.

Pattern variations

In order to support a wide variety of tech stacks, we've provided pattern variations that we know are suitable for specific platforms and tools.

If you would like us to consider any further variations, contact us.

Default pattern

The default pattern uses 'vanilla' private key JWT, in which:

in step 2, we'll supply you with the URL for our public key JWKS
in step 3, we'll populate the iss field with the client_id you provide

Pattern variation 1: federated identity

This pattern variation uses OpenID Connect Discovery to publish our public keys. This is suitable for teams using Microsoft Azure because it aligns with using Microsoft identity platform with a federated credential.

In this pattern:

in step 2, we'll supply you with the URL for our OIDC 'well known' endpoint
in step 3, we'll populate the iss field with our OIDC issuer URL

Detailed integration instructions

The following sections explain in detail how to implement this security pattern.

You might also find it useful to refer to the guidance that explains how we use signed JWT to secure our own APIs: Application-restricted RESTful APIs - signed JWT authentication.

Step 1: DSP generates a key pair

This step happens during system configuration.

DSP generates a 4096-bit RSA private/public key pair.

Note that:

DSP generates separate key pairs for each environment.
Within each environment, DSP generates a separate key pair for each NHS organisation.
Within a given environment, DSP might use the same private/public key pair across multiple integrations.

DSP then:

stores the private key in a key vault
publishes the public key as a JWKS at a well-defined URL
publishes an OIDC 'well-known' endpoint which includes details of our public key JWKS (for use with pattern variation 1)

For more details on how DSP generates a key pair, or to generate a key pair and JWKS for testing, see Step 2: generate a key pair on our Signed JWT authorisation guidance page. You can also use our API platform to publish your public key JWKS for testing - see Step 3: register your public key with us, and use the option to "Ask us to host your public key".

Here's an example public key JWKS containing two separate public keys (the purpose of having multiple keys is to allow for periodic key rotation):

{
  "keys": [
    {
      "kty": "RSA",
      "e": "AQAB",
      "use": "sig",
      "kid": "DSP_TEST_1",
      "alg": "RS512",
      "n": "ApKKL1BY_itCl3EDTTlLJzuP33Rl6LbEaDsk75GxdyXzXb0jsbWQ-fG3b2i0T-efcJfmuHvzzAk6NoOSwnG_kRhb6b_n924MyqkGS6_Mb1wMhZdd4GQCU1c0vJLRVYTvrySq9L4M4CP2yCdyHXFv57kanA-R3nRUNO6tIkRWsdD2VVwm6dII_QTnSpKrRgyt0DyYImRxsa52AdpdFAArXiIR1OZgkuwJn8l-6yKT6iXUYhgfI6Pgl3XgJ3i06DDjpkUG-zTpyFlpnxLfgvZ8P-Q6LXvfazWItzDYM5xe37RL8zkus2mip5FCgKHu5Ed59CPYkto2YRaRUKvSoZ1BYPLfMjfEQuHPpqvmfL4MG8N7dzUAHRI6mDuOrWTsxyqJHV-I2MYPEPJx1YlZS-mbpbJj6oQmwWxXvld2X-clvNjePa6CD3R6U6pBnc9y_3luj_JrkKItUqAxBxhIBGM1GdeCJnogDEypXQIOKBMZpy6er_EHFbRXtgQEJ-snIY0TITnsOyjmpyrFWv2pa-fe4jtAPeeo4jUJfcw6iAHbN31WcMfg0GNnV4Td_BmcdmvihbV827_3OmqHdt9HEWJCtkWJvZcDN09WifTdBNvXwy9vKyAHRdmkGG-pdq_JFWt661Y7Dm9ubSN58OzO6uyVOJMHdIpcCjtPb8mkQ8rFheax"
    },
    {
      "kty": "RSA",
      "e": "AQAB",
      "use": "sig",
      "kid": "DSP_TEST_2",
      "alg": "RS512",
      "n": "Ah-ekOAyAvmO3ZCxCyUWNwGQRR52sMbtWLVPLoFvA0JlCg_qWdtQvsEt4t5KuT0Ujf7h0vcOJJvDwfWX8j1dVFlDR7SMEa48hodw0xqlKRp82LCwl4nScK_OWN7eVgsofyLedfnTKnGlixaROYn7Tt6RGPPO9A1PizEI3bUhC39fo6JwxWNFba_PIMdLFwI2jPwpja4gxNlFUOK-T9HXPxhtLgx6lcrJOL5YHLld9g5pP2JwLl8XvvzlQ295p-tFfV6zRGcIf5t2oHNkFbADo4aYK7FvbK1afJGILYjQgYCJtRZarkU2fb47izyCRJBXnzqPWlh2X3FI7ib6fRwlaTiTj6Rcj2XKrYUBI9nCSaQa8euSw2tNLYAUNPXhKW35hK1CYG5ZKNGrXph6tjJlqTxgQjE2oyciyVPAI_cjyNxaXiPbor7r9ffiFL-Ck75q9IeH1saj7zISziTTMLmK84IC9l3ARRbsZ9eFr7YswDNuHL0ghqTpr9RejzXinWydBLoHSyl06dG4hjX5tlDqutK0PGRhi9pX9EpPqn0wTm3GfOn06C8wtjQDuSECrAlAUskVKDJ0q9e7bZnX5R3izBm30mx2yXTJf7w_iR079h_LMEijzuKhs8LZIpNU3RgVgqkGPnOCPtLt3SpFfExSYAunhslZ9i_bvrX5u-Kp-fLH"
    }
  ]
}

We've also published this public key JWKS at a URL that you can use for testing.

The associated private and public keys are also available below in X.590 PEM format.

DSP_TEST_1 private key

DSP_TEST_1 public key

DSP_TEST_2 private key

DSP_TEST_2 public key

Step 2: DSP registers with your API

This step happens during system configuration.

The DSP team registers DSP with you for a specific NHS organisation.

Ideally, you provide a user interface for the DSP team to use, but alternative processes, such as a service request, are acceptable.

During registration:

the DSP team shares its NHS organisation-specific public key URL with you
you provide the DSP team with an organisation-specific client ID as per the OAuth2.0 standard

Step 3: DSP generates and signs a JWT

This step happens during operational use of DSP.

Specifically, it happens when DSP needs to use your API, but only if DSP doesn't already have an active access token.

DSP generates and signs a JWT for use in step 3.

The JWT consists of three parts:

header
payload
signature

Header

The JWT header includes the following fields:

Field	Description	Type
alg	The algorithm used to sign the JWT, which is always RS512.	string
typ	The token type - JWT.	string
kid	The Key Identifier (KID) used to select the public key to use to verify the signature of the JWT, for example test-1. If DSP has multiple public/private key pairs, you must use this to select the appropriate public key from its JWKS.	string

Field

Description

Type

alg

The algorithm used to sign the JWT, which is always RS512.

string

typ

The token type - JWT.

string

kid

The Key Identifier (KID) used to select the public key to use to verify the signature of the JWT, for example test-1.

If DSP has multiple public/private key pairs, you must use this to select the appropriate public key from its JWKS.

string

Example

{
"alg": "RS512",
"typ": "JWT",
"kid": "test-1"
}

Payload

The JWT payload includes the following fields:

Field	Description	Type
iss	The issuer of the JWT. By default this is the client ID you issued to DSP in step 1, but if you're using pattern variation 1, it is the issuer URL as per our OIDC 'well known' endpoint.	string
sub	The subject of the JWT - the client ID.	string
aud	The audience of the JWT - the URI of the token endpoint DSP is calling, for example https://<YOUR-DOMAIN>/oauth2/token for your production environment.	string
exp	Expiry time of the JWT, expressed as a Numeric Time value - the number of seconds since epoch (for example, a UNIX timestamp). This is set to 5 minutes after the time of creation of the JWT.	number
iat	Issue / creation time of the JWT, expressed as a Numeric Time value - the number of seconds since epoch (for example, a UNIX timestamp). API providers can choose whether to do anything with this claim. It has only been included in the specification because the Microsoft identity platform federated credential pattern mentioned in security pattern variation 1 requires it to be present.	number

Example

{
"iss": "<test-app-api-key>",
"sub": "<test-app-api-key>",
"aud": "https://<YOUR-DOMAIN>/oauth2/token",
"exp": "<current-time-plus-5mins-from-jwt-creation>",
"iat": "<current-time>"
}

Signature

The JWT signature consists of the contents of the header and payload, signed with the appropriate private key.

Assembling the JWT

The complete JWT consists of:

the header, base64 encoded
a period separator
the payload, base64 encoded
a period separator
the signature, base64 encoded

Generating a test JWT

You can generate a JWT for testing at https://jwt.io/.

Step 4: DSP gets an access token

This happens immediately after step 3.

Once it has a signed JWT, DSP makes a call to your OAuth 2.0 server's token endpoint.

Specifically, this is an HTTP POST . We recommend the following URLs for your token endpoint:

Environment	Token endpoint
Integration test	https://integration-test.<yourdomain>/oauth2/token
Production	https://<yourdomain>/oauth2/token

DSP includes the following data in the request body in x-www-form-urlencoded format:

grant_type = client_credentials
client_assertion_type = urn:ietf:params:oauth:client-assertion-type:jwt-bearer
client_assertion = <the signed JWT from step 3>

Here's a complete example, as a CURL command:

curl -X POST -H "content-type:application/x-www-form-urlencoded" --data \
"grant_type=client_credentials\
&client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer\
&client_assertion=<DSP'S-SIGNED-JWT>" \
https://<YOUR-DOMAIN>/oauth2/token

Your token endpoint must validate the request as per the OAuth2.0 specification, including, but not limited to:

verifying the signature against the appropriate public key for the given client ID (iss field) and key identifier (kid field)
checking the JWT hasn't expired (exp field)

Your token endpoint must then respond with a JSON response body containing the following fields:

access_token - the access token DSP uses when calling your API
expires_in - the time after which the access token will expire, in seconds, which is ideally 600 and must be a maximum of 3600
token_type - must be Bearer

Here's an example response:

{'access_token': 'Sr5PGv19wTEHJdDr2wx2f7IGd0cw',
'expires_in': '600',
'token_type': 'Bearer'}

Refresh tokens

You do not need to include a refresh token in your response.

Error scenarios

If there are any issues with DSP's call to your token endpoint, you must return an appropriate error response, as per the OAuth2.0 specification.

Step 5: DSP calls your API

As appropriate, DSP calls your API as described in the Digital Staff Passport API standard.

DSP includes the following header in its call:

Authorization = Bearer <access token from step 4>

Here's an example, using a CURL command:

curl -X GET https://<YOUR-DOMAIN>/dsp-api/employees/12345 \
-H "Authorization: Bearer <access token from step 4>"

Your API must validate the Authorization header as per the OAuth2.0 specification, and return a suitable error if validation fails.

Step 6: DSP refreshes its token

DSP's access token expires after a period of time, as per the expires_in parameter - by default this is 600 seconds (10 minutes).

After that, calls to your API must return an HTTP status code of 401 (Unauthorized).

You do not need to provide a method for DSP to refresh its access token. If the token expires, DSP will get a new token, repeating the above process from step 3.

Step 7: DSP rotates its key pairs

Periodically, DSP rotates its key pairs, as follows:

DSP generates a new key pair, as per step 1.
DSP adds the new public key to its published public key JWKS, with a new kid, alongside the existing public key.
DSP starts using the new private key to sign its JWTs, as per step 3.
DSP removes the old public key from its published public key JWKS.

You do not need to take any action when DSP rotates its key pairs.

You just need to make sure you always validate the JWT signature against the appropriate public key for the given client ID and KID in step 4.

Last edited: 15 January 2025 2:17 pm