Send emails via Exchange Online (Office 365) using Modern Authentication (OAuth 2.0)

Help, I'm unable to send emails!

Microsoft has announced to permanently disable Basic Auth in all tenants in Exchange Online on October 1st, 2022.
Basic authentication means that the application you are using sends a username and password with every request. (These credentials are often stored or saved on the device).

This method is outdated and unsecure.

Therefor Microsoft permanently disabled Basic Auth as of October 1st, 2022.

Configure Modern Authentication in Azure AD

The idea is that you register an App in Azure Active Directory and that you give this App sufficient permissions. You are allowing an App to access certain APIs. In this case API permissions to access Exchange allowing us to email.

After you registered your *App you will have an ID to identify your app and some other settings. It are these settings that are required in your application and which will be used to check if you are allowed to email.

Prerequisites:

  1. Access to the Microsoft Azure portal for your tenant.
  2. An account with sufficient permissions to modify settings within your tenant (Global Administrator privileges).

Azure Configuration

  1. Open a webbrowser and navigate to Microsoft Azure portal.
  2. Login.
    (If you have multiple tenants select the correct tentant by clicking your account in the upper-right corner and select Switch directory).
  3. Go to App registrations (Search for App registrations).

    Image

  4. Register a new application by clicking New registration.

    Image

  5. On the Register an application, use these settings:
    1. In the Name input enter Winking PrintandShare.
    2. Supported account types select Accounts in this organization directory only ({tenant name} only - Single tenant).
    3. Click Register button at the bottom.
      The application has been created and the Winking PrintandShare overview page appears.

      Image

  6. Go to API permissions in the menu on the left side and add the following permissions:

    Image Image

    1. Click Add a permission > Microsoft APIs > Microsoft Graph > Delegated permissions > search and select User.Read > click Add permissions
    2. Click Add a permission > Microsoft APIs > Microsoft Graph > Application permissions > search and select
      Mail.Send,
      Mail.Read,
      Mail.ReadBasic,
      Mail.ReadBasic.All,
      Mail.ReadWrite,
      MailboxSettings.Read,
      MailboxSettings.ReadWrite,
      Calendars.Read,
      Calendars.ReadWrite,
      Contacts.Read,
      Contacts.ReadWrite
      > click Add permissions
    3. Click Add a permission > APIs my organization uses > select Office 365 Exchange Online > Application permissions > Other permissions > full_access_as_app > click Add permissions

      Image

  7. You will now see your Configured permissions. If you created the app and you are an Office 365 administrator click Grant admin consent for {tenant}.
    (Located in the API permissions overview).
    If you cannot Grant admin consent ask your administrator to do this.

    Image

    Image

    Image

    (Depending on your configuration and security you might need to add additional API permissions.)

  8. In Microsoft Azure go to Enterprise applications (or search for Enterprise applications).

    Image

    1. Select the Winking PrintandShare app that you created.
    2. Navigate to Properties in the menu on the left side.

      Image

    3. You can optionally set Visible to users to Yes.
  9. Either you choose to work with a Client secret (see 9.1) or you work with a Authority (see: 9.2). Depending on what you choose, follow the described steps below:

9.1. using Client Secret

Go back to App registrations in Azure and select Winking PrintandShare app. This will take you to the overview page. From the menu on the left side select Certificates & secrets.

Image

  1. Go to Certificates & secrets in the menu on the left.
  2. Click New client secret.

    Image

  3. Fill in a description Winking Print&Share app secret.
    Set the expires to 24 months.
    Click Add at the bottom.

    Image

  4. WRITE DOWN THE SECRET VALUE. This value will not be visible after a while and if you leave the page you will never be able to see this value! Make sure you write it down when you see it!
  5. Tip: In your agenda, set a reminder after 23 months that you must renew the client secret before it expires and update your software with the new client secret.
  6. (optionally) You can limit application permissions by applying an application policy in Exchange Online. This way you can limit the number of email accounts that this registered Azure application can access/use.

9.2. using Authority

Go back to App registrations in Azure and select your Winking PrintandShare app. This will take you to the overview page. From the menu on the left side select Authentication.

Image

  1. Under Platform configurations click Add a platform.

    Image

  2. Select Mobile and desktop applications (Windows, UWP, Console, IoT & Limited-entry Devices, Classic iOS + Android).

    Image

  3. Now you will see the Redirect URIs.
    Choose an URI: https://login.microsoftonline.com/common/oauth2/nativeclient or use a Custom redirect URI with your preferred value.
    Save by clicking the Configure button at the bottom.

    Image

    (If you later on need a specific redirect URI, you can add it here. For example: https://login.microsoftonline.com/common/oauth2/mycompany.be)

Collecting the required data

  1. Go to the App registrations section in the Microsoft Azure portal.

  2. Click on the app that you've created (e.g. Winking PrintandShare).

  3. In the menu on the left make sure menu item Overview is selected.

  4. Write down the value next to the label Application (client) ID:, this is our Client ID.

  5. Write down the value next to the label Directory (tenant) ID:, this is our Tentant ID.

  6. Depending the method you are using Authority or Client Secret follow the steps to collect the required data.

    6.1. Authority:

    1. In the Overview page of the Winking PrintandShare app you will see a link/button called Endpoints. When clicking this link/button a dialog will appear.

      Image

    2. In the Endpoints dialog write down the value of OAuth 2.0 authorization endpoint. This is something like https://login.microsoftonline.com/<YOUR_TENANT_ID>/oauth2/authorize. This value will be used for your Authority URI.

    6.2. Client Secret:

    1. You should have already made notes of the client secret when you created it and when it was visible to you. If you have forgotten this, you will never be able to retrieve this value. If this happens and it is not in use: delete the current client secret and create a new one described in the steps above. Don't forget to write down the value of the client secret when you see it after generating it.

I'm using Print&Share v3.1

Update the default email settings in Print&Share. These default settings are being used when creating new email channels.

Update default settings:

  1. Start Print&Share
  2. Open General Configuration.
  3. Navigate to Email tabpage.
  4. Click on Transport settings.
  5. Select Transportation method: Microsoft Exchange/Office 365.

For Modern (OAuth: open authority):

  1. Authority: fill in the value you got from Endpoints.
    For example: https://login.microsoftonline.com/<YOUR_TENANT_ID>/oauth2/authorize
  2. Client id: fill in the value of Application (client) ID you wrote down in the earlier steps.
  3. Redirect URI: fill in https://login.microsoftonline.com/common/oauth2/nativeclient.
    (If that doesn't work try: https://login.microsoftonline.com/common/oauth2/contoso.com. Be sure to replace contoso.com with your valid linked domain)

In case you receive this error code:
AADSTS900023: Specified tenant identifier 'authorize' is neither a valid DNS name, nor a valid external domain.
Try to replace authorize with your domain used in Azure, in case it is contoso.com then the authority url you could try could be: https://login.microsoftonline.com/<YOUR_TENANT_ID>/oauth2/contoso.com

Example:

Authority: https://login.microsoftonline.com/6s4d8zed-sz12-4655-g9pf-j6433f642254/oauth2/mycompany.be
Client id: 5h6g8zds-gg56-7723-s6xf-p6459j64849
Redirect URI: https://login.microsoftonline.com/common/oauth2/nativeclient

Image

For Modern (OAuth: client secret):

  1. Tenant id: fill in the value of Directory (tenant) ID you wrote down in the earlier steps.
  2. Client id: fill in the value of Application (client) ID you wrote down in the earlier steps.
  3. Client secret: fill in the value of the Secret you wrote down in the earlier steps.

Example:

Tenant id: 6s4d8zed-sz12-4655-g9pf-j6433f642254
Client id: 5h6g8zds-gg56-7723-s6xf-p6459j64849
Client secret: 6545456-ssd5-445......

Image

Update your profile(s):

  1. Start Print&Share click Change (upper-right corner of the main window) to open the Profiles dialog.
  2. In the Profiles dialog, select a profile and click Edit.
  3. Select the Email-channel from the Channels: list and click Configure.
    Alternately you can navigate to the Channel configuration tabpage and select the tabpage of your Email channel.
  4. Click on Transport settings.
  5. Click Load global settings to use the settings from the defaults in General Configuration.

I'm using File Processor

  1. Open or create a File Processor channel.
  2. Go to Input or Output (depending on where you want to use and configure email).
  3. Select for Input or Output Type: Email and specific type MS Exchange.
  4. Login method choose Modern (OAuth: client secret).
  5. From e-mail: <your email>
  6. Tenant id: fill in the value of Directory (tenant) ID you wrote down in the earlier steps.
  7. Client id: fill in the value of Application (client) ID you wrote down in the earlier steps.
  8. Client secret: fill in the value of the Secret you wrote down in the earlier steps.

See also