Overview
This page gives more details about testing this security pattern with our mock authorisation service:
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.
1. Obtain credentials
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:
Header |
Value |
apikey |
The API Key from your application |
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:
Parameter |
Description |
client_id |
The client identifier issued to the mocked authorisation provider client. |
client_secret |
The secret assigned to the mocked authorisation provider client. |
redirect_uri |
https://example.org/ |
In this case, you need to use the cis2 credentials.
3. Application calls the /authorize endpoint
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:
Parameter |
Description |
scope |
openid |
response_type |
code |
client_id |
The client_id returned from the call to the /keycloak-client-credentials endpoint.
|
redirect_uri |
https://example.org/ |
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'
4. Browser navigates to the callback URL supplied by the application
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.
5. Application posts client credentials and code to /token endpoint
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:
Parameter |
Description |
grant_type |
authorization_code |
code |
The authorization code returned from the call to the authorization endpoint. |
redirect_uri |
https://example.org |
client_id |
The client_id returned from the call to the /keycloak-client-credentials endpoint. |
client_secret |
The client_secret returned from the call to the /keycloak-client-credentials endpoint. |
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.
Last edited: 12 March 2024 2:42 pm