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

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

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

When testing (particularly automated testing) on CIS2 user-restricted APIs, and you do not want to use a smartcard or modern equivalent, then you need to authenticate your mock authorisation healthcare worker with CIS2.

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

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

OIDC clients initiate the CIS2 authorisation sequence from the browser by calling the CIS2 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 case, you need to use the cis2 credentials.

If your application is configured to use our mock identity provider via the OIDC protocol in place of CIS2, 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 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/Cis2-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/Cis2-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 CIS2 you can login with the username aal3 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 a CIS2 ID token.

This call is an HTTP POST to the following endpoint:

https://identity.ptl.api.platform.nhs.uk/realms/Cis2-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/Cis2-mock-int/protocol/openid-connect/token' --header 'Content-Type: application/x-www-form-urlencoded' --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 CIS2 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 CIS2 - separate authentication.

For help and support, contact us.