Connector for Microsoft Office 365

1. General

So that third-party applications (such as Intrexx) may access the information in a Microsoft Office 365 organization, general access must be granted by a Microsoft Office 365 administrator of the respective organization whose information is accessed. This setting can be made in the Microsoft Office 365 Admin Center. To access Microsoft Office 365, and the data it contains with, with an application, the accessing application needs to be registered on Microsoft Office 365 (more precisely Azure Active Directory). Every access takes place via Microsoft Office 365 Graph and its API. The app is given a unique ID during the registration; this is used by Microsoft Office 365 to identify the app. Furthermore, a password is provided that it can use to authenticate itself against Microsoft Office 365. Which Microsoft Office 365 organization can be access is determined based on the user, who registers the app (e.g. the Microsoft Office 365 company area where the publishing employee is entered). As another important aspect, the so-called Scope is defined. This is the area within Microsoft Office 365 that may be used (Files, Contacts, Mail etc.). The maximum permissions (CREATE, READ, READWRITE etc.) can be provided for the respective defined scope. The permissions context, used later when access is made, orientates itself to the permissions of the accessing user, but is limited to the permissions defined here at the application level.

2. Requirements

3. Settings in the Microsoft Office 365 Admin Center




For a third-party application - Intrexx in this case - to access information in a Microsoft Office 365 organisation, an administrator must first provide permission. The corresponding setting can be found in the Microsoft Office Admin Center under Settings / Services & add-ins / Integrated apps.



Activate the setting "Let people in your organization decide whether third-party apps can access their Office 365 information". This allows external applications to access data in the Microsoft Office 365 client. Every accessing application needs to be registered individually.

4. Register app

So that Intrexx can access the data in Microsoft Office 365, the portal must be registered as an app on Microsoft Office 365 (more precisely on Azure Active Directory) under the URL https://apps.dev.microsoft.com/portal/register-app. This page is available via a button in the configuration dialog when setting up the connection. The registration is made in the Azure Active Directory instance where the current user is logged in, which is also used for managing the currently logged in account.



Enter a name for the app here. The name may only consist of letters [a-zA-Z] and numbers [0-9], as well as hyphens and underscores. Then click on "Create".



4.1. Application ID

The ID for the application is shown here.

4.2. Application Secrets

Click on "Generate New Password". The password will then be displayed. As this is a one-time instance, you should note this password now so that it can be used later in the OAUTH2 settings dialog in Intrexx.

4.3. Platforms

Click on "Add Platform".



Select "Web" here.

4.4. Redirect-URLs




Enter the Auth2 URL in the format https://<Domain>/<Portalname>/oauth2 that Microsoft should be redirected to (e.g. https://localhost:8080/myportal/oauth2). Please note that the portal name is case-sensitive. This URL is entered later in the general settings of the connection.

4.5. Owners




As the currently logged in user, you are automatically defined as the owner. Additional users can be specified by clicking on "Add user"; these users can then use the app in their context. At least one owner is required at all times.

4.6. Microsoft Graph Permissions (Scope)




Every access takes place via the Microsoft Office 365 Graph and its API. Which Microsoft Office 365 organization can be access is determined based on the user, who registers the app (e.g. the Microsoft Office 365 company area where the publishing employee is entered). As another important aspect, the so-called Scope is defined. This is the area within Microsoft Office 365 that may be used (Files, Contacts, Mail etc.). The maximum permissions (CREATE, READ, READWRITE etc.) can be provided for the respective defined scope. The permissions context, used later when access is made, orientates itself to the permissions of the accessing user, but is limited to the permissions defined here at the application level.

Delegated permissions

These permissions are used for the interactive user access. Click "Add" here to provide permissions. At least the following permissions are required: Here is a list of all possible options:

Files.Read the user can read their files
Files.Read.All the user can read all files that they have permission for
Files.Read.Selected the application can read files that the user selected (preview)
Files.ReadWrite the user can read/write their files
Files.ReadWrite.All the user can read/write all files that they have permission for
Files.ReadWrite.Selected the application can read/write files that the user selected (preview)
Files.ReadWrite.AppFolder the application can read/write files in the app directory
offline_access Optional if the Microsoft Office 365 session of the portal user should be refreshed automatically after it has expired.

These permissions are entered later in the configuration dialog of the connection under "Microsoft Office 365 Scope". Separate each of the permissions with a space when doing so (e.g. Files.ReadWrite.All Files.ReadWrite.AppFolder Files.ReadWrite.Selected User.Read).

Application permissions

These permissions are used for accesses made by processes. Before access can be made in processes, a Microsoft Office 365 administrator must validate the access in Microsoft Office 365 for the current app registration. The following options are available:

Files.Read.All the application can read all files within the site collection without a logged-in user
Files.ReadWrite.All the application can read/write all files within the site collection without a logged-in user
Before the first access is made in Intrexx, a Microsoft O365 administrator must then open the following URL to validate the admin permissions for this access. This validation is valid for a time until the action needs to be repeated.
GET https://login.microsoftonline.com/<tenant>/adminconsent?
client_id=<client_id>
&state=12345
&redirect_uri=http://localhost/myapp/permissions
Replace <tenant> with the Microsoft Office 365 tenant ID. This can be indentified in the Azure Active Directory. <client_id> corresponds to the Application ID from the registration. Furthermore, the URL for the Microsoft login server needs to be modified in the Connector configuration so that the tenant ID is used instead of "common".
https://login.microsoftonline.com/common/oauth2/v2.0/token
https://login.microsoftonline.com/common/oauth2/v2.0/authorize
is therefore changed to
https://login.microsoftonline.com/<Tenant-ID>/oauth2/v2.0/token
https://login.microsoftonline.com/<Tenant-ID>/oauth2/v2.0/authorize
Once the permissions are validated, access can be made in Intrexx. Click here for more information.

Profile

These settings are optional and are not absolutely necessary.

Save settings

Once all of the data has been entered, click on "Save" on the page. A list of all of the apps created by you can be found here: https://apps.dev.microsoft.com.

5. IIS configuration

If you use the ISS Web Server IIS for your Intrexx portal, the IIS URL Rewrite 2.0 Module needs to be installed. The 32-bit versions can be downloaded here and the 64-bit version here. Once this is installed, open the Intrexx virtual website and then the URL Rewrite Module in the IIS Manager.



Enter the corresponding entries for the OAuth2 callbacks here. Enter the expression "Default.asp?urn:schemas-unitedplanet-de:ixservlet:name=oAuth2CallbackServlet" in the "Rewrite URL" field.

6. Tomcat configuration

If you are using Tomcat as the web server, the redirect for OAuth2 must be entered in the "server.xml" file in the installation directory /tomcat/conf. In the Host section, search for the following entry at the end of the file:
<Valve className="org.apache.catalina.valves.AccessLogValve" directory="logs" pattern="%h %l %u %t "%r" %s %b %D "%{User-Agent}i"" prefix="localhost_access_log" suffix=".txt"/>
Add the following entry underneath
<Valve className="org.apache.catalina.valves.rewrite.RewriteValve" />
Afterwards, create a text file called "rewrite.config" with a text editor of your choice. Enter the following there:
RewriteRule /<portalname>/oauth2?(.*) /<portalname>/default.ixsp?urn:schemas-unitedplanet-de:ixservlet:name=oAuth2CallbackServlet&%{QUERY_STRING} [NC,L]
Please note that the portal name is case-sensitive. You can identify the portal name in the "Context" field in the portal properties. Move the rewrite-config file to the installation directory /tomcat/conf/Catalina/<host>. Afterwards, restart the Intrexx Tomcat Servlet Containers.

7. Integrate certificates

Certificates can be integrated in the portal properties. There, add the certificates from the following URLs Afterwards, restart the portal service.

8. Create connection

All information about configuring a connection to Microsoft Office 365 can be found here.

8. Integrate Microsoft Office 365 files into applications

All information about configuring your portal applications to display Microsoft Office 365 files can be found here.

9. Authentication

Authentication to the Azure Active Directory takes place via OAuth2. As soon as the Intrexx user wants to access information in Microsoft Office 365, they need to be authenticated against the Azure Active Directory. When the user, or rather the account, of the Intrexx user has not yet been authenticated in the current session, the user will be redirected to the Microsoft Office 365 page where they can enter their Microsoft Office 365 login data to log in to the Azure Active Directory. Once they have logged in to the Azure Active Directoy successfully, Intrexx is given a token from the Azure Active Directoy that enables Intrexx to have access in the scope of the application and the permission context of the logged-in user.

OAuth2

OAuth2 enables web application users (Microsoft Office 365, the service provider) to exchange private resources, such as files, photos, contacts, appointments, with other web applications (in our case Intrexx, the consumer) without needing to disclose the username and password of the service provider application (Office 365) to the consumer application (Intrexx). This is achieved by providing a token for the transfer of permission information. The key question in this context is as follows: May Intrexx user XY, who has authenticated correctly in Intrexx, exchange their data, which is stored in Microsoft Office 365, with Intrexx? This means that the Microsoft Office 365 authentication data of the user is not made known in Intrexx directly.

11. More information

Microsoft Office 365 in processes
Import / Export