Improved Documentation

ksainc · Feb 9, 2024 · 77df52a · 77df52a
1 parent 4615833
commit 77df52a
Show file tree

Hide file tree

Showing 11 changed files with 70 additions and 8 deletions.
diff --git a/README.md b/README.md
@@ -2,25 +2,27 @@
 
 EWS (Exchange Web Services) integration allows you to automatically bidirectionally synchronize your Nextcloud calendars and contacts with an external EWS protocol capable system like Microsoft Exchange, Kerio Connect, etc
 
-![EWS Connector](https://github.com/ksainc/integration_ews/blob/62a4ae5081526009e310ea9e9734809a769697cf/img/EWS%20Notification%20Screen.png?raw=true 'Notifications')
+![EWS Connector](docs/images/EWS%20Notification%20Screen.png 'Notifications')
 
 ## How to use
 
 Before proceeding further please make sure you read the following sections, Requirements, Installation, Capabilities and Limitations.
 
-After the app is installed and enabled in Nextcloud you should have a new section call "Connected Accounts" under "Personal Settings", if you don't see it refresh the browser window.
+After the app is installed and enabled in Nextcloud you should have a new section called "Connected Accounts" under "Personal Settings", if you don't see it refresh the browser window.
 
-![EWS Connector](https://github.com/ksainc/integration_ews/blob/969e0f6a2bfe28e4197c0cc941333a43fce25b5c/img/EWS%20Initial%20Screen.png?raw=true 'Initial Configuration')
+![EWS Connector](docs/images/EWS%20Initial%20Screen.png 'Initial Configuration')
 
-On the initial screen you will be asked for the account information (hostname, username, password) for the remote system. After filling in the required information, press the "Connect" button. The app will then attempt an initial connection to the remote system, if successful, it will retrieve a list of all available calendars and contacts folders from the remote system, and display them below the authentication section.
+### On-premises / Self-Hosted Exchange
+On the initial screen you will be asked for the account information hostname (formats IP/domain), username (formats "[email protected]" or "domain\username"), password for the remote system. After filling in the required information, press the "Connect" button. The app will then attempt an initial connection to the remote system, if successful, it will retrieve a list of all available contacts, calendar and task folders from the remote system, and display them below the authentication section.
 
-![EWS Connector](https://github.com/ksainc/integration_ews/blob/969e0f6a2bfe28e4197c0cc941333a43fce25b5c/img/EWS%20Connected%20Screen.png?raw=true 'Correlation Configuration')
+### Exchange 365
+To connect to a Office 365 Account the system administrator for your organization needs to pre-setup the appropriate settings in both the Office 365 control panel and Nextcloud. Please see [Microsoft Exchange 365 Configuration](docs/o365.md)
 
-Once your accounts is connected and the remote calendars and contacts folders are listed similar to the image above. The next step is to create some correlations (associations/relations/links) between the local and remote, calendar or contacts collections by clicking the link icon beside the remote collection name and selecting the local calendar or contacts address book to associate with and click save. PLEASE READ THE WARNING BELOW BEFORE CLICK SAVE
+After the above inital configuration has been completed. On the initial configuration screen change the provider to "Microsoft Exchange 365". Then press the connect button, a popup will appear asking for your account information, upon successful authentication the app will then attempt an initial connection to the remote system, if successful, it will retrieve a list of all available contacts, calendar and task folders from the remote system, and display them below the authentication section.
 
-##### WARNING
+![EWS Connector](docs/images/EWS%20Connected%20Screen.png 'Correlation Configuration')
 
-This is an initial alpha release. Although the app has been thoroughly tested in our environment with live data, we recommend creating a new address book and calendar in both the local and remote systems and linking them together first. Testing the functionality then once satisfied with the results, unlink the test address books/calendars and linking to your live data.
+Once your accounts is connected and the remote calendars and contacts folders are listed, similar to the image above. The next step is to create some correlations (associations/relations/links) between the local and remote, contacts, calendar or task collections by clicking the link icon beside the remote collection name and selecting the local addressbook, calendar or tasks list to associate with and click save.
 
 ## How it works
 

diff --git a/docs/faq.md b/docs/faq.md
diff --git a/img/EWS Connected Screen.png → docs/images/EWS Connected Screen.png b/img/EWS Connected Screen.png → docs/images/EWS Connected Screen.png
diff --git a/img/EWS Initial Screen.png → docs/images/EWS Initial Screen.png b/img/EWS Initial Screen.png → docs/images/EWS Initial Screen.png
diff --git a/img/EWS Notification Screen.png → docs/images/EWS Notification Screen.png b/img/EWS Notification Screen.png → docs/images/EWS Notification Screen.png
diff --git a/img/EWS Selection Screen.png → docs/images/EWS Selection Screen.png b/img/EWS Selection Screen.png → docs/images/EWS Selection Screen.png
diff --git a/docs/images/ms365-permissions.png b/docs/images/ms365-permissions.png
diff --git a/docs/images/ms365-registration-1.png b/docs/images/ms365-registration-1.png
diff --git a/docs/images/ms365-registration-2.png b/docs/images/ms365-registration-2.png
diff --git a/docs/images/ms365-secret.png b/docs/images/ms365-secret.png
diff --git a/docs/o365.md b/docs/o365.md
@@ -0,0 +1,60 @@
+# Microsoft Exchange 365 Configuration
+
+For the integration app to work with Exchange 365, you will require 3 pieces of information, Tenate ID, Application ID and Application Secret, this information needs to be entered in the "EWS Connector" section in the "Administrator" settings in Nextcloud.
+
+## Step 1 - Create Application Registration
+
+- Login to the Azure control panel [https://portal.azure.com](https://portal.azure.com).
+
+- Navigate to the "Microsoft Entra ID" section.
+
+- Navigate to the "App registrations" section (left menu).
+
+- Click + New Registration and fill in the following values
+
+    - Name: NC EWS Connector
+    - Types: Accounts in this organizational directory only (MSFT only - Single tenant)
+    - Redirect URI: (Web) https://fqdn.domain.tdl/apps/integration_ews/connect-ms365 (replace fqdn.domain.tdl with you NC domain)
+
+![Part 1](images/ms365-registration-1.png)
+
+![Part 2](images/ms365-registration-2.png)
+
+
+## Step 2 - Configure API permissions
+
+- Make sure you are in the "NC EWS Connector" settings section, if not click on the "NC EWS Connector" app name in the "App registrations" screen.
+
+- Navigate to the "API permissions" section.
+
+- Click "+ add permissions", then in the side popout, click "APIs my organization uses" then "Office 365 Exchange Online" and "Delegated permissions". Scroll down to "EWS" and select "EWS.AccessAsUser.All". Then click the "add permissions" button.
+
+- You should now have the following permissions as below, you can remove any other permissions that exist.
+
+![Permissions](images/ms365-permissions.png)
+
+
+## Step 3 - Configure Secret
+
+- Make sure you are in the "NC EWS Connector" settings section, if not click on the "NC EWS Connector" app name in the "App registrations" screen.
+
+- Navigate to the "Certificates & secrets" section.
+
+- Click "+ new client secret", then in the side popout, fillin in the description "Production" and select the expiry time. Then click "add" button.
+
+- After the screen updates, copy the "Value" as this can not be retrieved later.
+
+- You should now have the following secret as below.
+
+![Secret](images/ms365-secret.png)
+
+
+## Step 4 - Configure Nextcloud
+
+- Make sure you are in the "NC EWS Connector" settings section, if not click on the "NC EWS Connector" app name in the "App registrations" screen.
+
+- Navigate to the "Overview" section.
+
+- Copy the Tenet Id, Application Id, and Secret (from step 3) to the "EWS Connector" section in the "Administraion" settings in Nextcloud.
+
+## Step 5 - Enjoy the APP