Setting up OAuth Microsoft Outlook

After version 4.2.0 of the Helpdesk plugin a new feature was added - OAuth authentication for MS Office 365. In this guide, we will teach you how to configure the plugin on this point.

Creating OAuth App

Please login to the site of Microsoft Azure. Then select Microsoft Entra ID.

microsoft_entra_id.png

Then on the left sidebar, please click on Manage, a drop-down menu will appear, then click on App registrations.

app_registration.png

Afterward, just select New registration.

new_registration.png

Now, fill in the below 4 fields:

  • Name
  • Supported Account Type
  • Redirect URI (URL) - type "Web"
  • Redirect URI (URL)

register_an_application.png

The Redirect URI (URL) is taken from Administration - Plugins - Helpdesk - Configuration - OAuth settings tab.

helpdesk_oauth_redirect_url.png

The ready app (after saving) looks like this.

ready_redmine_mail_app.png

Now, copy the Application (client) ID via the button.

copy_app_id.png

Please paste it into the Helpdesk configuration field.

app_id_helpdesk.png

The next step that we have to do is to create our secret value. It is going to happen via the Add a certificate or secret button.

add_a_certificate_or_secret.png

Click on the New Client Secret.

new_client_secret.png

Then on the right side, a new window will pop up. Please fill in the 2 fields in accordance with your needs:
  • Description
  • Expires

mail_get_secret.png

Now, please copy the Value via the button for copying.

value_secret.png

And paste it into the Client secret value field of the Helpdesk settings.

helpdesk_client_secret_value.png

Set up the Helpdesk plugin for incoming mail

We have almost done our job. Now, we need to set up the Helpdesk itself. Please go to the Helpdesk project you would like to configure and go to the settings tab and fill in the below 3 fields for the incoming mail settings:

  • Protocol - Microsoft Outlook
  • Username
  • Password

helpdesk_mail_server_settings.png

Then click on the Authorize button that is located below the Password button. You will be redirected again to the Microsoft site to log in again. Afterward, a new window will come to you Let this app access your info?. Please click Yes.

microsoft_let_mail_app_yes.png

If everything is successful, then the Authentication section will come to a green sign. Also, three new options will come as well:
  • Mail folder
  • Move on success
  • Move on failure

successful_mail_setting.png

And now we test our configuration and see that everything is fine. The emails are received.

helpdesk_outlook_received_mails.png

And our first received mail.

successfully_received_first_mail.png

Automation of receiving emails

When you successfully set up the OAuth for your project then you could configure the receiving of the emails to be automatic. It could be done in 2 ways:

bundle exec rake redmine:email:helpdesk:receive RAILS_ENV=production

Or:

wget -O - http://127.0.0.1/helpdesk_mailer/get_mail?key=******************

More detailed information about the automatic receiving configurations could be checked in this article.

Important: The IMAP method isn't available for OAuth.

Outgoing mail settings

When you successfully authorize Outlook, you will also unlock the Microsoft protocol for the outgoing settings as well. So, you have to:
  • Disable the default settings
  • Select the Microsoft Outlook protocol from the drop-down menu
  • Set your outlook email address to the From field

Please check the below picture to make the situation more clear.

outgoing_settings.png

So, when we sent a reply to a client via the Helpdesk ticket interface.

email_sent_via_heldpdesk_interface.png

He will successfully receive it.

email_received_on_client_side.png

Troubleshooting

  • Please change the settings for Redmine to HTTPS protocol (in administration - settings general) if you use the OAuth feature or some sort of LDAP. Otherwise, the plugin will fail to load on the desired site.

https_protocol.png

  • If you have this error:
[2024-10-18T10:11:53.588980 #3710] FATAL -- : [7c045f25-b2ee-46a9-ab1d-6b5a21841d22]
[7c045f25-b2ee-46a9-ab1d-6b5a21841d22] SystemStackError (stack level too deep):
[7c045f25-b2ee-46a9-ab1d-6b5a21841d22]
[7c045f25-b2ee-46a9-ab1d-6b5a21841d22] plugins/redmine_contacts_helpdesk/app/models/helpdesk_oauth_provider.rb:81:in `block in execute'

The issue was due to the OAuth certificate on Azure that had expired. You have to fix it by renewing the certificate.

Video demonstration

Was this article helpful? Yes  No
493 from 521 found this helpful