Modern Authentication for Enhanced Security
Basic authentication methods, including POP and IMAP, were deprecated on May 25, 2023, as part of NHSmail’s transition to more secure authentication protocols. Organisations must now adopt OAuth 2.0, which offers enhanced security by enabling third-party applications to access resources without handling user credentials directly. Although SMTP is still supported, NHSmail strongly recommends migrating to alternative protocols to future-proof your integration.
OAuth 2.0 enables applications to securely access resources like email and calendar data through Exchange Online APIs. The protocol involves several key components: the user, the third-party application, and the authorisation server (Azure Active Directory). Together, these components facilitate secure token-based authentication and authorisation.
Preparing for Integration
Before submitting an application registration request, organisations must complete several prerequisites. The application must support OAuth 2.0, and administrators should confirm whether the app requires delegated or application-level permissions. Commonly required permissions include IMAP.AccessAsUser.All, User.Read, and offline_access for applications that need to access resources without the user being present. Mailbox addresses used by the application must also belong to the requesting organisation, verified through its ODS code.
For applications requiring high levels of trust, such as those using Exchange Online PowerShell, a digital certificate may be needed. Supported certificate formats include .cer, .crt, and .pem. Additionally, organisations should specify URIs used in the authorisation process, such as redirect and token endpoint URIs.
Registering Your Application
The application registration process is facilitated through a web-based form accessible only to Local Administrators. Administrators must provide key details, including the ODS code, required permissions, mailbox addresses, and any applicable URIs or certificates. Once submitted, the request is processed, and administrators receive an email confirmation with a link to the NHS Application Registration Portal.
Successful registration results in the issuance of three critical credentials: the Application ID, Client Secret, and Tenant ID. The Tenant ID for NHSmail is fixed, and authorisation and token endpoints are standardised URLs. Client Secrets, which are used like passwords for the application, are accessible for 72 hours after issuance and must be kept confidential.
Configuring Your Application
With credentials in hand, administrators can configure their applications to use OAuth 2.0 for secure access to Exchange Online. The setup involves updating the application to use the retrieved credentials, including storing and refreshing tokens to ensure uninterrupted access. For applications requiring persistent background operations, the offline_access scope allows token refreshes without user re-authentication.
Credential Management and Renewal
Credentials, such as secrets or certificates, have expiration dates, and proactive renewal is essential to avoid service disruptions. NHSmail provides email notifications at 60, 45, 30, 14, and 7 days before expiration. Administrators can request renewal by submitting a ticket to the NHSmail helpdesk, ensuring the new credentials are deployed before the old ones expire.
In cases where an application is no longer needed, organisations can request deletion. If needed, deleted applications can be recovered within 30 days, but after this period, a new registration is required.
Troubleshooting Common Issues
Administrators may encounter challenges such as missing credentials, failed registrations, or application errors. NHSmail offers robust support through its helpdesk, which can assist with recovering credentials, troubleshooting errors, and navigating the registration process. Ensuring compliance with all prerequisites significantly reduces the likelihood of issues during integration.
Final Thoughts
Integrating with NHSmail using OAuth 2.0 ensures secure, reliable access to Exchange Online resources, aligning with modern authentication standards. By following the outlined process—from completing prerequisites to managing credentials—digital health innovators can achieve a seamless integration that supports their operational needs while safeguarding sensitive NHS data.
For further details or support, please contact 6B, or reach out to the NHSmail Knowledge Base or contact the NHSmail helpdesk.
