Die Microsoft Graph-API ist eine RESTful Web-API, mit deren Hilfe auf die in der Microsoft Azure Cloud verfügbaren Unternehmensinformationen und Cloud-Dienste zugegriffen werden kann.

Damit raum]für[raum die in der Cloud verfügbaren kundenspezifischen Informationen, Daten und Dienste nutzen kann, sind folgende Schritte erforderlich:

  1. Erstellen und Einrichten einer Microsoft Azure-Anwendung mit Zugriff auf die Microsoft Graph-API

  2. raum]für[raum: Einrichten der Microsoft Graph-API-Schnittstelle

Erstellen und Einrichten einer Microsoft Azure-Anwendung mit Zugriff auf die Microsoft Graph-API

In der Anwendung wird geregelt,

  • wer raum]für[raum nutzen darf,
  • auf welche Unternehmens-Resourcen raum]für[raum und seine Anwender zugreifen dürfen und
  • in welcher Art und Weise sich die Anwender an raum]für[raum anmelden können

Daher sind zum Einrichten folgende Schritte erforderlich:

  1. Auswählen der raum]für[raum-spezifischen Personengruppe, die Zugriff erhalten soll
  2. Auswählen der raum]für[raum-spezifischen Authentifizierungsverfahren und Endpunkte
  3. Auswählen der raum]für[raum-spezifischen Microsoft Graph-API-Berechtigungen (auf die in der Azure Cloud verfügbaren Infrastruktur-Komponenten, Dienste und Informationen) in Abhängigkeit der erworbenen raum]für[raum-Module und -Funktionalitäten

Voraussetzungen / Einschränkungen

Multi-Faktor-Authentifizierung (MFA)

Wenn eine Multi-Faktor-Authentifizierung im Rahmen der raum]für[raum-Anmeldung durchgeführt werden soll, können mit Hilfe von Azure Conditional Access klare Zugriffsregelungen abgebildet werden, sofern eine Richtlinie existiert, die die Multi-Faktor-Authentifizierung für alle Cloud-Apps aktiviert.

Mehrere granulare Richtlinien für einzelne Azure Business-Apps werden von Microsoft aktuell leider nicht unterstützt. (Stand 10.05.2022)

https://practical365.com/planning-for-azure-ad-conditional-access-policies/

Registrieren einer Anwendung für die Microsoft Identity Platform

Für die initiale Registrierung der Anwendung werden folgende Parameter festgelegt:

  1. Auswahl des Namens für die Anwendung
  2. Auswahl der unterstützten Benutzerkonten
  3. Auswahl der Anwendungsplattform

Anweisungen

Screenshots

Rufen Sie das Azure-App-Registrierung-Portal auf und melden Sie sich mit einem Administrator-Account an.

https://portal.azure.com/#blade/Microsoft_AAD_RegisteredApps/ApplicationsListBlade

Alternativ können Sie die App-Registrierung auch manuell erreichen:

  • Melden Sie sich im Azure-Portal mit einem Administrator-Account an
  • Wählen Sie unter Azure-Dienste die Option "Azure Active Directory"
  • Sie finden "Azure Active Directory", indem Sie
    • auf das Burger-Menü in der linken oberen Ecke klicken
    • anschließend auswählen
    • und dann die Option aufrufen
  • Klicken Sie nun in der linken Spalte auf 

Klicken Sie auf den Button , um eine neue Anwendung anzulegen.

Auswahl des Namens für die Anwendung

Wählen Sie einen sprechenden Namen für die App, z.B. den vollqualifizierten Domain-Namen, über den die raum]für[raum-Anwendung im Netzwerk erreichbar ist.

Auswahl der unterstützten Benutzerkonten

Wählen Sie den passenden Kontotyp für die Anwender aus, die sich an der raum]für[raum-Anwendung anmelden können sollen.


Auswahl der Anwendungsplattform

Wählen Sie als Plattform "Web".

Ergänzen Sie /oauth.php hinter den voll-qualifizierten Domain-Namen der raum]für[raum-Anwendung und klicken Sie dann auf den Button , um die App zu erstellen.

Dieser Endpunkt wird für die browserbasierte Benutzer-Authentifizierung verwendet.


 

Auf der Übersichtsseite finden Sie zwei wichtige Informationen, die später zum Konfigurieren der Graph-API-Schnittstelle in raum]für[raum benötigt werden:

Azure App-Registrierung

raum]für[raum Graph-API-Formular

Anwendungs-ID (Client)

Client-ID

Verzeichnis-ID (Mandant)

Tenant-ID

Einrichten der Authentifizierung

  1. raum]für[raum-Zugriff auf die Anwendung der Microsoft Identity Platform
  2. raum]für[raum-Benutzerauthentifizierung

raum]für[raum-Zugriff auf die Anwendung der Microsoft Identity Platform

Anweisungen

Screenshots

Damit raum]für[raum eine Verbindung mit der neu erstellten Azure-App aufbauen kann, wird eine anwendungsspezifische Anmeldeinformation benötigt.

Der benötigte Wert kann im Menüpunkt erzeugt werden.

Im Reiter "Geheime Clientschlüssel" kann durch Anklicken des Buttons der Erstellvorgang initiiert werden.

Zum Erzeugen des geheimen Clientschlüssels

  • vergeben Sie eine Beschreibung, z.B. "raum]für[raum Token" und
  • legen den Gültigkeitszeitraum fest, hier z.B. "24 Monate"

Anschließend klicken Sie auf den Button , um den geheimen Clientschlüssel zu erstellen.

Die wichtige Information, die für die Einrichtung der raum]für[raum Graph-API-Schnittstelle benötigt wird, ist der Inhalt der Spalte "Wert".

Azure geheime Client Schlüssel

raum]für[raum Graph-API-Formular

Wert

Client Secret

Die Spalte "Geheime ID" enthält nur einen Bezeichner, der aber für die raum]für[raum-Konfiguration nicht relevant ist.

Hinweis 1: Sichtbarkeit

Der Wert muss unmittelbar nach dem Erstellen notiert werden, da beim erneuten Aufrufen der Seite die Clientschlüssel aus Sicherheitsgründen nur noch unvollständig angezeigt werden.

Hinweis 2: Gültigkeitszeitraum

Vor Ablauf des Gültigkeitszeitraums muss von Hand ein neuer geheimer Clientschlüssel erstellt und in der raum]für[raum-Graph-API-Konfiguration aktualisiert werden, um eine unterbrechungsfreie Kommunikation zwischen raum]für[raum und der Anwendung der Microsoft Identity Platform zu gewährleisten.

raum]für[raum-Benutzerauthentifizierung

Microsoft unterstützt diverse Szenarien zur Authentifizierung. Als Web-Anwendung (Anwendungsplattform "Web") nutzt raum]für[raum den "OAuth 2.0 Authorization code flow".

Anwendungsplattform

Web-Anwendung

https://docs.microsoft.com/en-us/azure/active-directory/develop/v2-app-types#web-apps

Authentifizierungs-Worklow

OAuth 2.0 Authorization code flow

https://docs.microsoft.com/en-us/azure/active-directory/develop/v2-oauth2-auth-code-flow#protocol-diagram


raum]für[raum stellt zwei verschiedene Authentifizierungsendpunkte zur Verfügung:

Umleitungs-URI

Verwendungszweck

oauth.php

Endpunkt für browserbasierte Azure-Anmeldung (Standard)

authorize.php

Endpunkt für raum]für[raum-Outlook-ADD.IN- sowie raum]für[raum-Mobile-APP-basierte Anmeldung

Falls zusätzlich zum Browser auch das raum]für[raum Outlook ADD.IN und/oder die raum]für[raum Mobile App verwendet werden soll, kann der zusätzliche Authentifizierungsendpunkt - wie nachfolgend beschrieben - eingerichtet werden.

Anweisungen

Screenshots

Rufen Sie das Azure-App-Registrierung-Portal auf und melden Sie sich mit einem Administrator-Account an.

https://portal.azure.com/#blade/Microsoft_AAD_RegisteredApps/ApplicationsListBlade

Alternativ können Sie die App-Registrierung auch manuell erreichen:

  • Melden Sie sich im Azure-Portal mit einem Administrator-Account an
  • Wählen Sie unter Azure-Dienste die Option "Azure Active Directory"
  • Sie finden "Azure Active Directory", indem Sie
    • auf das Burger-Menü in der linken oberen Ecke klicken
    • anschließend auswählen
    • und dann die Option aufrufen
  • Klicken Sie nun in der linken Spalte auf 

Wählen Sie die für raum]für[raum vorgesehene Anwendung aus.


Rufen Sie in der linken Spalte im Abschnitt "Verwalten" das Menü auf.

Nun prüfen Sie, ob die für die Plattform "Web" erforderlichen Umleitungs-URIs autorisiert sind.


Zum Hinzufügen eines zusätzlichen Authentifizierungsendpunkts klicken Sie einfach auf den Link und ergänzen den Link.


Hier tragen Sie den zusätzlichen raum]für[raum-Endpunkt ein (hier: authorize.php) und klicken abschließend auf den

-Button.

Zuordnen (und ggf. Autorisieren) der erforderlichen Microsoft Graph-API-Berechtigungen

Wenn die Anwendung erstellt wurde, können nun in Abhängigkeit der gewünschten raum]für[raum-Funktionalität die erforderlichen Microsoft Graph-API-Berechtigungen zugeordnet werden.

Exemplarisch fügen wir hier die Berechtigung hinzu, die es raum]für[raum ermöglicht, lesend auf alle Personen zuzugreifen (inkl. Personendetails), die in der Anwendung für die Microsoft Identity Platform berechtigt wurden. (Erforderlich zum Provisionieren von Benutzern)

API

Berechtigung

Art

Administrator-
einwilligung
erforderlich


Microsoft Graph

User.Read.All

Anwendung

Ja

Diese Berechtigung befähigt raum]für[raum, auf alle Personen zuzugreifen (inkl. Personendetails), die in der Anwendung für die Microsoft Identity Platform berechtigt wurden.

Um eine Zuordnung vornehmen zu können, werden folgende Informationen benötigt:

  1. Die Art der Berechtigung
  2. Den spezifischen Namen der Berechtigung

Art der Berechtigung

Grundsätzlich wird zwischen zwei Berechtigungsarten unterschieden:

  1. Delegierte Berechtigung (raum]für[raum agiert im Namen einer individuellen Person)
  2. Anwendungsberechtigung (raum]für[raum agiert als Anwendung ohne Benutzerkontext)

Name der Berechtigung

Referenz-Dokumentation: https://docs.microsoft.com/en-us/graph/permissions-reference


Anweisungen

Screenshots

Im "Verwalten"-Menü der linken Spalte können im Unterpunkt die erforderlichen spezifischen Zugriffe gewährt werden.

Um weitere Berechtigungen zu erteilen, klicken Sie auf den Button .

Einige Berechtigungen können ohne die Zustimmung eines Administrators erteilt werden, andere benötigen hingegen eine spezielle Zustimmung, die durch eine entsprechend berechtigte Person durch Anklicken des Buttons autorisiert werden muss.

Im Reiter "Microsoft-APIs" wählen Sie die Kachel "Microsoft Graph" aus.

Im Anschluss müssen Sie sich für einen der Berechtigungstyp entscheiden:

  • Delegierte Berechtigungen oder
  • Anwendungsberechtigungen

Danach können Sie über das Suchformular die Ausgabe einschränken und die gewünschte Berechtigung auswählen.

Durch das Eintragen eines Berechtigungsnamens in der Suchzeile - hier z.B. "User.Read" - wird die Ausgabe der Berechtigungen auf das im Suchfilter genannte Kriterium angepasst.

Die Ausgabe ist zwei-spaltig.

Berechtigung

Administratoreinwilligung erforderlich

Name der Berechtigung

Ja / Nein

Zum Auswählen der Berechtigung aktivieren Sie die Checkbox und klicken anschließend auf den Button .

Erscheint in der Zeile mit der neuen Berechtigung unter "Status" der Warnhinweis  , so muss eine entsprechend berechtigte Person die API-Berechtigung durch Anklicken des Buttons autorisieren.

Über das Pop-up-Fenster "Bestätigung der Administratoreinwilligung" kann die Zustimmung dann durch Anklicken des Buttons erteilt werden.

Ob die Zustimmungen erfolgreich erteilt wurde, kann in der Spalte Status abgelesen werden:


Troubleshooting

Thema

URL

Beheben von Microsoft Graph-Autorisierungsfehlern

https://docs.microsoft.com/de-de/graph/resolve-auth-errors

Microsoft Graph-Fehlerantworten und -Ressourcentypen

https://docs.microsoft.com/de-de/graph/errors