1. Home
  2. Guidance
  3. General Guidance
  4. Basic Authentication Deprecation
  5. Organisations with In-house or Third-party Backend Applications | Admin Guide

Organisations with In-house or Third-party Backend Applications | Admin Guide

This article provides information to Local Administrators of organisations with in-house software or third-party backend applications that are integrated to Exchange Online using basic authentication with the below protocols:

  • Post Office Protocol (POP)
  • Internet Messaging Access Protocol (IMAP)
  • Remote Power Shell (RPS)

Microsoft has replaced basic authentication protocols for Exchange Online with modern connectivity that enables additional layers of security. The NHSmail team has put in place a strategy to separate out the retirement of these protocols into a new schedule before June 2023 to reduce any potential impact or disruption to organisations and their users.

The below table provides an overview of this schedule:

Protocol Retirement date
POP, IMAP, RPS 25th May 2023 (evening)

IMPORTANT NOTE: All in-house or third-party backend applications using basic authentication will stop sending and receiving emails once the change is completed. A series of communications will be sent out to organisations appearing in our reporting to raise awareness and guide them through the process. However, it is responsibility of each organization to review their backend systems and confirm they are using modern authentication to connect to Exchange Online.

Overview

Microsoft has replaced basic authentication protocols for Exchange Online with modern connectivity that enables additional layers of security. The NHSmail team has put in place a strategy to separate out the retirement of these protocols into a new schedule before June 2023 to reduce any potential impact or disruption to organisations and their users.

All applications required to integrate with Exchange Online must use OAuth 2.0 authentication, a service provided by Azure Active Directory (Azure AD) to enable applications to connect with IMAP, POP or SMTP protocols to access Exchange Online in Office 365.

Recommendation: Although Simple Mail Transfer Protocol (SMTP) is still supported, you should consider switching to another protocol because it may be deprecated in the near future.OAuth 2.0 is an authorization protocol that enables third-party applications to access resources on a user’s behalf without having to know their credentials. It is widely used as a standard for authorization in modern web applications and APIs.

The OAuth 2.0 protocol involves several actors: the user who owns the resource, the third-party application that wants to access the resource, and the authorization server that grants permission to the third-party application to access the resource on behalf of the user. The authorization server issues an access token to the third-party application, which it can use to access the user’s resource.

The process to request the registration of an application is as follows:

Step 1: Review all pre-requisites and application requirements.

Step 2: Access the web-based form and submit a request.

Step 3: Retrieve the Application ID, Secret and Tenant ID.

Once the above process is completed, Local Administrators can proceed to configure the application to use OAuth 2.0.

Pre-requisites

1. Confirm the application supports OAuth 2.0.

To determine if the application can use OAuth 2.0 to connect to Exchange Online, Local Administrators should check the documentation and specifications for the app.

Exchange Online supports several authentication methods, including OAuth 2.0, which allows users to authorize third-party applications to access their Exchange Online data. However, some applications may not support OAuth 2.0, or may require additional configuration or permissions to use OAuth 2.0 with Exchange Online.

If the organization has developed in-house applications to connect to Exchange Online, Local Administrators should review the Microsoft documentation on OAuth 2.0 and Exchange Online REST APIs to ensure that the application meets the requirements and follows best practices for secure authentication.

If the organization is using a third-party application to connect to Exchange Online, Local Administrators should check with the vendor or provider of the application to determine if it supports OAuth 2.0 and if any additional configuration is required.

NOTE: If the application does not support OAuth 2.0, it will not be possible to connect to Exchange Online using modern authentication and therefore will stop sending and receiving emails when the change is completed.

Do not submit a request to us if the application does not support OAuth 2.0

2. Identify the type of permissions required

Local Administrators will be required to specify the type of permissions required for the application to connect to Exchange Online. There are five supported permissions:

  • IMAP/POP/SMTP Application:
    • Office 365 Exchange Online
    • IMAP.AccessAsApp
    • POP.AccessAsApp
    • SMTP.AccessAsApp
  • IMAP/POP/SMTP Delegated:
    • Office 365 Exchange Online
    • IMAP.AccessAsUser.All
    • POP.AccessAsUser.All
    • SMTP.Send
  • EWS:
    • Office 365 Exchange Online
    • Full_access_as_app
  • Graph Mail Delegated:
    • Mail.ReadWrite
    • Mail.ReadWrite.Shared
    • Mail.Send
    • User.Read
  • Graph Mail Application:
    • Mail.ReadWrite
    • Mail.Send

NOTES:

    • This information is mandatory when submitting a registration request.
    • Application and EWS permissions require at least one application account.
    • Applications that require additional permissions will have to go through an approval process; use the ServiceNow request process for O365 stores to raise an exception case.

3. Confirm mailbox addresses

Application and EWS permissions require at least one mailbox address (application account) that will be used to connect to Exchange Online. As part of this confirmation, Local Administrators are required to check:

  • Mailboxes are set as application accounts in NHSmail Portal.
  • Mailboxes are assigned to their organization (belongs to the same ODS code).

NOTE: This information is mandatory for application permissions, when submitting a registration request. Mailboxes not belonging to the same organization of the requestor will not be accepted and the request will be rejected.

4. Confirm if the application requires a Digital Certificate

Whether the app requires a digital certificate to connect using OAuth 2.0 depends on several factors, including the authentication method used, the API used to connect to, and the security requirements of the system.

For Exchange Online, Microsoft recommends using certificate-based authentication for certain scenarios, such as when the application requires a high degree of trust, or when using OAuth 2.0 with Exchange Online PowerShell. In these cases, Local Administrators would need to obtain a digital certificate and submit it as part of the request.

If Local Administrators are unsure whether in-house apps require a digital certificate or not, consult the documentation for the application or service, as well as the documentation for the OAuth 2.0 library or framework used to build this functionality. For third-party backend applications, Local Administrators can contact the provider of the service for more information about their authentication requirements.

NOTE: This information is mandatory when submitting a registration request. Applications using a Digital Certificate will not require a Secret to use OAuth 2.0.

5. List any URIs

URIs (Uniform Resource Identifiers) are used in OAuth 2.0 as identifiers for various components of the authorization process. Here are some of the common URIs used in OAuth 2.0:

  • Authorization Endpoint URI: This URI specifies the location of the authorization server’s endpoint where the resource owner can grant authorization to the client.
  • Token Endpoint URI: This URI specifies the location of the authorization server’s endpoint where the client can exchange the authorization grant for an access token.
  • Redirect URI: This URI is used by the client to specify where the authorization server should redirect the resource owner after authorization is granted or denied.
  • Client ID URI: This URI is used to uniquely identify the client application to the authorization server.
  • Scope URI: This URI specifies the set of permissions that the client application is requesting from the resource owner.
  • Resource Server URI: This URI specifies the location of the resource server that hosts the protected resources that the client is trying to access.

These URIs are typically defined as strings and can be specified in various formats, including HTTPS URLs, URN (Uniform Resource Name) format, or other custom formats. The specific format and requirements for each URI will depend on the implementation of the OAuth 2.0 protocol by the authorization server and client application.

If Local Administrators are unsure whether in-house apps are using URIs or not, consult the setup or configuration documentation for the application or service. For third-party backend applications, Local Administrators can contact the provider of the service for more information about their setup/configuration.

NOTE: This information is optional when submitting a registration request.

6. Confirm the Home Page URL

In OAuth 2.0, a home page URL is a URL that represents the homepage of a registered application. It is typically used as part of the authorization process to provide additional information about the client application to the user.

During the OAuth 2.0 authorization flow, when the user is redirected to the authorization server’s consent page, the server may display the home page URL along with the client name and logo. This helps the user to identify the client application and decide whether to grant access to their resources.

The home page URL is typically specified by the client application during registration with the authorization server, and can be any valid URL that represents the application’s homepage or landing page. This URL can also be used by the authorization server to provide additional information about the client application to the user, such as its purpose or features.

NOTE: This information is optional when submitting a registration request.

7. Choose an application name and find out the organization ODS code

Local Administrators are required to use a memorable application name as it will help to identify and troubleshoot any issues using NHSmail support teams services or going through the renewal process next year.

Search for the organization ODS code using the Organisation/Practitioner Search service.

NOTE: This information is mandatory when submitting a registration request.

Submit a Request

The NHSmail application registration form is available to Primary Local Administrators (PLAs) or Local Administrators (LA) to submit a request to register an application in Azure AD to connect to Exchange Online using OAuth 2.0.

Step 1: Access the registration form.

Step 2: Fill in the form using the information and data gathered while confirming the pre-requisites.

1. *Type in the organisation ODS code without spaces or special characters.

2. *Select the type of access required.

a. *If the application requires application permissions, please provide a list of mailbox addresses separated by comas:

i.e. email1@nhs.net,email2@nhs.net,email3@nhs.net

3. Confirm if the application requires a digital certificate to connect using OAuth2.0.

a. If the application requires a digital certificate, complete the submission process, and then proceed to follow the guidance to upload it.

4. Provide URIs identifiers separated by comas:

i.e. https://url1.net,https://url2.net,https//:url3.net

5. Provide Home Page URL.

i.e. https//homepage.net

6. *Type in an application name.

7. *Read and confirm the validation questions.

Step 3: Review all information that has been provided in the form and click on Submit button to submit the request.

Information marked with an * is mandatory and local administrators are required to confirm it is correct before submitting a request to us.

NOTE: An email confirmation will be sent with a link to access the Application Registration Portal. Please note it can take up to 20 minutes to set up access to it and for the request to be added.

Upload a Digital Certificate

In certain cases, in-house or 3rd party applications require a digital certificate instead of a Secret to connect to Exchange Online using OAuth 2.0. Local Administrators would need to obtain a digital certificate and submit it as part of the request.

Step 1: Submit an application registration request.

Step 2: Access NHSmail mailbox and look for an email with subject “app registration has been received”.

Step 3: Click on the NHS Application Registration Portal link provided on the email body and wait for the SharePoint site to load up; if requested, log in using the NHSmail credentials used to submit the application registration request.

1. Locate the RITM column and look down the list for the request needed to upload a certificate to.

 

 

2. Click on the RITM number of the request.

 

 

 

3. Double click on “Add or remove attachments”.

 

 

 

4. Locate and attach the digital certificate and click on Open.

5. Verify the correct file has been attached.

 

 

 

6. Close the certificate upload Window.

Once the certificate has been added, it can take up to 20 minutes for the request to be processed and completed.

NOTE: The following type of certificates are supported:

  • .cer
  • .crt
  • .pem

Any other type of certificates will be rejected, and the application registration will not be completed. Make sure to have and submit the correct file to avoid delays on registering the application.

Access the Application ID, Secret and Tenant ID

Once the application request is completed, an automated email will be sent to the Local Administrator who initially submitted the request. To access and retrieve the Application ID and Secret, follow the below steps:

To access the Application ID:

Step 1: Access the NHSmail mailbox and look for an email with subject “app registration has been received”.

Step 2: Click on the NHS Application Registration Portal link provided on the email body and wait for the SharePoint site to load up; if requested, log in using the NHSmail credentials used to submit the application registration request.

Step 3: Locate the RITM column and look down the list for the request.

 

 

 

Step 4: Check the Application Name is correct.

 

 

 

Step 5: Check the Status is set to Complete.

 

 

 

Step 6: Retrieve the Application ID which will be in the AppID column.

 

 

 

NOTE: The Application ID will not be available until the registration process is completed. If the Status is set to New or Failed, AppID column will be blank.

To access the Secret:

Step 1: Access the NHSmail mailbox and look for an email with subject “app registration is now completed”.

Step 2: Click on the NHS Application Portal Documents Library link provided on the email body and wait for the SharePoint site to load up; if requested, log in using the NHSmail credentials used to submit the application registration request.

Step 3: Locate the Name column and look down the list for the request.

 

 

 

Step 4: Click on the RITM number of the request.

 

 

 

Step 5: Click on the .docx file.

 

 

 

Step 6: Click on Edit in Desktop App button.

 

 

Step 7: Retrieve the Secret which will be in the document.

NOTES:

  • Only the Local Administrator who initially submitted the request will have access to the Secret. Please make sure the correct NHSmail credentials are used when opening the document in the Desktop App.
  • The document with the Secret will be available only for 72h, after this time it will be removed.
  • Application ID and Secret must remain confidential and should not share with anyone else. The .docx document which contains the Secret is protected and the Local Administrator will not be able to share or forward it.
  • Applications that require a digital certificate do not need a Secret and one will not be created as part of these requests.

To access the Tenant ID:

NHS tenant ID is: 37c354b2-85b0-47f5-b222-07b48d774ee3

To Access Authorization URL and Token URL:

Authorization URL is: https://login.microsoftonline.com/37c354b2-85b0-47f5-b222-07b48d774ee3/oauth2/v2.0/authorize

Token URL is: https://login.microsoftonline.com/37c354b2-85b0-47f5-b222-07b48d774ee3/oauth2/v2.0/token

Configure the application to use OAuth 2.0.

Once the application request is completed and the Local Administrator has retrieved the Application ID, Secret and Tenant ID, applications can be configured to use OAuth 2.0.

If the organization has developed in-house applications to connect to Exchange Online, Local Administrators should review the Microsoft documentation on OAuth 2.0 and Exchange Online REST APIs to follow their guidance.

If the organisation is using a third-party applications to connect to Exchange Online, Local Administrators should check with the vendor or provider of the application to confirm and set up the application to use OAuth 2.0.

Application Credential Renewal Notification

Local administrators will receive notifications and reminders when their organisation’s application credential’s that are connected to internal or external backend systems are nearing the expiration date.

To ensure that local organisations can renew their credentials in time and prevent service interruption, the organisation’s administrators will get reminder emails at 60, 45, 30, 14, and the last seven days before the credentials expire. The reminder email will come from no-reply.nhsmail@nhs.net and will have the subject “[Action Required] Renew the Credential for Entra Application – <Application Name>”. The email will contain relevant information about the application, its credential type, and its expiration date.

Credential Renewal Request

One of the local administrators who received the email can ask for a renewal by sending a ticket to the national helpdesk at helpdesk@nhs.net with the following information:

Details Description
Subject Renew Entra Application Credential Secret/Certificate
Application Name <Application Name found on the reminder mail>
Application ID <Application ID found on the reminder mail>
Credential Type <Secret* or Certificate**>
Email Address Administrator or Recipient’s email address
Availability <Administrator or Recipient’s availability in the next few days and best time to contact through MS Teams>
Secondary Contact Alternate NHSmail Local Admin user email address for sharing the credentials

*Please provide the email address of the recipient who will receive the credentials if the application credential type is a Secret.

**Please attach the certificate (public key) if the application credential type is a Certificate. The file type should be one of these: .cer, .pem, .crt. Please also change the extension of the public key to a .txt file to avoid being blocked by the NHSmail attachment policies.

The NHSmail team will renew the application credentials and send them securely to the recipients provided after the ticket was raised.

Note: The new credential does not replace the existing credential but works with it. The existing credential will continue to work until it expires, giving application owners enough time to update their application code with the relevant changes.

Application Registration Deletion Process

Automated Deletion

One of the steps to maintain hygiene and order for application registration is an automated task that will remove all applications that have expired credentials over 30 days old. This will happen once a week.

Manual Deletion

If application owners decide that an application is no longer needed, they can ask for it to be removed from the platform.

To ask for application removal, please submit a ticket to national helpdesk and include the Application Name and Application ID.

After the ticket is created, NHSmail team will arrange for it to be removed from the platform.

Application Recovery

If an application is deleted, it can still be recovered within 30 days of deletion. Application owner can contact the national helpdesk and give the information of their application, such as application name and application ID. NHSmail team will recover it and create a new credential.

After 30 days, deleted applications are irrecoverable. Application owners are advised to make a new request with the Modern Authentication process.

Issues and Troubleshooting

How can I submit a request to register an application to use OAuth 2.0?

Follow the guidance provided in the NHS Support Site, check pre-requisites and application requirements before submitting a formal request.

Where is the link to access the web-based form to submit a request?

The registration form can be accessed using any internet web browser.

How can I request access to the web-based form?

Only Local Administrators have access to the form.

I am a Local Administrator but do not have access to the form.

Please raise an incident with the NHSmail helpdesk to confirm and give you access to the form.

The web-based form shows an error when trying to submit a request.

Please raise an incident with the NHSmail helpdesk providing relevant details to troubleshoot and solve this issue.

I submitted a request, but I did not get an email confirmation.

It can take up to 20 minutes for new requests to be processed, if you do not receive an email confirmation in the next 4 hours, please raise an incident with the NHSmail helpdesk.

I submitted a request, but I do not have access to Application Request Portal.

It can take up to 20 minutes for new requests to be processed, if you do not have access in the next 4 hours, please raise an incident with the NHSmail helpdesk.

I have not received a confirmation email my request is completed.

If the application does not require a digital certificate, it can take up to 20 minutes for the request to be processed; if you do not have an email confirmation in the next 4 hours, please raise an incident with the NHSmail helpdesk.

If the application requires a digital certificate, read and follow how to upload a certificate. Once the certificate is uploaded, it can take up to 20 minutes for the request to be processed; if you do not have an email confirmation in the next 4 hours, please raise an incident with the NHSmail helpdesk.

I have received an email saying the registration could not be completed, what do I need to do next?

The reason why the request could not be completed is stated within the body of the email you have received. Please review the pre-requisites and application requirements before submitting a new request.

How can I access the Application ID, Tenant ID and Secret?

Review and follow the guidance to access the Application ID, Secret and Tenant ID.

The secret does not appear to be accessible anymore.

Local Administrators have access to Secrets 72 hours after the request has been completed.

I have missed the 72h deadline or lost the Secret created for my application, what should I do?

Please raise an incident with the NHSmail helpdesk providing the name of the application and type of permissions required. Please note that only the Local Administrator who submitted the request will be able to raise an incident for this purpose.

How can I submit a Digital Certificate with my request?

If the application requires a digital certificate, read and follow how to upload a certificate. Once the certificate is uploaded, it can take up to 20 minutes for the request to be processed.

Why do I keep receiving multiple emails from this service?

If you keep receiving multiple or duplicated emails from this service, please raise an incident with the NHSmail helpdesk.

Can I raise an exception case?

If the application requires a set of permissions that are not available as described in the pre-requisites section, you can request an exception using the ServiceNow request process for O365 stores.

How do I raise a ticket with NHSmail helpdesk?

If you are having issues that can’t be resolved using this guidance, please send an email to the NHSmail helpdesk to raise an incident, attaching the below information:

  • Name and email address of the Local Administrator who submitted the request using the web-based form.
  • Organization and/or ODS code.
  • Application Name.
  • RITM (if known).
  • Confirm if the application requires a digital certificate.
  • Any additional notes.
Last Reviewed Date 15/05/2024
Updated on 15/05/2024

Related Articles

Need Support?
Can’t find the answer you’re looking for? Don’t worry we’re here to help!
Contact Support
back to top