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
Intrexx Version 18.03 or higher
A licensed Connector for Microsoft Office 365 -
the license has to be assigned to the portal where the
connection
is configured.
An account for Microsoft Office 365 Business / Personal (with limitations)
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:
Files.ReadWrite.All
Files.ReadWrite.AppFolder
Files.ReadWrite.Selected
User.Read
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".
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:
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.