Test your software

Once you've designed and built your integration with CIS2 Authentication, you'll want to test that it works as expected.

In this step you'll:

• get access to our integration testing environment
• test your integration code

The integration environment (INT) is where you'll develop, test and demonstrate your solution meets our technical conformance requirements.

In order to access the integration environment, you need to provide configuration information such as:

• Redirect URI - it's important that you provide a valid redirect URI. Some example redirect URIs are:
  • https://test.connect.test.co.uk/oauth/CIS2Auth
  • http://localhost:9005/pages/NHSCIS2Auth.aspx
  • http://localhost:8080/login/oauth2/code/cis2

• If you wish to have userinfo responses signed, state the algorithm to be used. The algorithms that are supported are defined in our OpenID Provider Configuration Documents, but typical values we see used are RS256 or RS512.

• Back-channel logout endpoint - to register for back-channel logout notifications, the client must provide a single public internet facing endpoint where NHS CIS2 Authentication can POST a logout token. This configuration is part of the OIDC client registration. The endpoint must be secured with HTTPS, accessible by a public DNS domain and present a server certificate matching its FQDN. The certificate presented must include a full certificate chain to a trusted public root CA e.g. DigiCert. For more details see back channel logout.
• Security pattern used - the OIDC standard has a number of ways to prove your application is the legitimate connecting party. Select which one you want to use - the most secure option is Private Key JWT, but we recognise that not all software supports this. If you cannot use this, make sure it's on your backlog or roadmap for future phases. For more details on these options see client authentication credentials - options available are:
  • Client Secret
  • Private Key JWT

This configuration is controlled by our configuration tool called Connection Manager which allows you to submit and manage your CIS2 Authentication configuration.  Please note that Connection Manager is only available in the Path To Live (PTL) environments. 

To access Connection Manager, please submit your Team ID as detailed in the document 'Providing your Team ID' that was included in the 'Welcome to CIS2' email you would have received as part of step 1.

Obtain user IDs (UUIDs)

As with all the PTL environments, user IDs are needed in the integration environment. These are known as UUIDs in CIS2 Authentication.

UUIDs are specific to each environment, so an INT UUID will not work in PROD and vice versa. Typically INT ones start with 5552 or 5553.

If you have previously integrated with CIS1, you may already have smartcards for an environment (and therefore UUIDs). These will continue to work with CIS2 Authentication.

If you require new UUIDs, make a smartcard request for a Path to Live environment. This process is still used if you just require a UUID, for example if you are going to be only using security keys. There is an option to advise that you do not require a smartcard to be sent to you. This process is managed by our ITOC team.

You'll need to ask for resources/users to be set up.

Any subsequent changes to identity set up can be made by contacting the ITOC team directly at [email protected].

For example, to use the new UUID with an alternative authenticator, such as Windows Hello or a security key, request this from the ITOC team at [email protected].

If you don't already have particular permission/role requirements for your application, then use these value when requesting that a user be set up:

• Org Code: A9A5A
• Org Name: NHSID DEV
• Role Code: R8015

Authenticators in PTL

All our PTL environments support the same authenticators available in the production environment. The choice of authenticator doesn't change how you integrate your application with NHS CIS2 Authentication, but may simplify how your development teams work.

Points to consider when assessing which authenticator to use:

• While some end users are still using smartcards over HSCN, there is no requirement to test with smartcards over HSCN as the authenticator flow is the same for all authenticators, therefore you can use any of the supported authenticators for testing. The only exception to this when testing for AAL3, you can't use an AAL2 authenticator. 
• If you're migrating from CIS1 to CIS2 Authentication, consider using non-smartcard authenticators to ensure you have removed any dependencies on CIS1
• For remote teams where an HSCN connection may not be available, we support authenticators that work over the internet without the need for a HSCN connection: smartcards that authenticate over the internet, security keys and Windows Hello. For offshore teams, security keys are a good choice as they are easy to purchase and can be registered remotely. They also have the advantage of not requiring any additional software to be installed.
• Each person in your team can use a different authenticator, plus a user's identity (UUID) can be bound to multiple authenticators, which help support a variety of working patterns your team may require.

While smartcards are provided centrally by NHS England, the other authenticators are not and must be purchased separately. NHS England also do not supply smartcard readers for system integrators and these must also be purchased separately. There are many different manufacturers of smartcard readers, whose drivers need to interact with a vast combination of different platforms, software, hardware and setups. Find out more about the smartcard readers we support.

If you have any questions about which authenticators your teams should use, please contact us to discuss. 

Development machine set up

There is minimal set up required to development machines that are specific to NHS CIS2 Authentication. No additional software is required to use security keys or Windows Hello. NHS Identity Agent, NHS Credential Management and relevant drivers are required to use smartcards over HSCN, along with having an HSCN connection. The set up is the same as for setting up a smartcard user workstation - an HSCN connection is needed to download the necessary software.

Next steps

The process to set up access to the integration environment takes 1 to 2 days depending on your requirements.

How you test your integration is up to you.

However, bear in mind that when you come to get your software assured, we will ask you to demonstrate your integration to us.

For automated testing, you can use our mock authorisation service. It's primarily intended for user when integrating with national APIs, but can also be used for non-API CIS2 Authentication integrations.

Once you've tested your software, the next step is to get your software assured.