Arbeiten mit Benutzern in Microsoft Graph

Wichtig

Die APIs unter der /beta Version in Microsoft Graph können sich ändern. Die Verwendung dieser APIs in Produktionsanwendungen wird nicht unterstützt. Um festzustellen, ob eine API in v1.0 verfügbar ist, verwenden Sie die Version Selektor.

Mit Microsoft Graph können Sie App-Erlebnisse basierend auf Benutzern und ihren Beziehungen zu anderen Objekten wie Gruppen, E-Mails, Kalendern, Dateien und Administratorrollen erstellen. Sie können über gängige API-Operationen, Autorisierungsmodelle, Berechtigungen und die Handhabung sensibler Aktionen auf Benutzerdaten zugreifen und diese verwalten.

Zugreifende Benutzer

Zugriff auf Benutzer über Microsoft Graph auf zwei Arten:

  • Nach ihrer 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-Operationen

In Microsoft Graph werden Benutzer durch den Benutzerressourcentyp dargestellt. In der folgenden Tabelle sind allgemeine Vorgänge aufgeführt, die Sie an Benutzern ausführen können.

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 anhand der 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.
POST /invitations Laden Sie einen Gast im Rahmen der Business-to-Business (B2B)-Zusammenarbeit in Microsoft Entra External ID ein

Autorisierung und Privilegien

Microsoft Graph unterstützt delegierte und Anwendungsberechtigungen zur Verwaltung von Benutzervorgängen. Das Verständnis dieser Berechtigungen ist entscheidend für eine sichere und effiziente Anwendungsentwicklung.

Einige Benutzervorgänge können vom angemeldeten Benutzer anhand seiner eigenen Daten ausgeführt werden. Für solche Vorgänge kann der Benutzer der App Microsoft Graph Berechtigungen für den Zugriff auf seine 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 Microsoft Graph-Berechtigungen gewährt werden, denen nur autorisierte Administratoren zustimmen können, und Microsoft Entra-Rollen. Darüber hinaus gelten einige Vorgänge als vertraulich, und nur begrenzte 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

Es gibt zwei Arten von Benutzern in Microsoft Entra ID: Mitglieder und Gäste. Member werden systemintern im Mandanten erstellt. Gäste treten dem Mandanten bei, indem sie ihre Einladung einlösen, und greifen als Gäste der Business-to-Business-Zusammenarbeit (B2B) auf den Mandanten zu.

Benutzer in Microsoft Entra ID verfügen über Standardberechtigungen, die ihnen erlauben, bestimmte Vorgänge auszuführen. Dieser Satz von Standardberechtigungen hängt davon ab, ob der Benutzer ein Mitglied oder ein Gastbenutzer ist, und der Mandantenadministrator kann die Einstellungen für diese Standardberechtigungen ändern. Weitere Informationen zu den Aktionen von Mitgliederbenutzern und Gastbenutzern finden Sie unter Was sind die Standardbenutzerberechtigungen in Microsoft Entra ID?.

Standardbenutzerberechtigungen in externen Mandanten

Es gibt auch Standardberechtigungen für Kunden in Microsoft Entra ID in externen Mandanten. Die folgende Tabelle zeigt die API-Operationen, 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 können aktualisiert werden: city, country, displayName, givenName, jobTitle, postalCode, state, streetAddress, surname, and preferredLanguage		 User.ReadWrite
Kennwort ändern POST /me/changePassword Directory.AccessAsUser.All

Grundprofileigenschaften des Benutzers

Die Berechtigung User.ReadBasic.All beschränkt den App-Zugriff auf das Lesen einer begrenzten Anzahl von Eigenschaften für die Geschäfts-, Schul- oder Unikonten anderer Benutzer. Dieses Basisprofil enthält nur die folgenden Eigenschaften:

  • displayName
  • givenName
  • id
  • mail
  • photo
  • securityIdentifier
  • surname
  • userPrincipalName

Darüber hinaus erlauben die folgenden szenariospezifischen Berechtigungen Apps auch das Auslesen des grundlegenden Benutzerprofils, das hauptsächlich bezeichnerbezogene Eigenschaften enthält:

  • User-Mail.ReadWrite.All
  • User-PasswordProfile.ReadWrite.All
  • User-Phone.ReadWrite.All
  • User-LifeCycleInfo.Read.All
  • User-LifeCycleInfo.ReadWrite.All

Sensible Aktionen

Die folgenden Aktionen gegen das Benutzerobjekt gelten als vertraulich und können nur auf bestimmte Administratoren beschränkt sein. Alle Benutzer können die sensiblen Eigenschaften lesen.

Sensible Aktion Name vertraulicher Eigenschaft
Benutzer deaktivieren oder aktivieren accountEnabled
Geschäftstelefon aktualisieren businessPhones
Mobiltelefon aktualisieren mobilePhone
Aktualisieren einer unveränderlichen lokalen ID onPremisesImmutableId
Aktualisieren anderer E-Mails otherMails
Kennwortprofil aktualisieren passwordProfile
Benutzerprinzipalnamen aktualisieren userPrincipalName
Löschen oder Wiederherstellen von Benutzern Nicht zutreffend

Wer kann sensible Aktionen ausführen

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

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

Rolle, für die sensible Aktionen ausgeführt werden können Auth Admin User Admin Privileged Auth Admin Globaler Admin
Auth Admin ✅   ✅ ✅
Verzeichnisleser ✅ ✅ ✅ ✅
Globaler Admin     ✅ ✅
Gruppen-Admin   ✅ ✅ ✅
Gasteinladender ✅ ✅ ✅ ✅
Helpdesk-Admin   ✅ ✅ ✅
Nachrichtencenter-Leser ✅ ✅ ✅ ✅
Password Admin ✅ ✅ ✅ ✅
Privileged Auth Admin     ✅ ✅
Privilegierte Rolle Admin     ✅ ✅
Berichteleser ✅ ✅ ✅ ✅
Benutzer
(keine Administratorrolle)		 ✅ ✅ ✅ ✅
Benutzer
(Keine Administratorrolle, aber Mitglied oder Besitzer einer Gruppe, der die Rolle zugewiesen werden kann)		     ✅ ✅
Benutzer mit einer Rolle, die auf eine Verwaltungseinheit mit eingeschränkter Verwaltung beschränkt ist     ✅ ✅
User Admin   ✅ ✅ ✅
Leseberechtigter für Verwendungszusammenfassungsberichte ✅ ✅ ✅ ✅
Alle benutzerdefinierten Rollen ✅ ✅

Wer kann Kennwörter zurücksetzen?

In der folgenden Tabelle sind die Rollen aufgeführt, mit denen Kennwörter zurückgesetzt und Aktualisierungstoken ungültig gemacht werden können. In den Zeilen werden die Rollen aufgelistet, für die das Kennwort des Benutzers zurückgesetzt werden kann. Beispielsweise kann ein Kennwortadministrator das Kennwort für Verzeichnisleseberechtigte, Gasteinladende, Kennwortadministratoren 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 auf Ebene eines Mandanten zugewiesen sind. Für Rollen, die im Bereich einer Verwaltungseinheit zugewiesen sind, gelten weitere Einschränkungen.

Rolle, dass das Kennwort zurückgesetzt werden kann Password Admin Helpdesk-Admin Auth Admin User Admin Privileged Auth Admin Globaler Admin
Auth Admin     ✅   ✅ ✅
Verzeichnisleser ✅ ✅ ✅ ✅ ✅ ✅
Globaler Admin         ✅ ✅*
Gruppen-Admin       ✅ ✅ ✅
Gasteinladender ✅ ✅ ✅ ✅ ✅ ✅
Helpdesk-Admin   ✅   ✅ ✅ ✅
Nachrichtencenter-Leser   ✅ ✅ ✅ ✅ ✅
Password Admin ✅ ✅ ✅ ✅ ✅ ✅
Privileged Auth Admin         ✅ ✅
Privilegierte Rolle Admin         ✅ ✅
Berichteleser   ✅ ✅ ✅ ✅ ✅
Benutzer
(keine Administratorrolle)		 ✅ ✅ ✅ ✅ ✅ ✅
Benutzer
(Keine Administratorrolle, aber Mitglied oder Besitzer einer Gruppe, der die Rolle zugewiesen werden kann)		         ✅ ✅
Benutzer mit einer Rolle, die auf eine Verwaltungseinheit mit eingeschränkter Verwaltung beschränkt ist         ✅ ✅
User Admin       ✅ ✅ ✅
Leseberechtigter für Verwendungszusammenfassungsberichte   ✅ ✅ ✅ ✅ ✅
Alle benutzerdefinierten Rollen ✅ ✅

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

  • businessPhones
  • mobilePhone
  • otherMails

Allgemeine Eigenschaften

✅ Gilt nur für Version 1.0.

Die folgenden stellen den Standardsatz von Eigenschaften dar, die zurückgegeben werden, wenn ein Benutzer abgerufen oder Benutzer in Version 1.0 aufgelistet werden. Dies ist eine Teilmenge aller verfügbaren Eigenschaften in Version 1.0. 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.

Details und eine Liste aller Eigenschaften finden Sie im Benutzerobjekt .

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.

Einschränkungen bei der Benutzer- und Gruppensuche für Gäste

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 jedoch 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, die standardmäßig nicht zurückgegeben werden

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

Eigenschaften, die außerhalb des Hauptdatenspeichers gespeichert sind

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

Eigenschaften, die außerhalb des Hauptdatenspeichers gespeichert sind, werden auch nicht als Teil der Änderungsnachverfolgung unterstützt. Daher führt eine Änderung an einer dieser Eigenschaften nicht dazu, dass ein Objekt in der Delta-Abfrageantwort angezeigt wird.

Die folgenden Eigenschaften des Benutzerobjekts werden außerhalb des Hauptdatenspeichers gespeichert: signInActivity, cloudLicensing, mailboxSettings, deviceEnrollmentLimit, print, aboutMe, birthday, hireDate, interests, mySite, pastProjects, preferredName, responsibilities, schools, skills.

Zusammenfassung

Microsoft Graph bietet leistungsstarke Funktionen zum Verwalten von und Interagieren mit Benutzerdaten. Durch das Verständnis der verschiedenen Berechtigungen, der gängigen API-Operationen und die Handhabung sensibler Aktionen können Sie sichere und effiziente Anwendungen erstellen. Weitere Informationen finden Sie unter den zugehörigen Inhalten und Dokumentationslinks.

Verwandte Inhalte

  • Last updated on