Testing with our mock authorisation service using NHS login - separate authentication

This page gives more details about testing this security pattern with our mock authorisation service:

• user-restricted RESTful APIs - using NHS login - separate authentication

When testing (particularly automated testing) on NHS login user-restricted APIs, you need to authenticate your mock authorisation user with NHS login.

Successful authentication results in an ID token being issued to the callback endpoint that you registered with NHS login.

Your software needs to follow a standard OIDC authorisation code flow with NHS login.

OIDC clients initiate the NHS login authorisation sequence from the browser by calling the NHS login authorize endpoint.

This is a configuration step, normally done before you deploy your application.

To access our authorisation endpoints you must obtain the client credentials for our mocked authorisation provider client.

To get these credentials, you can make a call to our mock-jwks service - but the application you previously registered on the API Platform must have mock-jwks (Int Environment) added to its list of enabled APIs.

After configuring your application to use the mock-jwks API, you can call the mockjwks API's keycloak-client-credentials endpoint with the API Key of the application:

https://int.api.service.nhs.uk/mock-jwks/keycloak-client-credentials

Note: the above URL is for the mock-jwks API in the integration environment. You need to include the following headers in your call:

Here is a complete example, as a CURL command:

curl --location --request GET 'https://int.api.service.nhs.uk/mock-jwks/keycloak-client-credentials' --header 'apikey: {your API key}'

If the request is valid, the mock-jwks API responds with a HTTP status 200 response.

This response contains the following set of parameters for both cis2 and nhs-login:

In this instance we need to use the nhs-login credentials.

If your application is configured to use our mock identity provider via the OIDC protocol in place of NHS login, proceed to step 5.

Our mock OIDC provider's discovery document can be used to automatically configure your application to use the provider.

Call our authorize endpoint to authenticate via the browser in exchange for an authorization code.

This call is an HTTP GET to the following endpoint:

https://identity.ptl.api.platform.nhs.uk/realms/NHS-Login-mock-int/protocol/openid-connect/auth

Note: the above URL is for our mock authentication server in the integration environment.

You need to include the following query parameters in your call:

Here is a complete example, as a CURL command:

curl --location --request GET 'https://identity.ptl.api.platform.nhs.uk/realms/NHS-Login-mock-int/protocol/openid-connect/auth?scope=openid&response_type=code&client_id= {client_id received from mock-jwks API}&redirect_uri=https://example.org'

If the request is valid, the OAuth 2.0 authorisation server responds with a HTTP status 200 and a normal redirect to a login form from the auth endpoint.

For NHS login you can login with the username p9 as a test user.

After entering a valid set of credentials for a user, the browser navigates to the redirect_uri provided in the authorization call, with an authorization_code as a query parameter.

Call our token endpoint to exchange the client credentials and authorization code for an NHS login ID token.

This call is an HTTP POST to the following endpoint:

https://identity.ptl.api.platform.nhs.uk/realms/NHS-Login-mock-int/protocol/openid-connect/token

Note: the above URL is for our mock authentication server in the integration environment.

You need to include the following query parameters in your call:

Here is a complete example, as a CURL command:

curl --location --request POST 'https://identity.ptl.api.platform.nhs.uk/realms/NHS-Login-mock-int/protocol/openid-connect/token' --header 'Content-Type: application/x-www-formurlencoded' --data-urlencode 'grant_type=authorization_code' --data-urlencode 'code= ' --data-urlencode 'redirect_uri=https://example.org' --data-urlencode 'client_id={client_id received from mock-jwks API}' --data-urlencode 'client_secret={client_secret received from mock-jwks API}'

Once the user authentication is successful, your web server should call the NHS login token endpoint and receive a number of tokens including the ID token.

The ID token has a lifetime of 1 hour. After 1 hour the user must re-authenticate.

We strongly recommend you exchange the ID token for our access and refresh tokens as soon as possible.

For full details of how to use this security pattern, see User-restricted RESTful APIs - using NHS login - separate authentication.

For help and support, contact us.