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)

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.

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

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).

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.

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.

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.

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.

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.

Upload a Digital Certificate

In certain cases, in-house or 3^rd 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.

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.

 

 

 

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.

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.

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.