Ohne Benutzer zugreifen
Um Microsoft Graph aufzurufen, muss eine App ein Zugriffstoken vom Microsoft Identity Platform abrufen. Dieses Zugriffstoken enthält Informationen dazu, ob die App für den Zugriff auf Microsoft Graph im Namen eines angemeldeten Benutzers oder mit einer eigenen Identität autorisiert ist. Dieser Artikel enthält Anleitungen dazu, wie eine App mit ihrer eigenen Identität auf Microsoft Graph zugreifen kann, die auch als app-only-Zugriff bezeichnet wird.
In diesem Artikel werden die unformatierten HTTP-Anforderungen beschrieben, die für eine App erforderlich sind, um Microsoft Graph mit einer eigenen Identität mithilfe eines beliebten Flows namens OAuth 2.0-Clientanmeldeinformationen aufzurufen. Alternativ können Sie das Schreiben unformatierter HTTP-Anforderungen vermeiden und eine von Microsoft erstellte oder unterstützte Authentifizierungsbibliothek verwenden, die viele dieser Details für Sie verarbeitet und Ihnen hilft, Zugriffstoken zu erhalten und Microsoft Graph aufzurufen. Weitere Informationen finden Sie unter Verwenden der Microsoft Authentication Library (MSAL).For more information, see Use the Microsoft Authentication Library (MSAL).
Voraussetzungen
Bevor Sie mit den Schritten in diesem Artikel fortfahren:
- Machen Sie sich mit den Authentifizierungs- und Autorisierungskonzepten im Microsoft Identity Platform vertraut. Weitere Informationen finden Sie unter Grundlagen zu Authentifizierung und Autorisierung.
- Registrieren Sie die App bei Microsoft Entra ID. Weitere Informationen finden Sie unter Registrieren einer Anwendung beim Microsoft Identity Platform.
Authentifizierungs- und Autorisierungsschritte
Damit eine App die Autorisierung und den Zugriff auf Microsoft Graph mithilfe des Clientanmeldeinformationsflows erhält, müssen Sie die folgenden fünf Schritte ausführen:
- Registrieren Sie die App bei Microsoft Entra ID.
- Konfigurieren Sie Microsoft Graph-Anwendungsberechtigungen für die App.
- Fordern Sie die Zustimmung des Administrators an.
- Fordern Sie ein Zugriffstoken an.
- Rufen Sie Microsoft Graph mithilfe des Zugriffstokens auf.
1. Registrieren der App
Bevor die App den Microsoft Identity Platform-Endpunkt verwenden oder Microsoft Graph aufrufen kann, muss sie ordnungsgemäß registriert sein. Führen Sie die Schritte aus, um Ihre App auf dem Microsoft Entra Admin Center zu registrieren.
Speichern Sie in der App-Registrierung die folgenden Werte:
- Die Anwendungs-ID (im Microsoft Entra Admin Center als Objekt-ID bezeichnet), die vom App-Registrierungsportal zugewiesen wird.
- Ein geheimer Clientschlüssel (Anwendungskennwort), ein Zertifikat oder anmeldeinformationen für eine Verbundidentität.
- Ein Umleitungs-URI für die App zum Empfangen von Tokenantworten von Microsoft Entra ID.
- Ein Umleitungs-URI für den Dienst zum Empfangen von Administratoreinwilligungsantworten, wenn die App Funktionen zum Anfordern der Administratoreinwilligung implementiert.
2. Konfigurieren von Berechtigungen für Microsoft Graph
Microsoft Graph macht Anwendungsberechtigungen für Apps verfügbar, die Microsoft Graph unter ihrer eigenen Identität aufrufen. Diese Berechtigungen erfordern immer die Zustimmung des Administrators.
Sie konfigurieren die Anwendungsberechtigungen, die die App beim Registrieren der App benötigt. Ein Administrator kann diesen Berechtigungen entweder mithilfe des Microsoft Entra Admin Center zustimmen, wenn er die App in seiner organization installiert, oder Sie können eine Registrierungsoberfläche in der App bereitstellen, über die Administratoren den von Ihnen konfigurierten Berechtigungen zustimmen können. Sobald Microsoft Entra ID die Administratorzustimmung erfasst, kann die App Token anfordern, ohne erneut die Zustimmung anfordern zu müssen.
Führen Sie die folgenden Schritte aus, um Anwendungsberechtigungen für die App im Azure-Portal für App-Registrierungen zu konfigurieren:
- Wählen Sie auf der Seite API-Berechtigungen der Anwendung Die Option Berechtigung hinzufügen aus.
- Wählen Sie Microsoft Graph aus.
- Wählen Sie Anwendungsberechtigungen aus.
- Wählen Sie im Dialogfeld Berechtigungen auswählen die Berechtigungen aus, die für die App konfiguriert werden sollen.
Der folgende Screenshot zeigt das Dialogfeld Berechtigungen auswählen für Microsoft Graph-Anwendungsberechtigungen.
Wichtig
Konfigurieren Sie immer den Berechtigungssatz mit den geringsten Berechtigungen, die für die App erforderlich sind. Weitere Informationen finden Sie unter Bewährte Methoden für die Verwendung von Microsoft Graph-Berechtigungen.
3. Anfordern der Administratorgenehmigung
Administratoren können die Berechtigungen, die Ihre App benötigt, am Microsoft Entra Admin Center erteilen. Wenn Sie jedoch keinen Zugriff auf die Microsoft Entra Admin Center haben, können Sie mithilfe des Microsoft Identity Platform-Endpunkts /adminconsent eine Registrierungsoberfläche für Administratoren bereitstellen.
Wichtig
Wenn Sie Änderungen an den konfigurierten Berechtigungen vornehmen, müssen Sie auch den Prozess für die Administratorzustimmung wiederholen. Änderungen, die im App-Registrierungsportal vorgenommen werden, werden erst wider, wenn ein autorisierter Administrator, z. B. ein globaler Administrator, die App neu konfiguriert.
Anforderung
// Line breaks are for legibility only.
GET https://login.microsoftonline.com/{tenant}/adminconsent
?client_id=6731de76-14a6-49ae-97bc-6eba6914391e
&state=12345
&redirect_uri=https://localhost/myapp/permissions HTTP/1.1
| Parameter | Bedingung | Beschreibung |
|---|---|---|
| tenant | Erforderlich | Der Verzeichnismandant, von dem Sie die Berechtigung anfordern möchten. Der Wert kann im GUID- oder Anzeigenamenformat vorliegen. Wenn Sie nicht wissen, zu welchem Mandanten der Benutzer gehört, und Sie möchten, dass er sich mit einem beliebigen Mandanten anmeldet, verwenden Sie common. |
| client_id | Erforderlich | Die Anwendungs-ID, die Ihrer App vom Azure App-Registrierungsportal zugewiesen wurde. |
| redirect_uri | Erforderlich | Der Umleitungs-URI, an den die Antwort gesendet werden soll, damit ihre App verarbeitet werden soll. Sie muss mit einer der Umleitungs-URIs übereinstimmen, die Sie im Portal registriert haben. Er muss URL-codiert sein und kann zusätzliche Pfadsegmente enthalten. |
| state | Empfohlen | Ein Wert, der in der Anforderung enthalten ist, der auch in der Tokenantwort zurückgegeben wird. Dabei kann es sich um eine Zeichenfolge mit beliebigen Inhalten handeln. Der Zustand wird verwendet, um Informationen zum Status des Benutzers in der App zu codieren, bevor die Authentifizierungsanforderung aufgetreten ist, z. B. die Seite oder Ansicht, auf der er sich befand. |
Oberfläche zur Administratorzustimmung
Bei Anforderungen an den /adminconsent Endpunkt erzwingt Microsoft Entra ID, dass sich nur ein autorisierter Administrator anmelden kann, um die Anforderung abzuschließen. Der Administrator wird aufgefordert, alle Anwendungsberechtigungen zu genehmigen, die Sie für Ihre App im App-Registrierungsportal angefordert haben.
Der folgende Screenshot zeigt ein Beispiel für das Zustimmungsdialogfeld, das Microsoft Entra ID dem Administrator präsentiert:
Antwort
Wenn der Administrator die Berechtigungen für Ihre Anwendung genehmigt, sieht die erfolgreiche Antwort wie folgt aus:
// Line breaks are for legibility only.
https://localhost/myapp/permissions?admin_consent=True&tenant=38d49456-54d4-455d-a8d6-c383c71e0a6d&state=12345#
| Parameter | Beschreibung |
|---|---|
| tenant | Der Verzeichnismandant, der Ihrer Anwendung die angeforderten Berechtigungen gewährt hat, im GUID-Format. |
| state | Ein Wert, der in der Anforderung enthalten ist, der auch in der Tokenantwort zurückgegeben wird. Dabei kann es sich um eine Zeichenfolge mit beliebigen Inhalten handeln. Der Zustand wird verwendet, um Informationen zum Status des Benutzers in der App zu codieren, bevor die Authentifizierungsanforderung aufgetreten ist, z. B. die Seite oder Ansicht, auf der er sich befand. |
| admin_consent | Legen Sie diesen Wert auf True fest. |
4. Anfordern eines Zugriffstokens
Im Fluss zur Gewährung von OAuth 2.0-Clientanmeldeinformationen verwenden Sie die Werte für Anwendungs-ID und den geheimen Clientschlüssel, die Sie beim Registrieren der App gespeichert haben, um ein Zugriffstoken direkt vom Microsoft Identity Platform/token-Endpunkt anzufordern.
Sie geben die vorkonfigurierten Berechtigungen an, indem Sie als Wert für den scope Parameter in der Tokenanforderung übergebenhttps://graph.microsoft.com/.default.
Tokenanforderung
Senden Sie eine POST-Anforderung an den /token Identity Platform-Endpunkt, um ein Zugriffstoken abzurufen. In dieser Anforderung verwendet der Client den geheimen Clientschlüssel.
// Line breaks are for legibility only.
POST https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token HTTP/1.1
Host: login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded
client_id=535fb089-9ff3-47b6-9bfb-4f1264799865
&scope=https%3A%2F%2Fgraph.microsoft.com%2F.default
&client_secret=qWgdYAmab0YSkuL1qKv5bPX
&grant_type=client_credentials
| Parameter | Bedingung | Beschreibung |
|---|---|---|
| tenant | Erforderlich | Der Verzeichnismandant, von dem Sie die Berechtigung anfordern möchten. Der Wert kann im GUID- oder Anzeigenamenformat vorliegen. |
| client_id | Erforderlich | Die Anwendungs-ID, die beim Registrieren der App vom Azure App-Registrierungsportal zugewiesen wurde. |
| Bereich | Erforderlich | Der Wert, der für den scope-Parameter in dieser Anforderung übergeben wird, sollte der Bezeichner (App-ID-URI) der gewünschten Ressource mit dem angehängten Suffix .default sein. Der App-ID-URI der Microsoft Graph-Ressource lautet beispielsweise https://graph.microsoft.com/. Für Microsoft Graph ist der Wert für scope daher https://graph.microsoft.com/.default. Dieser Wert informiert den Microsoft Identity Platform Endpunkt darüber, dass alle Berechtigungen auf App-Ebene, denen der Administrator zugestimmt hat, in das Zugriffstoken eingeschlossen werden sollen. |
| client_secret | Erforderlich | Der geheime Clientschlüssel, den Sie für Ihre App im App-Registrierungsportal generiert haben. Stellen Sie sicher, dass sie URL-codiert ist. |
| grant_type | Erforderlich | Muss client_credentials sein. |
Tokenantwort
Eine erfolgreiche Antwort sieht wie folgt aus:
{
"token_type": "Bearer",
"expires_in": 3599,
"ext_expires_in":3599,
"access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik1uQ19WWmNBVGZNNXBP..."
}
| Parameter | Beschreibung |
|---|---|
| access_token | Das angeforderte Zugriffstoken. Ihre App kann dieses Token in Aufrufen von Microsoft Graph verwenden. |
| expires_in | Gültigkeit des Zugriffstokens (in Sekunden). |
| ext_expires_in | Wird verwendet, um eine verlängerte Lebensdauer für das Zugriffstoken anzugeben und resilienz zu unterstützen, wenn der Tokenausstellungsdienst nicht reagiert. |
| token_type | Gibt den Tokentypwert an. Der einzige Typ, der Microsoft Entra ID unterstützt, ist Bearer. |
5. Aufrufen von Microsoft Graph unter Verwendung des Zugriffstokens
Nachdem Sie über ein Zugriffstoken verfügen, verwendet die App es, um Microsoft Graph aufzurufen, indem das Zugriffstoken als Bearertoken an den Autorisierungsheader in einer HTTP-Anforderung angefügt wird. Die folgende Anforderung ruft alle Benutzer im Mandanten ab. Die App muss über die Berechtigung User.Read.All verfügen, um diese API aufrufen zu können.
GET https://graph.microsoft.com/v1.0/users HTTP/1.1
Authorization: Bearer eyJ0eXAiO ... 0X2tnSQLEANnSPHY0gKcgw
Host: graph.microsoft.com
Eine erfolgreiche Antwort sieht wie folgt aus (einige Antwortheader wurden entfernt):
HTTP/1.1 200 OK
Content-Type: application/json;odata.metadata=minimal;odata.streaming=true;IEEE754Compatible=false;charset=utf-8
request-id: f45d08c0-6901-473a-90f5-7867287de97f
client-request-id: f45d08c0-6901-473a-90f5-7867287de97f
OData-Version: 4.0
Date: Wed, 26 Apr 2017 19:53:49 GMT
Content-Length: 407
{
"@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users",
"value": [
{
"businessPhones": [],
"displayName": "Conf Room Adams",
"givenName": null,
"jobTitle": null,
"mail": "Adams@Contoso.com",
"mobilePhone": null,
"officeLocation": null,
"preferredLanguage": null,
"surname": null,
"userPrincipalName": "Adams@Contoso.com",
"id": "8afc02cb-4d62-4dba-b536-9f6d73e9be26"
},
{
"businessPhones": [
"+1 425 555 0109"
],
"displayName": "Adele Vance",
"givenName": "Adele",
"jobTitle": "Retail Manager",
"mail": "AdeleV@Contoso.com",
"mobilePhone": null,
"officeLocation": "18/2111",
"preferredLanguage": null,
"surname": "Vance",
"userPrincipalName": "AdeleV@Contoso.com",
"id": "59bb3898-0621-4414-ac61-74f9d7201355"
}
]
}
Unterstützte App-Szenarios und Ressourcen
Es gibt zwei Kategorien von Apps, die Microsoft Graph unter ihrer eigenen Identität aufrufen:
- Hintergrunddienste (Daemons), die auf einem Server ausgeführt werden, ohne dass ein Benutzer angemeldet ist.
- Apps, die über einen angemeldeten Benutzer verfügen, aber auch Microsoft Graph mit ihrer eigenen Identität aufrufen. Beispielsweise, um Funktionen zu verwenden, die höhere Berechtigungen erfordern als der Benutzer.
In diesem Artikel hat die App einen geheimen Clientschlüssel als Anmeldeinformationen verwendet. Optional können Sie ein Zertifikat oder Anmeldeinformationen für Verbundidentitäten konfigurieren.
Weitere Informationen zu Apps, die Microsoft Graph unter ihrer eigenen Identität aufrufen und den Clientanmeldeinformationsflow verwenden, finden Sie unter Authentifizierungsflows und Anwendungsszenarien: Daemon-App, die eine Web-API im Namen des Daemons aufruft.
Verwenden der Microsoft Authentication Library (MSAL)
In diesem Artikel haben Sie die Details des Low-Level-Protokolls beschrieben, die normalerweise nur beim manuellen Erstellen und Ausgeben von unformatierten HTTP-Anforderungen zum Ausführen des Clientanmeldeinformationsflows erforderlich sind. Verwenden Sie in Produktions-Apps eine von Microsoft erstellte oder unterstützte Authentifizierungsbibliothek, z. B. die Microsoft Authentication Library (MSAL), um Sicherheitstoken abzurufen und geschützte Web-APIs wie Microsoft Graph aufzurufen.
MSAL und andere unterstützte Authentifizierungsbibliotheken vereinfachen den Prozess für Sie, indem Sie Details wie Validierung, Cookieverarbeitung, Tokenzwischenspeicherung und sichere Verbindungen verarbeiten, sodass Sie sich auf die Funktionalität Ihrer Anwendung konzentrieren können.
Microsoft hat eine große Auswahl an Codebeispielen erstellt und verwaltet, die die Verwendung unterstützter Authentifizierungsbibliotheken mit dem Microsoft Identity Platform veranschaulichen. Informationen zum Zugriff auf diese Codebeispiele finden Sie in den Microsoft Identity Platform Codebeispielen.
Verwandte Inhalte
- Wählen Sie aus Codebeispielen, die von Microsoft erstellt und verwaltet werden, um benutzerdefinierte Apps auszuführen, die unterstützte Authentifizierungsbibliotheken verwenden, Benutzer anmelden und Microsoft Graph aufrufen. Weitere Informationen finden Sie unter Microsoft Graph-Tutorials.
Feedback
Bald verfügbar: Im Laufe des Jahres 2024 werden wir GitHub-Tickets als Feedbackmechanismus für Inhalte auslaufen lassen und es durch ein neues Feedbacksystem ersetzen. Weitere Informationen finden Sie unter: https://aka.ms/ContentUserFeedback.
Einreichen und Feedback anzeigen für