Fixes #270 - Documentation for common O365 / M365 errors

Co-authored-by: Ralf Schmid <[email protected]>

channels/microsoft365/common-errors.rst

@@ -0,0 +1,156 @@
+Common errors
+=============
+
+Here you can find some common errors in M365 context. Also have a look at
+the general :doc:`M365 documentation </channels/microsoft365/index>` for the
+configuration.
+
+Incorrect client ID
+-------------------
+
+**Error message:** AADSTS00016: Application with identifier
+'xxxxxxxx' was not found in the directory 'MSFT'. This can happen if the
+application has not been installed by the administrator of the tenant or
+consented to by any user in the tenant. You may have sent your authentication
+request to the wrong tenant.
+
+.. figure:: /images/channels/microsoft365/errors/wrong-id.png
+  :alt: Error message
+  :scale: 90%
+  :align: center
+
+In this case, please compare whether the client ID created in Zammad
+matches that in Azure for the Azure App.
+
+The Client ID can be found in Zammad under 
+Settings > Channels > Microsoft 365 > App Configuration. 
+See :doc:`here </channels/microsoft365/accounts>` how to find the client 
+ID in Azure and where to copy it to in Zammad.
+
+Wrong or expired client secret
+------------------------------
+
+**Error message:** 500: We're sorry, but something went wrong. 
+
+.. figure:: /images/channels/microsoft365/errors/zammad_error_500.png
+  :alt: Error message
+  :scale: 90%
+  :align: center
+
+This error occurs when the client uses an incorrect or expired client secret.
+
+.. warning:: **Important notice:**
+  We never ask the client for the client secret as this can potentially be a
+  security risk. We ask the customer to create a new client secret and copy the
+  value and not the ID to Zammad.
+
+See :doc:`here </channels/microsoft365/accounts>` for more information.
+
+Wrong tenant
+------------
+
+**Error message:** AADSTS0023: Specified tenant identifier 'xxxxxxxx' is
+neither a valid DNS name, nor a valid external domain.
+
+.. figure:: /images/channels/microsoft365/errors/wrong-tenant.png
+  :alt: Error message
+  :scale: 90%
+  :align: center
+
+If a wrong tenant is used in Zammad or the email account is not a member of
+the tenant created in Zammad, this error message occurs.
+
+In this case, please check if the tenant is entered correctly in
+Zammad, or remove the tenant completely.
+
+.. warning:: **Important notice:**
+  Once the tenant is completely removed, all email accounts can be created in
+  Zammad regardless of which tenant the email account is a member of.
+
+Request admin consent
+---------------------
+
+**Prompt:** approval required
+
+.. figure:: /images/channels/microsoft365/errors/admin-request.png
+  :alt: Error message
+  :scale: 90%
+  :align: center
+
+This message occurs when the admin tries to create an email account in Zammad
+that has not yet received approval from the Azure global admin.
+
+In our documentation,
+:doc:`step-by-step instructions </channels/microsoft365/accounts/account-setup>`
+can be found on how to request admin consent from Zammad.
+
+.. note::
+  The request for the admin consent can be bypassed by assigning the admin
+  consent in Azure to the App.
+
+  Home > App Registration > Manage > API Permission > Grant admin consent for
+  "MSFT".
+
+Missing permissions for the Azure user
+--------------------------------------
+
+**Error message:** Can't use Channel:Driver::SMTPAuthentificationError:Net::SMTPAuthentificationError
+
+.. figure:: /images/channels/microsoft365/errors/smtp-error-settings.png
+  :alt: Error message
+  :scale: 60%
+  :align: center
+
+  Error message in the M365 channel settings
+
+or
+
+.. figure:: /images/channels/microsoft365/errors/smtp-error-ticket.png
+  :alt: Error message
+  :scale: 90%
+  :align: center
+
+  Error message in the ticket
+
+This error occurs when the admin wants to create an email account in Zammad
+whose user does not have permission for SMTP authentication to the mail server.
+Please check the following two most common problems in this case.
+
+
+Private email account
+^^^^^^^^^^^^^^^^^^^^^
+
+If it is a private email account, the admin must grant the SMTP authentication
+permission to the user of the inbox. The permission is provided at
+https://admin.microsoft.com.
+
+Add the SMTP authentication permission under
+Users > Active Users > click on the User > Email > Manage Email Apps.
+
+.. figure:: /images/channels/microsoft365/errors/mail-permissions.png
+  :alt: Error message
+  :scale: 90%
+  :align: center
+
+
+Shared inbox
+^^^^^^^^^^^^
+
+If it is a shared inbox, you can try to enable the SMTP Authentication
+(``SmtpClientAuthenticationDisabled``) in the Azure shell. This isn't a Zammad
+problem, so we can only help to a limited extent here.
+
+To enable the SMTP Authentication, use the following commands:
+
+If not installed::
+
+   Import-Module ExchangeOnlineManagement
+
+Log in to Exchange using Powershell::
+
+   Connect-ExchangeOnline
+
+Switching on the SMTP authentication for a mailbox - also possible with a
+shared mailbox::
+
+   Set-CASMailbox -Identity [email protected] -SmtpClientAuthenticationDisabled $false  

channels/microsoft365/index.rst

@@ -9,6 +9,7 @@ Microsoft 365
    signatures
    settings
    email-headers
+   common-errors
 
 Connect a Microsoft 365 account (formerly “Office 365”) to Zammad.
 
@@ -29,3 +30,6 @@ Connect a Microsoft 365 account (formerly “Office 365”) to Zammad.
 .. include:: /channels/email/index.rst
    :start-after: .. start-after-migration
    :end-before: Extra Options for Self-Hosted Users
+
+:doc:`🛟 Common M365 errors </channels/microsoft365/common-errors>`
+   Here you can find common errors and how to fix them.

locale/admin-docs.pot

@@ -8,7 +8,7 @@ msgid ""
 msgstr ""
 "Project-Id-Version: Zammad pre-release\n"
 "Report-Msgid-Bugs-To: \n"
-"POT-Creation-Date: 2023-08-02 16:21+0100\n"
+"POT-Creation-Date: 2023-08-04 09:52+0200\n"
 "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
 "Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
 "Language-Team: LANGUAGE <[email protected]>\n"
@@ -3734,6 +3734,164 @@ msgstr ""
 msgid "Contact your administrator if you don’t have access to an admin account."
 msgstr ""
 
+#: ../channels/microsoft365/common-errors.rst:2
+msgid "Common errors"
+msgstr ""
+
+#: ../channels/microsoft365/common-errors.rst:4
+msgid "Here you can find some common errors in M365 context. Also have a look at the general :doc:`M365 documentation </channels/microsoft365/index>` for the configuration."
+msgstr ""
+
+#: ../channels/microsoft365/common-errors.rst:9
+msgid "Incorrect client ID"
+msgstr ""
+
+#: ../channels/microsoft365/common-errors.rst:11
+msgid "**Error message:** AADSTS00016: Application with identifier 'xxxxxxxx' was not found in the directory 'MSFT'. This can happen if the application has not been installed by the administrator of the tenant or consented to by any user in the tenant. You may have sent your authentication request to the wrong tenant."
+msgstr ""
+
+#: ../channels/microsoft365/common-errors.rst:None
+#: ../channels/microsoft365/common-errors.rst:None
+#: ../channels/microsoft365/common-errors.rst:None
+#: ../channels/microsoft365/common-errors.rst:None
+#: ../channels/microsoft365/common-errors.rst:104
+#: ../channels/microsoft365/common-errors.rst:113
+#: ../channels/microsoft365/common-errors.rst:None
+msgid "Error message"
+msgstr ""
+
+#: ../channels/microsoft365/common-errors.rst:22
+msgid "In this case, please compare whether the client ID created in Zammad matches that in Azure for the Azure App."
+msgstr ""
+
+#: ../channels/microsoft365/common-errors.rst:25
+msgid "The Client ID can be found in Zammad under Settings > Channels > Microsoft 365 > App Configuration. See :doc:`here </channels/microsoft365/accounts>` how to find the client ID in Azure and where to copy it to in Zammad."
+msgstr ""
+
+#: ../channels/microsoft365/common-errors.rst:31
+msgid "Wrong or expired client secret"
+msgstr ""
+
+#: ../channels/microsoft365/common-errors.rst:33
+msgid "**Error message:** 500: We're sorry, but something went wrong."
+msgstr ""
+
+#: ../channels/microsoft365/common-errors.rst:40
+msgid "This error occurs when the client uses an incorrect or expired client secret."
+msgstr ""
+
+#: ../channels/microsoft365/common-errors.rst:42
+msgid "**Important notice:** We never ask the client for the client secret as this can potentially be a security risk. We ask the customer to create a new client secret and copy the value and not the ID to Zammad."
+msgstr ""
+
+#: ../channels/microsoft365/common-errors.rst:47
+msgid "See :doc:`here </channels/microsoft365/accounts>` for more information."
+msgstr ""
+
+#: ../channels/microsoft365/common-errors.rst:50
+msgid "Wrong tenant"
+msgstr ""
+
+#: ../channels/microsoft365/common-errors.rst:52
+msgid "**Error message:** AADSTS0023: Specified tenant identifier 'xxxxxxxx' is neither a valid DNS name, nor a valid external domain."
+msgstr ""
+
+#: ../channels/microsoft365/common-errors.rst:60
+msgid "If a wrong tenant is used in Zammad or the email account is not a member of the tenant created in Zammad, this error message occurs."
+msgstr ""
+
+#: ../channels/microsoft365/common-errors.rst:63
+msgid "In this case, please check if the tenant is entered correctly in Zammad, or remove the tenant completely."
+msgstr ""
+
+#: ../channels/microsoft365/common-errors.rst:66
+msgid "**Important notice:** Once the tenant is completely removed, all email accounts can be created in Zammad regardless of which tenant the email account is a member of."
+msgstr ""
+
+#: ../channels/microsoft365/common-errors.rst:71
+msgid "Request admin consent"
+msgstr ""
+
+#: ../channels/microsoft365/common-errors.rst:73
+msgid "**Prompt:** approval required"
+msgstr ""
+
+#: ../channels/microsoft365/common-errors.rst:80
+msgid "This message occurs when the admin tries to create an email account in Zammad that has not yet received approval from the Azure global admin."
+msgstr ""
+
+#: ../channels/microsoft365/common-errors.rst:83
+msgid "In our documentation, :doc:`step-by-step instructions </channels/microsoft365/accounts/account-setup>` can be found on how to request admin consent from Zammad."
+msgstr ""
+
+#: ../channels/microsoft365/common-errors.rst:88
+msgid "The request for the admin consent can be bypassed by assigning the admin consent in Azure to the App."
+msgstr ""
+
+#: ../channels/microsoft365/common-errors.rst:91
+msgid "Home > App Registration > Manage > API Permission > Grant admin consent for \"MSFT\"."
+msgstr ""
+
+#: ../channels/microsoft365/common-errors.rst:95
+msgid "Missing permissions for the Azure user"
+msgstr ""
+
+#: ../channels/microsoft365/common-errors.rst:97
+msgid "**Error message:** Can't use Channel:Driver::SMTPAuthentificationError:Net::SMTPAuthentificationError"
+msgstr ""
+
+#: ../channels/microsoft365/common-errors.rst:104
+msgid "Error message in the M365 channel settings"
+msgstr ""
+
+#: ../channels/microsoft365/common-errors.rst:106
+msgid "or"
+msgstr ""
+
+#: ../channels/microsoft365/common-errors.rst:113
+msgid "Error message in the ticket"
+msgstr ""
+
+#: ../channels/microsoft365/common-errors.rst:115
+msgid "This error occurs when the admin wants to create an email account in Zammad whose user does not have permission for SMTP authentication to the mail server. Please check the following two most common problems in this case."
+msgstr ""
+
+#: ../channels/microsoft365/common-errors.rst:121
+msgid "Private email account"
+msgstr ""
+
+#: ../channels/microsoft365/common-errors.rst:123
+msgid "If it is a private email account, the admin must grant the SMTP authentication permission to the user of the inbox. The permission is provided at https://admin.microsoft.com."
+msgstr ""
+
+#: ../channels/microsoft365/common-errors.rst:127
+msgid "Add the SMTP authentication permission under Users > Active Users > click on the User > Email > Manage Email Apps."
+msgstr ""
+
+#: ../channels/microsoft365/common-errors.rst:137
+msgid "Shared inbox"
+msgstr ""
+
+#: ../channels/microsoft365/common-errors.rst:139
+msgid "If it is a shared inbox, you can try to enable the SMTP Authentication (``SmtpClientAuthenticationDisabled``) in the Azure shell. This isn't a Zammad problem, so we can only help to a limited extent here."
+msgstr ""
+
+#: ../channels/microsoft365/common-errors.rst:143
+msgid "To enable the SMTP Authentication, use the following commands:"
+msgstr ""
+
+#: ../channels/microsoft365/common-errors.rst:145
+msgid "If not installed::"
+msgstr ""
+
+#: ../channels/microsoft365/common-errors.rst:149
+msgid "Log in to Exchange using Powershell::"
+msgstr ""
+
+#: ../channels/microsoft365/common-errors.rst:153
+msgid "Switching on the SMTP authentication for a mailbox - also possible with a shared mailbox::"
+msgstr ""
+
 #: ../channels/microsoft365/email-headers.rst:3
 msgid "Email header manipulation in Microsoft 365 channels work **just like in email channels**, so this article is lifted verbatim from :doc:`here </channels/email/email-headers>`."
 msgstr ""
@@ -3750,22 +3908,30 @@ msgstr ""
 msgid "Microsoft 365"
 msgstr ""
 
-#: ../channels/microsoft365/index.rst:13
+#: ../channels/microsoft365/index.rst:14
 msgid "Connect a Microsoft 365 account (formerly “Office 365”) to Zammad."
 msgstr ""
 
-#: ../channels/microsoft365/index.rst:19
+#: ../channels/microsoft365/index.rst:20
 msgid "Microsoft 365 channels are a specialized kind of :doc:`📨 email channel </channels/email/index>`."
 msgstr ""
 
-#: ../channels/microsoft365/index.rst:22
+#: ../channels/microsoft365/index.rst:23
 msgid "This documentation part does not cover :doc:`🗝 user authentication </settings/security/third-party/microsoft>`."
 msgstr ""
 
-#: ../channels/microsoft365/index.rst:25
+#: ../channels/microsoft365/index.rst:26
 msgid "If you’re already familiar with email channels, you can skip most of this—but **watch out for the “Accounts” section**, which has a few extra quirks due to Microsoft’s strict security measures."
 msgstr ""
 
+#: ../channels/microsoft365/index.rst:34
+msgid ":doc:`🛟 Common M365 errors </channels/microsoft365/common-errors>`"
+msgstr ""
+
+#: ../channels/microsoft365/index.rst:35
+msgid "Here you can find common errors and how to fix them."
+msgstr ""
+
 #: ../channels/microsoft365/settings.rst:3
 msgid "Settings in Microsoft 365 channels are **just like settings in email channels**, so this article is lifted verbatim from :doc:`here </channels/email/settings>`."
 msgstr ""