Introduction

The Microsoft calendar plugin integrates events from your Microsoft 365 (formerly Office 365) calendars into Joomla through DPCalendar. Business and personal accounts are supported.

The most convenient way to make your Microsoft calendars accessible in DPCalendar is to import them, because the cryptic keys and tokens from the Microsoft graph API are obtained during the import process. To be able to import the calendars you need to get first the required credentials from the Microsoft Azure portal as described below. During the import process are all calendars of all available users imported.

To get a bigger picture how external calendars are handled inside DPCalendar read the article Integration/Import external calendars.

Tenant ID, Client ID and Client Secret

To be able to import your Microsoft calendars you need a tenant ID (when you have a business account with an organization), client ID and client secret from the Microsoft Azure portal. This credentials are used to make authenticated requests against the Microsoft graph API endpoint. It is called OAuth authentication and allows you to revoke the credentials at any time and doesn't expose your private username and password.

1. Sign in to the Microsoft Azure portal.
2. If your account gives you access to more than one tenant, select your account in the top right corner, and set your portal session to the Azure AD tenant that you want.
3. In the left-hand navigation pane, select the "Microsoft Entra ID" (formerly the Azure Active Directory) service.
4. Create a new app by clicking on "Manage" > "App registrations" > "New registration".
5. When the "Register an application" page appears, enter your application's registration information. Choose the account type, either a tenant or a personal one. If you use a personal account, set as redirect uri https://{web site url}/plugins/dpcalendar/microsoft/import.php.
6. Click on "Register".
7. If you have a business account and want to import a specific tenant, then click on the app list on the new app and then on "API permissions". DPCalendar needs a couple of permissions to be able to work with the events, they are explained below. All of the permissions must be "Application" permissions" and NOT "Delegated permissions". After you selected them, grant admin consent for them.
   • Calendars.ReadWrite
     To read the calendar data.
   • MailboxSettings.Read
     To get the categories of the events for individual event coloring.
   • User.Read.All
     To fetch the users during import.
8. In the same screen click on "Certificates & secrets" and create a new client secret. Copy the value to a temporary file as you need it later for the import and the value can be seen only once.

Attachments

The Microsoft graph API does support attachments. They are stored in the cache folder of your Joomla installation temporary. The attachments itself are rendered in a separate layout in the file /plugins/dpcalendar/microsoft/tmpl/attachments.php. If you want to change that, then you need to copy it to /templates/{your template}/html/plg_dpcalendar_microsoft/attachments.php and change it to your needs.

Colors

Every event can be assigned to multiple categories. Each of these categories contains a color from one of the 24 presets. To assign the event categories to a real color, we use a template file (/plugins/dpcalendar/microsoft/tmpl/colors.php) to make the mapping. If you want to change that, then you need to copy it to /templates/{your template}/html/plg_dpcalendar_microsoft/colors.php and return an array with your preferred colors.

Troubleshooting

• 400 Error: redirect_uri_mismatch
  This happens when authorized redirect URIs values are incorrect and do not match your web site. Keep in mind also the protocol (http/s) and the port do need to be correct.
• 403 Error with forbidden screen on import
  A firewall rule is interfering here. If you have a security extension installed like Admin Tools check their settings. If your hoster has a web firewall active, contact them and check if they can add a rule to allow these requests. In mod security, there is a rule with the number 336141 which should be disabled.
• 403 Error on your Joomla site
  Too strict .htaccess rules can also prevent the callback from being processed on your Joomla site after the grant. The 403 error can also occur when an attachment is opened. Make sure that htaccess is not blocking direct file access in the folder /cache/plg_dpcalendar_microsoft/attachments.
• Admin Tools error on import
  Admin tools assumes the one time calendar import is a malicious attack, even it is not. To make the import work, disable the "Protect against common file injection attacks" rule in the "Basic Security Settings". This has to be done only once when importing the calendars and should be enabled again when the import is finished.

DPCalendar Options

These settings are the same for every calendar configured in the plugin.

Plugin Options