Einrichten von Entra ID mit Microsoft Graph API

Microsoft Entra ID (früher Azure Active Directory, Azure AD) ist eine cloudbasierte Lösung für Identitäts- und Zugriffsmanagement. In diesem Artikel wird erläutert, wie Sie Microsoft Entra ID in MyQ integrieren, um Benutzerauthentifizierung und andere Dienste bereitzustellen.

Erstellen einer Microsoft Entra ID-Verbindung

Gehen Sie zu MyQ > Einstellungen > Verbindungen.
Klicken Sie auf „Hinzufügen“ und wählen Sie „Microsoft Entra ID“ aus der Liste aus.
Geben Sie einen Titel für Ihre Verbindung ein und wählen Sie den gewünschten Modus aus:
- Automatisch erstellen: MyQ X konfiguriert die Azure-Anwendung, die für den Zugriff auf Entra ID-Benutzerinformationen erforderlich ist.
- Manuell einrichten: Konfigurieren Sie die Azure-Anwendung manuell. Wählen Sie diese Option, wenn Sie alle Aspekte der Integrationskonfiguration selbst verwalten möchten.
Fahren Sie mit dem entsprechenden Abschnitt unten fort.

Automatisch erstellen

In diesem Modus kann der Administrator MyQ beauftragen, die Unternehmensanwendung (Service Principal) in seinem Mandanten zu erstellen und dieser Anwendung Berechtigungen für den Zugriff auf Entra ID-Benutzer zu erteilen.

Zu beachten

Wenn Sie zögern, auch nur vorübergehenden Administratorzugriff für die Erstellung eines Client-Geheimnisses zu gewähren, steht das automatische Verbindungsverfahren zu ODB nicht zur Verfügung. In solchen Fällen ist es ratsam, eine Anwendung manuell in der Azure-Umgebung Ihrer Organisation zu erstellen und die Verbindung zu MyQ X selbst zu konfigurieren (Modus „Manuell einrichten“). Dieser Ansatz stellt sicher, dass Sie die volle Kontrolle über die Berechtigungen der Anwendung und die Sicherheitsaspekte der Verbindung behalten, im Einklang mit den spezifischen Sicherheitsrichtlinien und Compliance-Anforderungen Ihrer Organisation.

Voraussetzungen

Für die Erstellung des Dienstprinzipals im Tenant des Kunden sind die Rollen „Anwendungsadministrator“ oder „Cloud-Anwendungsadministrator“ erforderlich.
Für die Erteilung der Administratorzustimmung für den Dienstprinzipal ist die Rolle „Global Administrator“ erforderlich.
Um alle Schritte der automatischen Einrichtung abzuschließen, ist die Rolle „Global Administrator“ erforderlich.

Schritte zur automatischen Einrichtung der Microsoft Entra ID-Anwendung

Der Administrator meldet sich mit seinem Azure-Administratorkonto an. Der Dienstprinzipal „MyQ X Entra ID Connector“ wird im Mandanten erstellt.
Der Administrator erteilt die Vertretung zur Verwaltung von Azure-Anwendungen.
1. In diesem Schritt angeforderte Berechtigungen:
  Application.ReadWrite.All (zum Abrufen eines Sicherheitsschlüssels)
  Directory.Read.All (zum Lesen des Standard-Domänennamens im verbundenen Mandanten, damit dieser in MyQ angezeigt werden kann).
Der Administrator erteilt der Unternehmensanwendung „MyQ X Entra ID Connector“ die Berechtigung zum Lesen von Benutzern und Gruppen und erteilt die Administratorzustimmung.
- In diesem Schritt angeforderte Berechtigungen:
  Group.Read.All
  User.Read.All
Sobald der Vorgang abgeschlossen ist, wird der Microsoft Entra ID-Connector gespeichert und die Verbindungsdaten werden sicher in MyQ gespeichert.

Neuberechtigung der Entra ID-Verbindung

Die automatische Verbindung zu Entra ID kann nach ihrer Erstellung geändert oder auf manuell umgestellt werden. Durch einen Rechtsklick auf die Verbindung wird die Option „Erneut autorisieren“ im Kontextmenü verfügbar.

Anwendungsverwaltung

Die Gültigkeitsdauer des Geheimnisses beträgt 2 Jahre. Achten Sie darauf, den Schlüssel zu rotieren, wenn er abläuft. Dies können Sie über die Option „Neu autorisieren“ in MyQ tun. Wenn das Geheimnis innerhalb von 30 Tagen abläuft, sendet MyQ eine Health-Check-Warnung.
Anmeldeinformationen für Dienstprinzipale sind im Azure-Portal nicht sichtbar. Sie können über PowerShell oder die Microsoft Graph-API verwaltet werden.
Falls Sie den Zugriff der App oder das aktuell verwendete Secret widerrufen müssen, können Sie einfach die gesamte MyQ X Entra ID Connector-Unternehmensanwendung in Azure löschen und mit der Option „Neu autorisieren“ in MyQ eine neue erstellen.

Weitere Informationen

Wenn die automatische Einrichtung erneut durchgeführt wird, wird keine neue Instanz der Anwendung im Mandanten erstellt, sondern die aktuelle Anwendung aktualisiert (z. B. wird ein neues Geheimnis für den Dienstprinzipal im Mandanten erstellt). Wenn die MyQ X Entra ID Connector-Anwendung aus Azure entfernt wurde, wird sie erneut erstellt.
Der Dienstprinzipal (Unternehmensanwendung) wird nach Schritt 1 auf dem Mandanten erstellt (ohne die erforderlichen Berechtigungen, die in Schritt 2 erteilt werden). Schritt 2 kann später abgeschlossen werden (durch Rechtsklick auf den MyQ X Entra ID Connector und Auswahl von „Re-authorize“).
Um besser zu verstehen, was MyQ in diesem Modus tut, erläutert Microsoft diese Methode in seiner Entwicklerdokumentation – Benutzer- und Administratorzustimmung aus der Perspektive des Anwendungsentwicklers verstehen

Manuelle Einrichtung

Wenn Sie manuell eine Azure-Anwendung erstellen, um mehrere dieser Dienste zu verknüpfen, können Sie entweder eine Anwendung mit allen erforderlichen Berechtigungen erstellen oder für Entra ID, OneDrive for Business und SharePoint Online jeweils eine separate Anwendung erstellen. Lesen Sie hier mehr dazu.

Microsoft Entra ID-Anwendungskonfiguration

Melden Sie sich beim Microsoft Azure-Portal an und gehen Sie zu „App-Registrierungen“.
Klicken Sie auf „Neue Registrierung“, um eine neue Anwendung zu erstellen, oder wählen Sie eine vorhandene Anwendung aus.
Wenn Sie eine neue Anwendung erstellen, legen Sie den Namen fest und wählen Sie unter „Unterstützte Kontotypen“ die Option „Nur Konten in diesem Organisationsverzeichnis (nur {Tenantname} – Einzeltenant)“, wenn alle Ihre Benutzer Mitglieder Ihres Tenants sind. Je nach Zielgruppe der Anwendung kann bei Bedarf auch eine mandantenfähige Anwendung verwendet werden.
Sie können die Einstellungen für die Umleitungs-URI vorerst überspringen (siehe Schritt 7). Klicken Sie auf „Registrieren“, um die Anwendung zu erstellen.
Gehen Sie auf dem Übersichtsbildschirm der Anwendung zu „API-Berechtigungen“ und wählen Sie „Microsoft Graph API“ sowie den erforderlichen Berechtigungstyp (Delegiert oder Anwendung) aus, wie unten dargestellt.
- Die folgenden Berechtigungen sind erforderlich:
  - Microsoft Graph \ Group.Read.All
  - Microsoft Graph \ User.Read
  - Microsoft Graph \ User.Read.All
- Beachten Sie, dass das System während der Benutzerauthentifizierung automatisch auch die folgenden OpenID Connect-Bereiche anfordert, um eine erweiterte Identitätsüberprüfung zu ermöglichen.
  - openid (ermöglicht die Anmeldung und das Lesen des grundlegenden Benutzerprofils)
  - email (Zugriff auf die E-Mail-Adresse des Benutzers)
  - profile (Zugriff auf grundlegende Profilinformationen des Benutzers)
Für alle Berechtigungen muss der Status „Für Standardverzeichnis gewährt“ festgelegt werden. Sie können der Anwendung die Administratorzustimmung über die Schaltflächen oben in der Liste der Berechtigungen erteilen.
Verwenden Sie „Berechtigung hinzufügen“, um eine neue Berechtigung hinzuzufügen.
Verwenden Sie „Administratorzustimmung für Standardverzeichnis erteilen“, um den Status der Berechtigung auf „Für Standardverzeichnis gewährt“ zu setzen.
Gehen Sie zu „Authentifizierung“ und klicken Sie unter „Plattformkonfigurationen“ auf „Plattform hinzufügen“.
- Wählen Sie „Web“ und listen Sie alle Weiterleitungs-URLs für Ihre MS Entra ID-Anwendung auf. Verwenden Sie für die tatsächlichen URLs den Hostnamen (und Port) Ihres Servers im folgenden Format:
  https://{hostname:port}/auth
- Klicken Sie außerdem auf „Plattform hinzufügen“ und wählen Sie „Einseitige Anwendung“ aus. Fügen Sie die folgende Weiterleitungs-URL hinzu und achten Sie darauf, dass der abschließende Schrägstrich enthalten ist:
  https://helper.myq.cz/openid/
  Für alle Server, die die Entra ID-Anmeldung verwenden, muss in der Azure-Anwendung eine Weiterleitung definiert sein. Führen Sie diesen Schritt unbedingt für jeden Print Server und jeden Central Server in Ihrer Bereitstellung durch.
- Klicken Sie für jede Plattformkonfiguration auf „Konfigurieren“.
Speichern Sie auf der Übersichtsseite der Anwendung die Anwendungs-ID (Client-ID) und die Verzeichnis-ID (Tenant-ID), da diese für die MyQ-Konfiguration benötigt werden.
Klicken Sie neben „Client-Anmeldeinformationen“ auf „Zertifikat oder Geheimnis hinzufügen“ und führen Sie die folgenden Schritte aus:
1. Klicken Sie auf „Neues Client-Geheimnis“.
2. Fügen Sie eine Beschreibung hinzu.
3. Legen Sie die Gültigkeitsdauer für den Schlüssel fest.
4. Klicken Sie auf „Hinzufügen“.
5. Speichern Sie den Wert des geheimen Client-Schlüssels, da Sie ihn für die Konfiguration in MyQ benötigen und ihn später nicht mehr abrufen können.

Verwendung des MyQ Desktop Clients mit nahtlosem Single Sign-On

Um nahtloses Single Sign-On im MyQ Desktop Client nutzen zu können, müssen Sie eine korrekt konfigurierte Anwendung erstellen. Befolgen Sie die obigen Anweisungen und ab Schritt 7:

Wählen Sie „Plattform hinzufügen“ und dann „Mobil- und Desktop-Anwendungen“.
Fügen Sie benutzerdefinierte Umleitungs-URIs hinzu ms-appx-web://microsoft.aad.brokerplugin/30fadb1e-5a0b-41f4-9927-a2075a531f1d wobei 30fadb1e-5a0b-41f4-9927-a2075a531f1d die Anwendungs- (Client-)ID ist.

Konfiguration in MyQ

Gehen Sie zu „MyQ > Einstellungen > Verbindungen“, um MyQ mit Microsoft Entra ID zu verbinden. Klicken Sie auf „Hinzufügen“ und wählen Sie „Microsoft Entra ID“ aus der Liste aus. Geben Sie im Popup-Fenster die erforderlichen Informationen ein:

Titel: Fügen Sie einen Titel für die Verbindung hinzu.
Mandanten-ID: Geben Sie die Verzeichnis- (Mandanten-)ID ein, die Sie aus Microsoft Entra gespeichert haben.
Client-ID: Geben Sie die Anwendungs-ID (Client-ID) ein, die Sie aus Microsoft Entra gespeichert haben.
Sicherheitsschlüssel: Geben Sie den (geheimen) Wert ein, den Sie aus Microsoft Entra gespeichert haben.

Klicken Sie auf „Speichern“. Ihre Microsoft Entra ID-Verbindung ist nun hergestellt.

Microsoft Single Sign-On

So verwenden Sie Microsoft Single Sign-On:

Aktivieren Sie „Als Authentifizierungsserver verwenden“ in der Microsoft Entra ID-Synchronisierungsquelle – Registerkarte „Benutzer“, bevor Sie Benutzer synchronisieren, oder aktivieren Sie Microsoft Entra ID manuell als Authentifizierungsserver für ausgewählte Benutzer in deren Details auf der Hauptseite „Benutzer“.
Aktivieren Sie in den Einstellungen des Microsoft Entra ID-Authentifizierungsservers die Anzeige der Anmeldemethode „Mit Microsoft anmelden“.

Wenn Microsoft Single Sign-On aktiviert ist, wird die Schaltfläche „Mit Microsoft anmelden“ immer auf der Anmeldeseite der MyQ-Weboberfläche angezeigt, aber nur Benutzer, die Microsoft Entra ID als Authentifizierungsserver verwenden, können sich damit anmelden. Jeder Versuch, Microsoft Single Sign-On zu verwenden, durch einen Benutzer, der das Microsoft Entra ID-Authentifizierungssystem nicht nutzt, führt zu einer Fehlermeldung.

Was passiert, wenn ein Benutzer versucht, sich in der MyQ-Weboberfläche mit Microsoft anzumelden:

Der Benutzer klickt auf die Schaltfläche für Single Sign-On.
- Wenn der Benutzer im Browser nicht bei Microsoft angemeldet ist, wird er zur Microsoft-Anmeldeseite weitergeleitet, um sich dort anzumelden, und anschließend mit dem angegebenen Konto bei MyQ angemeldet.
- Wenn der Benutzer bei zwei Microsoft-Konten angemeldet ist, wird er zur Microsoft-Anmeldeseite weitergeleitet und kann dort das Konto auswählen, mit dem er fortfahren möchte.
Das Abmelden in der MyQ-Weboberfläche meldet den Benutzer nur lokal ab, nicht bei Microsoft.
In Fällen, in denen mehrere Entra ID-Authentifizierungsserver konfiguriert sind, werden auf der Anmeldeseite mehrere „Weiter mit Microsoft“-Schaltflächen angezeigt.

Einschränkungen

Benutzer, die den Microsoft Entra ID-Authentifizierungsserver verwenden, können sich nicht mit einer PIN bei der MyQ-Weboberfläche anmelden. Sie können ihre PIN jedoch auf den MyQ-Embedded Terminals und im MyQ-Desktop Client verwenden.

Die Synchronisierung und Authentifizierung über Microsoft Entra ID mit Microsoft Graph kann nun über die folgenden Schritte genutzt werden:

Hinzufügen eines Microsoft Entra ID-Authentifizierungsservers unter MyQ > Einstellungen > Authentifizierungsserver.
Hinzufügen einer Microsoft Entra ID-Synchronisierungsquelle in MyQ > Einstellungen > Benutzersynchronisierung.

Entra ID (Azure) – Multi-Tenant-Synchronisierung und -Authentifizierung

Sie können nun mehrere Entra ID-Mandanten in MyQ-Umgebungen verwenden, um Benutzer zu synchronisieren und zu authentifizieren. Dies ist besonders nützlich in Umgebungen mit gemeinsam genutzter Druckinfrastruktur, wie sie beispielsweise im öffentlichen Sektor zu finden sind, wo mehrere Organisationen Drucker von einem einzigen Standort aus verwalten, während jede ihre eigene Entra ID verwendet.

Befolgen Sie einen der oben beschriebenen Vorgänge, wiederholen Sie ihn jedoch, um mehrere Instanzen einzurichten. Stellen Sie sicher, dass jeder Mandant eine eindeutige und aussagekräftige Bezeichnung erhält, damit Benutzer erkennen können, welcher für ihre Nutzung relevant ist.