Arbeiten mit Benutzern in Microsoft Graph

  • Artikel

Sie können Microsoft Graph verwenden, um überzeugende App-Erfahrungen basierend auf Benutzern und deren Beziehungen zu anderen Objekten zu erstellen. Beispielsweise ihre Beziehungen zu anderen Benutzern und Gruppen, Gruppenmitgliedschaften und die Ressourcen, auf die sie zugreifen, z. B. ihre E-Mails, Kalender, Dateien und Administratorrollen.

Sie können auf zwei Arten über Microsoft Graph auf Benutzer zugreifen:

  • Durch ihre ID oder userPrincipalName, /users/{id} oder /users/{userPrincipalName}
  • Anhand des /me-Alias für den angemeldeten Benutzer, welcher /users/{signed-in user's id} entspricht

Allgemeine API-Vorgänge

Pfad Beschreibung
/me Rufen Sie die Details des angemeldeten Benutzers ab.
/users Listet die Benutzer in der Organisation auf.
/users/{id} Ruft einen bestimmten Benutzer nach ID ab.
/users/{id}/photo/$value Ruft das Profilfoto des Benutzers ab.
/users/{id}/manager Ruft den Vorgesetzten des Benutzers ab.
/users/{id}/messages Listet die E-Mails des Benutzers im primären Posteingang auf.
/users/{id}/events Listet bevorstehende Ereignisse des Benutzers im Kalender auf.
/users/{id}/drive Ruft den OneDrive-Dateispeicher des Benutzers ab.
/users/{id}/memberOf Listet die Gruppen auf, deren Mitglied der Benutzer ist.
/users/{id}/joinedTeams Listet die Microsoft Teams auf, deren Mitglied der Benutzer ist.

Autorisierung und Berechtigungen

Microsoft Graph unterstützt die Verwendung von delegierten Berechtigungen und Anwendungsberechtigungen zum Verwalten von Benutzervorgängen. Weitere Informationen finden Sie unter Delegierte und Anwendungsberechtigungen und in der entsprechenden API-Referenzdokumentation für die berechtigungen, die für jeden Vorgang erforderlich sind.

Einige Benutzervorgänge können vom angemeldeten Benutzer anhand seiner eigenen Details ausgeführt werden. Für solche Vorgänge kann der Benutzer der App die Microsoft Graph-Berechtigungen für den Zugriff auf ihre eigenen Details erteilen. Die Berechtigungen User.ReadBasic.All, User.Read und User.ReadWrite sind solche Berechtigungen.

Andere Vorgänge, einschließlich der Verwaltung von Details für andere Benutzer, erfordern Administratorrechte, die über andere Microsoft Graph-Berechtigungen und Microsoft Entra Rollen erteilt werden. Darüber hinaus gelten einige Vorgänge als vertraulich, und nur eingeschränkte Administratoren können sie ausführen. Weitere Informationen finden Sie in den Abschnitten Wer kann Kennwörter zurücksetzen und Wer kann vertrauliche Attribute aktualisieren ?

Standardbenutzerberechtigungen in Microsoft Entra ID

In Microsoft Entra ID gibt es zwei Arten von Benutzern: Mitglieder und Gäste. Zunächst werden Mitgliedsbenutzer nativ im Mandanten erstellt. Gastbenutzer treten dem Mandanten bei, indem sie ihre Einladung einlösen und auf den Mandanten als B2B-Zusammenarbeitsgäste (Business-to-Business) zugreifen.

Der Satz von Standardberechtigungen hängt davon ab, ob der Benutzer Mitglied oder Gastbenutzer ist. Weitere Informationen dazu, was Mitglieds- und Gastbenutzer tun können, finden Sie unter Was sind die Standardbenutzerberechtigungen in Microsoft Entra ID?.

Standardbenutzerberechtigungen in Kundenmandanten

Es gibt auch Standardberechtigungen für Kunden in Microsoft Entra ID für Kunden. In der folgenden Tabelle sind die API-Vorgänge aufgeführt, mit denen Kunden ihr eigenes Profil verwalten können.

Die Benutzer-ID oder userPrincipalName ist immer die des angemeldeten Benutzers.

Benutzervorgang API-Vorgang Erforderliche Berechtigungen
Profil lesen GET /me oder GET /users/{id or userPrincipalName} User.Read
Profil aktualisieren PATCH /me oder PATCH /users/{id or userPrincipalName}

Die folgenden Eigenschaften sind aktualisierbar: city, country, displayName, givenName, jobTitle, postalCode, state, streetAddress, surname und preferredLanguage		 User.ReadWrite
Kennwort ändern POST /me/changePassword Directory.AccessAsUser.All

Wer kann Kennwörter zurücksetzen?

In der folgenden Tabelle sind in den Spalten die Rollen aufgeführt, die Kennwörter zurücksetzen und Aktualisierungstoken ungültig werden können. Die Zeilen enthalten die Rollen, für die das Kennwort zurückgesetzt werden kann. Beispielsweise kann ein Kennwortadministrator das Kennwort für Verzeichnisleseberechtigte, Gasteinladung, Kennwortadministrator und Benutzer ohne Administratorrolle zurücksetzen. Wenn einem Benutzer eine andere Rolle zugewiesen ist, kann der Kennwortadministrator sein Kennwort nicht zurücksetzen.

Die folgende Tabelle gilt für Rollen, die im Bereich eines Mandanten zugewiesen sind. Für Rollen, die im Bereich einer Verwaltungseinheit zugewiesen werden, gelten weitere Einschränkungen.

Rolle, für die das Kennwort zurückgesetzt werden kann kennwort Admin Helpdesk-Admin Authentifizierungs-Admin benutzer Admin Privilegierte Authentifizierungs-Admin Globaler Admin
Authentifizierungs-Admin     ✅   ✅ ✅
Verzeichnisleser ✅ ✅ ✅ ✅ ✅ ✅
Globaler Admin         ✅ ✅*
Gruppen Admin       ✅ ✅ ✅
Gastladend ✅ ✅ ✅ ✅ ✅ ✅
Helpdesk-Admin   ✅   ✅ ✅ ✅
Nachrichtencenterleser   ✅ ✅ ✅ ✅ ✅
kennwort Admin ✅ ✅ ✅ ✅ ✅ ✅
Privilegierte Authentifizierungs-Admin         ✅ ✅
Admin für privilegierte Rollen         ✅ ✅
Berichteleser   ✅ ✅ ✅ ✅ ✅
Benutzer
(keine Administratorrolle)		 ✅ ✅ ✅ ✅ ✅ ✅
Benutzer
(keine Administratorrolle, sondern Mitglied oder Besitzer einer Gruppe, der Rollen zugewiesen werden können		         ✅ ✅
Benutzer mit einer Rolle, die auf eine eingeschränkte Verwaltungseinheit beschränkt ist         ✅ ✅
benutzer Admin       ✅ ✅ ✅
Leseberechtigter für Verwendungszusammenfassungsberichte   ✅ ✅ ✅ ✅ ✅
Alle benutzerdefinierten Rollen ✅ ✅

Die Möglichkeit zum Zurücksetzen eines Kennworts umfasst die Möglichkeit, die folgenden vertraulichen Eigenschaften zu aktualisieren, die für die Self-Service-Kennwortzurücksetzung erforderlich sind:

  • businessPhones
  • mobilePhone
  • otherMails

Wer kann vertrauliche Aktionen ausführen?

Einige Administratoren können die folgenden vertraulichen Aktionen für einige Benutzer ausführen. Alle Benutzer können die vertraulichen Eigenschaften lesen.

Sensible Aktion Name der vertraulichen Eigenschaft
Deaktivieren oder Aktivieren von Benutzern accountEnabled
Aktualisieren des Geschäftstelefons businessPhones
Aktualisieren eines Mobiltelefons mobilePhone
Aktualisieren der lokalen unveränderlichen ID onPremisesImmutableId
Aktualisieren anderer E-Mails otherMails
Aktualisieren des Kennwortprofils passwordProfile
Aktualisieren des Benutzerprinzipalnamens userPrincipalName
Löschen oder Wiederherstellen von Benutzern Nicht zutreffend

In der folgenden Tabelle sind in den Spalten die Rollen aufgeführt, die vertrauliche Aktionen ausführen können. In den Zeilen sind die Rollen aufgeführt, für die die vertrauliche Aktion ausgeführt werden kann.

Die folgende Tabelle gilt für Rollen, die im Bereich eines Mandanten zugewiesen sind. Für Rollen, die im Bereich einer Verwaltungseinheit zugewiesen werden, gelten weitere Einschränkungen.

Rolle, für die eine sensible Aktion ausgeführt werden kann Authentifizierungs-Admin benutzer Admin Privilegierte Authentifizierungs-Admin Globaler Admin
Authentifizierungs-Admin ✅   ✅ ✅
Verzeichnisleser ✅ ✅ ✅ ✅
Globaler Admin     ✅ ✅
Gruppen Admin   ✅ ✅ ✅
Gastladend ✅ ✅ ✅ ✅
Helpdesk-Admin   ✅ ✅ ✅
Nachrichtencenterleser ✅ ✅ ✅ ✅
kennwort Admin ✅ ✅ ✅ ✅
Privilegierte Authentifizierungs-Admin     ✅ ✅
Admin für privilegierte Rollen     ✅ ✅
Berichteleser ✅ ✅ ✅ ✅
Benutzer
(keine Administratorrolle)		 ✅ ✅ ✅ ✅
Benutzer
(keine Administratorrolle, sondern Mitglied oder Besitzer einer Gruppe, der Rollen zugewiesen werden können)		     ✅ ✅
Benutzer mit einer Rolle, die auf eine eingeschränkte Verwaltungseinheit beschränkt ist     ✅ ✅
benutzer Admin   ✅ ✅ ✅
Leseberechtigter für Verwendungszusammenfassungsberichte ✅ ✅ ✅ ✅
Alle benutzerdefinierten Rollen ✅ ✅

Allgemeine Eigenschaften

Im Folgenden werden standardmäßige Eigenschaften dargestellt, die beim Abrufen eines Benutzers oder beim Auflisten von Benutzern zurückgegeben werden. Diese stellen eine Teilmenge aller verfügbaren Eigenschaften. Verwenden Sie zum Abrufen weiterer Benutzereigenschaften den $select-Abfrageparameter. Erfahren Sie mehr über die Verwendung des $Auswahlabfrageparameters und lesen Sie, welche Eigenschaften, den $Auswahlabfrageparameter unterstützen.

Eigenschaft Beschreibung
id Die eindeutige ID des Benutzers.
businessPhones Telefonnummern des Benutzers.
displayName Der Name des Benutzers, der im Adressbuch angezeigt wird.
givenName Der Vorname des Benutzers.
jobTitle Die Position des Benutzers.
mail Die E-Mail-Adresse des Benutzers.
mobilePhone Die Mobiltelefonnummern des Benutzers.
officeLocation Der Bürostandort des Benutzers.
preferredLanguage Die vom Benutzer bevorzugte Sprache.
surname Der Nachname des Benutzers.
userPrincipalName Der Benutzerprinzipalname.

Weitere Informationen und eine Liste aller Eigenschaften finden Sie unter user-Objekt.

Benutzer- und Gruppensucheinschränkungen für Gastbenutzer in Organisationen

Benutzer- und Gruppensuchfunktionen ermöglichen der App, im Verzeichnis einer Organisation nach beliebigen Benutzern oder Gruppen zu suchen, indem der /users- oder /groups-Ressourcensatz abgefragt wird (z. B. https://graph.microsoft.com/v1.0/users). Sowohl Administratoren als auch Benutzer, die Mitglieder sind, verfügen über diese Funktion. Gastbenutzer hingegen nicht.

Wenn der angemeldete Benutzer ein Gastbenutzer ist, kann er abhängig von den einer App gewährten Berechtigungen das Profil eines bestimmten Benutzers oder einer bestimmten Gruppe lesen (z. B. https://graph.microsoft.com/v1.0/users/241f22af-f634-44c0-9a15-c8cd2cea5531); er kann jedoch nicht den /users- oder /groups-Ressourcensatz abfragen, wodurch potenziell mehr als eine einzelne Ressource zurückgegeben wird.

Mit den entsprechenden Berechtigungen kann die App die Profile von Benutzern oder Gruppen lesen, die über Links in Navigationseigenschaften abgerufen werden, beispielsweise /users/{id}/directReports oder /groups/{id}/members.

Eigenschaften werden standardmäßig nicht zurückgegeben

Einige Eigenschaften des Benutzerobjekts werden standardmäßig nicht zurückgegeben und müssen in einem $select Abfrageparameter angegeben werden. Beispiel: Geburtstag und Fähigkeiten. In der Eigenschaftentabelle der Benutzerentität finden Sie Die Eigenschaften, die nur zurückgegeben werden, wenn Sie $select.

Außerhalb des Standard Datenspeichers gespeicherte Eigenschaften

Während die Benutzerressourcendaten größtenteils in Microsoft Entra ID gespeichert werden, werden einige ihrer Eigenschaften, z. B. Skills, in SharePoint Online gespeichert. In den meisten Fällen können Sie diese Eigenschaften nicht im selben Create- oder Update-Anforderungstext wie andere Benutzereigenschaften angeben.

Eigenschaften, die außerhalb des Standard Datenspeichers gespeichert sind, werden im Rahmen der Änderungsnachverfolgung ebenfalls nicht unterstützt. Daher führt eine Änderung an einer dieser Eigenschaften nicht dazu, dass ein Objekt in der Deltaabfrageantwort angezeigt wird.

Verwandte Inhalte