Connector für Microsoft Office 365

1. Allgemeines

Als Grundvoraussetzung, dass Drittanbieter-Applikationen (wie z.B. Intrexx) auf die Informationen in einer Microsoft Office 365-Organisation zugreifen dürfen, muss der generelle Zugriff durch einen Microsoft Office 365-Administrator derjenigen Organisation, auf deren Informationen zugegriffen wird, erlaubt werden. Die Einstellung ist im Microsoft Office 365-Admin Center zu finden. Um mit einer Applikation auf Microsoft Office 365 und die darin enthaltenen Daten zugreifen zu können, muss die zugreifende Applikation bei Microsoft Office 365 (genauer beim Azure Active Directory) registriert werden. Alle Zugriffe erfolgen über den Microsoft Office 365 Graph und dessen API. Mit der Registrierung bekommt die App eine eindeutige ID, mit der sie von Microsoft Office 365 identifiziert werden kann. Außerdem wird ein Kennwort zugeteilt, mit dem sie sich gegenüber Microsoft Office 365 authorisieren kann. Über den Benutzer, der die App registriert, wird festgelegt, auf welche Microsoft Office 365-Organisation zugegriffen werden kann (z.B. der Microsoft Office 365-Firmenbereich, in dem der freigebende Mitarbeiter eingetragen ist. Als weiterer wichtiger Aspekt wird der sogenannte Scope festgelegt. Das ist der Bereich innerhalb von Microsoft Office 365, der verwendet werden darf (Files, Contacts, Mail etc.). Für den festgelegten Bereich können jeweils die maximalen Berechtigungen (CREATE, READ, READWRITE etc.) vergeben werden. Der später beim Zugriff verwendete Rechtekontext richtet sich dann nach den Rechten des zugreifenden Benutzers, kann aber nur maximal die hier auf Applikationsebene definierten Rechte umfassen.

2. Voraussetzungen

3. Einstellung im Microsoft Office 365-Admin Center




Der Zugriff auf die Informationen in einer Microsoft Office 365-Organisation durch Drittanbieter-Applikationen - in diesem Fall Intrexx - muss von einem Microsoft Office 365-Administrator erlaubt werden. Die entsprechende Einstellung finden Sie im Microsoft Office 365-Admin Center unter Einstellungen / Dienste und Add-Ins / Integrierte Apps.



Setzen Sie hier die Einstellung "Personen in Ihrer Organisation können entscheiden, ob Apps von Drittanbietern auf ihre Microsoft Office 365-Informationen zugreifen dürfen". Damit wird der Zugriff von Fremdapplikationen auf die Daten im Microsoft Office 365-Mandanten zugelassen. Jede zugreifende Applikation muss einzeln registriert werden.

4. App registrieren

Damit Intrexx auf die Daten in Microsoft Office 365 zugreifen kann, muss das Portal als App bei Microsoft Office 365 (genauer beim Azure Active Directory) unter der URL https://apps.dev.microsoft.com/portal/register-app registriert werden. Diese Seite erreichen Sie auch beim Einrichten der Verbindung über eine Schaltfläche im Konfigurationsdialog. Die Registrierung erfolgt in der Azure Active Directory Instanz, bei der der aktuelle Anwender angemeldet ist, die auch für die Verwaltung des aktuell angemeldeten Kontos verwendet wird.



Tragen Sie einen Namen für Ihre App ein. Der Name darf nur die Buchstaben [a-zA-Z] und die Zahlen [0-9] enthalten, sowie Unterstrich und Bindestrich. Klicken Sie dann auf "Create".

4.1. Anwendungs-ID

Hier finden Sie die ID der App.

4.2. Anwendungsgeheimnisse

Klicken Sie hier auf "Neues Kennwort generieren". Das Kennwort wird daraufhin angezeigt. Da dies ein einmaliger Vorgang ist, sollten Sie das Kennwort jetzt für die spätere Verwendung im Intrexx OAuth2-Einstellungsdialog notieren. Es kann hier jederzeit ein neues Kennwort erzeugt werden.

4.3. Plattformen

Klicken Sie auf "Plattform hinzufügen".



Wählen Sie hier "Web" aus.

4.4. Umleitungs-URL




Tragen Sie hier die OAuth2-Url in der Form https://<Domain>/<Portalname>/oauth2 ein, zu der Microsoft umgeleitet wird (z.B. https://localhost:8080/meinportal/oauth2). Bitte beachten Sie die Groß-/Kleinschreibung beim Portalnamen. Diese URL geben Sie später auch in den Allgemeinen Einstellungen der Verbindung an.

4.5. Besitzer




Hier sind Sie als aktuell angemeldeter Benutzer automatisch als Besitzer eingetragen. Mit Klick auf "Besitzer hinzufügen" können weitere Besitzer angegeben werden, die die App dann in ihrem Kontext verwenden können. Es muss immer mindestens ein Besitzer angegeben werden.

4.6. Microsoft Graph Berechtigungen (Scope)




Alle Zugriffe erfolgen über den Microsoft Office 365 Graph und dessen API. Über den Benutzer, der die App registriert, wird festgelegt, auf welche Microsoft Office 365-Organisation zugegriffen werden kann (z.B. der Microsoft Office 365-Firmenbereich, in dem der freigebende Mitarbeiter eingetragen ist). Als weiterer wichtiger Aspekt wird der sogenannte Scope festgelegt. Das ist der Bereich innerhalb von Microsoft Office 365, der verwendet werden darf (Files, Contacts, Mail etc.). Für den festgelegten Bereich können jeweils die maximalen Berechtigungen (CREATE, READ, READWRITE etc.) vergeben werden. Der später beim Zugriff verwendete Rechtekontext richtet sich dann nach den Rechten des zugreifenden Benutzers, kann aber nur maximal die hier auf Applikationsebene definierten Rechte umfassen.

Delegierte Berechtigungen

Diese Berechtigungen werden für den interaktiven Benutzerzugriff verwendet. Klicken Sie hier auf "Hinzufügen", um Rechte zu erteilen. Es werden mindestens die Rechte benötigt. Hier eine Liste der möglichen Optionen:

Files.Read der Anwender kann seine Dateien lesen
Files.Read.All der Anwender kann alle Dateien lesen, auf die er berechtigt ist
Files.Read.Selected die Anwendung kann die Dateien lesen, die der Anwender auswählt (Preview)
Files.ReadWrite der Anwender kann seine Dateien lesen/schreiben
Files.ReadWrite.All der Anwender kann alle Dateien lesen/schreiben, auf die er berechtigt ist
Files.ReadWrite.Selected die Anwendung kann die Dateien lesen/schreiben, die der Anwender auswählt (Preview)
Files.ReadWrite.AppFolder die Anwendung kann Dateien im App-Verzeichnis lesen/schreiben
offline_access Optional, wenn die Microsoft Office 365-Sitzung des Portalbenutzers automatisch nach Ablauf erneuert werden soll

Diese Rechte werden später im Konfigurationsdialog der Verbindung Verbindung unter "Microsoft Office 365 Scope" eingetragen. Trennen Sie die einzelnen Rechte dabei mit einem Leerzeichen (z.B. Files.ReadWrite.All Files.ReadWrite.AppFolder Files.ReadWrite.Selected User.Read).

Anwendungsberechtigungen

Diese Berechtigungen werden für den für Zugriffe durch Prozesse verwendet. Bevor der erste Zugriff in Prozessen stattfindet, muss ein Microsoft Office 365-Administrator für die aktuelle App-Registrierung den Zugriff in Microsoft Office 365 bestätigen. Folgende Optionen sind möglich:

Files.Read.All Die Anwendung kann alle Dateien innerhalb der Sitecollection ohne angemeldeten Benutzer lesen
Files.ReadWrite.All Die Anwendung kann alle Dateien innerhalb der Sitecollection ohne angemeldeten Benutzer lesen/schreiben

Anschließend muss vor dem ersten Zugriff in Intrexx ein Microsoft O365-Administrator die folgende URL aufrufen, um die Admin-Berechtigungen für diesen Zugriff zu bestätigen. Diese Bestätigung ist dann eine zeitlang gültig, bis die Aktion wiederholt werden muss. 
GET https://login.microsoftonline.com/<tenant>/adminconsent?
client_id=<client_id>
&state=12345
&redirect_uri=http://localhost/myapp/permissions
Ersetzen Sie <tenant> mit der Microsoft Office 365-Tenant-ID. Diese kann über Azure Active Directory ermittelt werden. <client_id> entspricht der Anwendungs-ID aus der Registrierung. Außerdem muss in der Connector-Konfiguration die URL für den Microsoft-Loginserver so angepasst werden, dass anstatt "common" die Tenant-ID verwendet wird. Aus 
https://login.microsoftonline.com/common/oauth2/v2.0/token
https://login.microsoftonline.com/common/oauth2/v2.0/authorize
wird also 
https://login.microsoftonline.com/<Tenant-ID>/oauth2/v2.0/token
https://login.microsoftonline.com/<Tenant-ID>/oauth2/v2.0/authorize
Nach Bestätigung der Berechtigungen kann der Zugriff in Intrexx erfolgen. Weitere Informationen dazu finden Sie hier.

Profil

Diese Einstellungen hier sind optional und werden nicht unbedingt benötigt.

Einstellungen speichern

Wenn alle Daten eingetragen sind, klicken Sie unten auf der Seite auf "Speichern". Eine Liste aller Apps, die Sie angelegt haben, finden Sie unter der URL https://apps.dev.microsoft.com.

5. IIS-Konfiguration

Wenn Sie für den Intrexx Portal Server den Webserver IIS verwenden, muss das IIS URL Rewrite 2.0 Modul installiert werden. Hier können Sie die 32-Bit-Version, und hier die 64-Bit-Version herunterladen. Nach der Installation muss die Intrexx virtuelle Website und dann das URL Rewrite Modul im IIS-Manager aufgerufen werden.



Tragen Sie hier die entsprechenden Einträge für die OAuth2-Callbacks ein. Tragen Sie im Feld "URL umschreiben" den Ausdruck Default.asp?urn:schemas-unitedplanet-de:ixservlet:name=oAuth2CallbackServlet ein.

6. Tomcat-Konfiguration

Bei der Verwendung von Tomcat als Webserver muss der Redirect für OAuth2 in der Datei "server.xml" im Installationsverzeichnis /tomcat/conf eingetragen werden. Suchen Sie dort im Host-Abschnitt am Ende der Datei nach dem folgenden Eintrag: 
<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"/>
Fügen Sie direkt darunter den Eintrag 
<Valve className="org.apache.catalina.valves.rewrite.RewriteValve" />
hinzu. Erstellen Sie dann mit einem beliebigen Texteditor eine Textdatei mit dem Namen "rewrite.config". Fügen Sie den folgenden Inhalt ein: 
RewriteRule /<portalname>/oauth2?(.*) /<portalname>/default.ixsp?urn:schemas-unitedplanet-de:ixservlet:name=oAuth2CallbackServlet&%{QUERY_STRING} [NC,L]
Bitte beachten Sie die Groß-/Kleinschreibung beim Portalnamen. Den Portalnamen können Sie in den Portaleigenschaften im Feld "Context" ermitteln. Legen Sie die rewrite.config-Datei im Installationsverzeichnis /tomcat/conf/Catalina/<host> ab. Führen Sie anschließend einen Neustart des Intrexx Tomcat Servlet Containers aus.

7. Zertifikate einbinden

Zertifikate können über die Portaleigenschaften eingebunden werden. Fügen Sie hier die Zertifikate aus den beiden URLs hinzu. Führen Sie anschließend einen Neustart des Portaldienstes aus.

8. Verbindung anlegen

Alle Informationen zur Konfiguration einer Verbindung zu Microsoft Office 365 finden Sie hier.

9. Microsoft Office 365-Dateien in Applikationen einbinden

Alle Informationen zur Konfiguration Ihrer Portal-Applikation für die Darstellung von Microsoft Office 365-Dateien finden Sie hier.

10. Authentifizierung

Die Authentifizierung zum Azure Active Directory erfolgt mit OAuth2. Sobald der Anwender mit Intrexx auf Informationen in Microsoft Office 365 zugreifen will, muss er dafür gegenüber dem Azure Active Directory authentifiziert werden. Wenn der Benutzer bzw. der Account des Intrexx-Benutzers in der aktuellen Session noch nicht authentifiziert wurde, wird der Benutzer zur Anmeldung am Azure Active Directory zur Microsoft Office 365 Seite weitergeleitet, wo er seine Microsoft Office 365-Anmeldedaten angeben kann. Bei erfolgreicher Anmeldung am Azure Active Directory bekommt Intrexx ein Token vom Azure Active Directory, das den Zugriff von Intrexx im Scope der Applikation und dem Rechtekontext des angemeldeten Benutzers ermöglicht.

OAuth2

OAuth2 ermöglicht dem Benutzer einer Webanwendung (Microsoft Office 365, der Service-Provider) private Ressourcen wie Dateien, Photos, Kontakte, Termine mit anderen Webanwendungen (in unserem Fall Intrexx, dem Konsument) auszutauschen, ohne dass der der Nutzername und das Passwort der Service-Provider-Webanwendung (Microsoft Office 365) der Konsumenten Applikation (Intrexx) preisgegeben werden muss. Dazu wird ein Token für die Übertragung der Berechtigungsinformation vergeben. Die zentrale Frage in diesem Kontext lautet: Darf der Intrexx Anwender XY, der sich korrekt in Intrexx authentifiziert hat, seine Daten, die in Microsoft Office 365 liegen, mit Intrexx austauschen? Dabei wird vermieden, dass die Microsoft Office 365-Authentifizierungsdaten des Anwenders in Intrexx direkt bekannt gemacht werden.

9. Weitere-Informationen

Microsoft Office 365 in Prozessen
Import / Export