Email import

The Microsoft Graph REST API can be used to access a user’s mailbox in the cloud on Exchange Online as part of Office 365.

Applicable Ultimo version: Rolling Release (Azure cloud)

Implementation steps

To use OAuth to access a user’s mailbox using the Microsoft Graph API the Ultimo application must be registered with Microsoft Entra ID.

1. Register Ultimo application with Microsoft Entra ID

1. Go to the Azure portal and sign in. This account must be in the same directory as the account that will be used to access Exchange.

2. Select Microsoft Entra ID and then select Manage > App Registrations in the left side menu.

3. Click on New Registration and use the following values:

   1. Enter a Name for the application

   2. For Supported account types choose Accounts in this organizational directory only

   3. For Redirect URI choose Web and enter https://{customer}.ultimo.net/OAuth2Callback where {customer} should be replaced with the actual customer environment

4. Click Register. Then copy the value of the Application (client) ID and the Directory (tenant) ID and save it. This will be needed later.

5. Select Certificates & secrets in the left side menu and click New client secret. Enter a description and click Add.

6. Copy the Value of the added client secret and save it.

2. Grant permissions

Two types of permissions can be used:

• Application permissions

• Delegated permission

Application permissions

Note: the steps below will grant Ultimo access to all mailboxes in your organisation. To limit this, create an application access policy.

1. Go to API permissions

2. Choose Microsoft Graph, select Application permissions and then add the following permissions: Mail.ReadWrite

Delegated permissions

When using delegated permissions, the signed-in user must have access to mailboxes that are used for email import.

1. Go to API permissions

2. Choose Microsoft Graph, select Delegated permissions and then add the following permissions: Mail.ReadWrite

3. Create credential in Ultimo

The application that was registered in the previous steps can be used to create a credential in Ultimo.

1. Go to the UCTool and select Credentials under Authorisation.

2. Click on the plus icon to create a new credential and use the following values:

   1. Enter an Id and Description for the credential

   2. When using application permissions, choose Client credentials as Grant type

      When using delegated permissions, choose Authorization code as Grant type

   3. When using delegated permissions, for Authorization URL enter https://login.microsoftonline.com/{tenant-id}/oauth2/v2.0/authorize?prompt=select_account where {tenant-id} should be replaced with the Directory (tenant) ID that was copied in the previous steps

   4. For Access token URL enter https://login.microsoftonline.com/{tenant-id}/oauth2/v2.0/token where {tenant-id} should be replaced with the Directory (tenant) ID that was copied in the previous steps

   5. For Client Id enter the value of the Application (client) ID that was copied in the previous steps

   6. For Client secret enter the value of the added client secret that was copied in the previous steps

   7. When using application permissions, enter https://graph.microsoft.com/.default as Scope

      When using delegated permissions, enter Mail.ReadWrite offline_access as Scope

3. Click on the save icon.

4. Click on the key icon in the toolbar to get an access token.

5. You will be redirected to the Microsoft login screen. Sign in with the account that will be used to access the mailbox(es).

6. You will be redirected back to Ultimo.

The credential with the access token can now be used to authenticate with the Microsoft Graph API to access a mailbox. Apply the credential on the Email server accounts that have been set up in Ultimo.