Digital Staff Passport direct to wallet integration standard

Use this standard to integrate an external system with the Digital Staff Passport (DSP) using the 'direct to wallet' integration pattern.

This page assumes you already understand Digital Staff Passport integration key concepts.

This integration pattern is suitable for external systems that have an employee portal that employees sign in to directly.

With this integration pattern, employees using DSP can download information, also known as ‘credentials’, from an external system directly to their digital wallet.

Before they do this, they must first upload their identity credential to the external system to strongly authenticate themselves.

The DSP digital wallet uses the 'Verifed IDs' feature of Microsoft Authenticator.

Credentials are transferred to and from the digital wallet as W3C compliant verifiable credentials.

DSP includes a ‘credential gateway’ to handle this on behalf of external systems. External systems interact with the credential gateway as if it were an Open ID Connect (OIDC) provider.

The DSP credential gateway is based on the Condatis Credential Gateway.

The credential gateway uses the Microsoft Entra APIs to interact with Microsoft Authenticator.

The design currently doesn't conform to the OpenID for Verifiable Credential Issuance draft standard. This might change in the future.

The end-to-end user journey requires the employee to interact with:

• The DSP online portal for their specific employer
• The DSP digital wallet on their mobile device
• The external system’s employee portal

The journey assumes the employee has already:

• registered for DSP with their employer
• completed an identity check
• downloaded their identity credential to their digital wallet

The journey can vary depending on the specific use case, but the following journey is a typical example:

1. Employer requests employee’s credentials via the DSP employer portal.
2. DSP employer portal emails credential request to employee.
3. Employer emails employee separately to tell them they can get the credentials from the external system, ideally including a link to access it (this step is necessary because the email from the DSP employer portal doesn’t include this information).
4. Employee accesses external system’s employee portal.
5. Employee requests to download relevant credentials.
6. External system checks employee’s identity by uploading their DSP identity credential.
7. Employee downloads requested credentials to their DSP digital wallet.
8. Employee uploads credentials from their DSP wallet to the DSP employee portal.
9. Employee shares credentials with their employer.

This standard explains in detail how external systems should implement steps 4 to 7 of the above user journey.

Screenshots are given as examples only and do not need to be followed exactly.

It is assumed that the employee already has access to the external system's employee portal, and is able to sign in to it using their usual access credentials.

For example:

DSP does not require the external system's employee portal to have any particular method or strength for authenticating the employee. A strong DSP identity check comes in a subsequent step.

1. Employee navigates to the relevant part of the external system’s employee portal.

For example:

2. The portal offers the employee an option to download the relevant credential to DSP.

To avoid confusion, this option should only be available if DSP is applicable to the employee. How this is determined depends on the external system and should be discussed with us.

The portal should make it clear whether the employee has already downloaded the credentials to DSP.

3. If the employee has already downloaded the credential, they should be able to re-download them, but the portal should prompt them to delete the credential from their digital wallet first.

For example:

4. When the employee requests to download the credential, the portal should present them with the exact information that is to be downloaded and ask them to confirm if they wish to proceed.

For example:

Before the external system allows the user to download the relevant credential, it must check their identity by uploading their identity credential from their DSP digital wallet.

This only needs to be done once per employee per session.

To do this, the external system interacts with the DSP credential gateway in 'verifying' mode.

From the external system’s perspective, this is a standard OIDC interaction with the DSP credential gateway. It proceeds as follows:

1. Employee requests to verify their identity.

For example:

2. External system redirects employee’s browser window to DSP credential gateway’s ‘authorize’ endpoint.
3. DSP credential gateway presents a QR code to the employee.

4. Employee opens their digital wallet and scans the QR code.
5. Digital wallet shares the employee’s identity credential with the DSP credential gateway.

6. DSP credential gateway verifies the identity.

7. DSP credential gateway redirects browser window back to external system, including an authorisation code.
8. External system calls DSP credential gateway’s ‘token’ endpoint to exchange authorisation code for OIDC token, which includes employee’s identity credential.
9. External system checks that the identity credential matches the signed in employee, based on first name, surname and, if possible, date of birth.
10. External system makes a note of the employee's DSP 'unique identifier' from the identity credential - this is needed when issuing their credential in the next step.
11. External system lets the employee know that their identity has been verified.

For example:

We have some scripts that demonstrate this sequence of interactions – contact us for details.

Once the identity check is complete, the employee can download the requested credentials to their DSP digital wallet.

It is assumed that they have already confirmed the exact information to be downloaded as part of step 5.

To do this, the external system interacts with the DSP credential gateway in ‘issuing’ mode.

From the external system’s perspective, this looks like an OIDC interaction with the DSP credential gateway, with the credential to be issued wrapped up in the authorisation request. It proceeds as follows:

1. Employee requests to download credential.

For example:

2. External system calls DSP credential gateway’s ‘pushed authorisation request’ endpoint with details of the credential to be issued. This includes the employee's DSP 'unique identifier' as obtained from their identity credential.
3. External system redirects employee’s browser window to DSP credential gateway’s ‘authorize’ endpoint.
4. DSP credential gateway presents a QR code to the employee.

5. Employee opens their digital wallet and scans the QR code.
6. DSP credential gateway issues employee’s credential to digital wallet.
7. Employee accepts the credential into their wallet

8. DSP credential gateway redirects browser window back to external system, including an authorisation code.
9. External system calls DSP credential gateway’s ‘token’ endpoint to exchange authorisation code for OIDC token, which includes details of the issued credential, for confirmation. In particular this includes the 'Serial Number' - a GUID which the external system should retain for future use such as revoking the credential.
10. External system's portal confirms to the employee that the credential has been downloaded to their wallet.

For example:

We have some scripts that demonstrate this sequence of interactions – contact us for details.

To be compatible with Digital Staff Passport, external systems must issue credentials exactly as per the Digital Staff Passport verifiable credentials data schema.

In particular, issued credentials must include the employee's DSP 'unique identifier' as obtained from their identity credential.

If something changes in the external system that means an issued credential is no longer valid, the external system must revoke the credential.

There is no way to actually force the credential to be revoked from the employee's digital wallet, it requires the employee to do it manually. But it can be revoked in the credential gateway.

Here's a typical journey:

1. Something happens in the external system that invalidates a previously issued credential.
2. External system revokes the credential in the credential gateway.
3. External system emails employee to tell them to remove the credential from their digital wallet.
4. Employee removes the credential from their digital wallet.

This standard explains in detail how external systems should implement steps 2 and 3 of the above user journey.

The credential gateway provides an endpoint that the external system can call to revoke the credential, based on the credential ID.

Once this is done, any attempt by the employee to share the credential from their digital wallet to another employer via the Digital Staff Passport employee portal will fail.

For details of the endpoint, see the credential gateway API specification - specifically the /Revocation/revokecredential operation.

Because there is no way to automatically revoke a credential from the employee's digital wallet, the only alternative is to contact the employee to let them know their credential is no longer valid and that they should remove it themselves.

A good way to do this is to send them an email.

For example email content, contact us.

The NHS digital service manual includes a design system that provides best practice guidance for building user interfaces for the NHS.

We don’t require you to conform to the design system, especially if it would conflict with your own design system, but it does provide design patterns you might find useful.

Your service must be a bronze service, meaning it is operational and supported during business hours.

For more details, see service levels.

We provide the following environments:

To access one of these environments, contact us.

We will:

• ask you to tell us the redirect URL for your application that you will use for the OIDC integration with the credential gateway
• provide you with an OAuth 2.0 client ID and client secret that are unique to your application, which you must use when interacting with the credential gateway
• provide you with a credential signing key, which you must use when issuing credentials
• set up a Decentralised Identifier (DID) for you at a URL like <your organisation>.staffpassports.nhs.uk which will be included in the 'Issued by' data field in any credentials issued on your behalf by the DSP credential gateway

Before your integration goes live, we’ll need to complete a number of assurance checks for both your organisation and your system. We call this onboarding.

This includes, for example, making sure we have processes in place to deal with live incidents.

For more details, see Digital Staff Passport onboarding and assurance.