Zugreifen im Namen eines Benutzers

  • Artikel

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 im Namen eines Benutzers auf Microsoft Graph zugreifen kann, auch als delegierter Zugriff bezeichnet.

In diesem Artikel werden die unformatierten HTTP-Anforderungen beschrieben, die für eine App erforderlich sind, um zugriff im Namen eines Benutzers mithilfe eines beliebten Flows namens OAuth 2.0-Autorisierungscode-Genehmigungsflow zu erhalten. 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:

  1. Machen Sie sich mit den Authentifizierungs- und Autorisierungskonzepten im Microsoft Identity Platform vertraut. Weitere Informationen finden Sie unter Grundlagen zu Authentifizierung und Autorisierung.
  2. 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 mithilfe des Autorisierungscodeflows Autorisierung und Zugriff auf Microsoft Graph erhält, müssen Sie die folgenden fünf Schritte ausführen:

  1. Registrieren Sie die App bei Microsoft Entra ID.
  2. Autorisierung anfordern.
  3. Fordern Sie ein Zugriffstoken an.
  4. Aufrufen von Microsoft Graph unter Verwendung des Zugriffstokens
  5. [Optional] Verwenden Sie das Aktualisierungstoken, um ein abgelaufenes Zugriffstoken zu erneuern.

1. Registrieren der App

Bevor die App die Microsoft Identity Platform-Endpunkte oder Microsoft Graph aufrufen kann, muss sie ordnungsgemäß registriert werden. 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 Umleitungs-URI (oder Antwort-URL), damit die App Antworten von Microsoft Entra ID empfangen kann.
  • Ein geheimer Clientschlüssel (Anwendungskennwort), ein Zertifikat oder anmeldeinformationen für eine Verbundidentität. Diese Eigenschaft ist für öffentliche Clients wie native, mobile und Single-Page-Anwendungen nicht erforderlich.

2. Anfordern der Autorisierung

Der erste Schritt im Autorisierungscodeflow besteht darin, dass der Benutzer die App autorisiert, in ihrem Namen zu handeln.

Im Flow leitet die App den Benutzer an den Microsoft Identity Platform-Endpunkt /authorize um. Über diesen Endpunkt meldet Microsoft Entra ID den Benutzer an und fordert seine Zustimmung für die Von der App angeforderten Berechtigungen an. Nachdem die Zustimmung eingeholt wurde, geben Microsoft Entra ID einen Autorisierungscode an die App zurück. Die App kann diesen Code dann am Microsoft Identity Platform /token Endpunkt für ein Zugriffstoken einlösen.

Autorisierungsanforderung

Das folgende Beispiel zeigt eine Anforderung an den /authorize Endpunkt.

In der Anforderungs-URL rufen Sie den /authorize Endpunkt auf und geben die erforderlichen und empfohlenen Eigenschaften als Abfrageparameter an.

Im folgenden Beispiel fordert die App die Microsoft Graph-Berechtigungen User.Read und Mail.Read an, die es der App ermöglichen, das Profil bzw. die E-Mail des angemeldeten Benutzers zu lesen. Die offline_access-Berechtigung ist ein standardmäßiger OIDC-Bereich, der angefordert wird, damit die App ein Aktualisierungstoken abrufen kann. Die App kann das Aktualisierungstoken verwenden, um ein neues Zugriffstoken abzurufen, wenn das aktuelle abläuft.

// Line breaks for legibility only

GET https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize?
client_id=11111111-1111-1111-1111-111111111111
&response_type=code
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&response_mode=query
&scope=offline_access%20user.read%20mail.read
&state=12345  HTTP/1.1
Parameter
Parameter Erforderlich Beschreibung
tenant Erforderlich Mit dem Wert {tenant} im Pfad der Anforderung kann gesteuert werden, wer sich bei der Anwendung anmelden kann. Die folgenden Werte sind zulässig:
  • common sowohl für Microsoft- als auch für Geschäfts-, Schul- und Unikonten
  • organizations nur für Geschäfts-, Schul- oder Unikonten
  • consumers nur für Microsoft-Konten
  • Mandantenbezeichner wie die Mandanten-ID oder der Domänenname.
    Weitere Informationen finden Sie unter Protokollgrundlagen.
    		•
    client_id Erforderlich Die Anwendungs-ID (Client), die der App vom Registrierungsportal zugewiesen wurde. Wird im Microsoft Graph-Anwendungs- und Dienstprinzipalobjekt auch als appId bezeichnet.
    response_type Erforderlich Muss für den OAuth 2.0-Autorisierungscodefluss enthalten code sein.
    redirect_uri Empfohlen Der Umleitungs-URI der App, in der Authentifizierungsantworten an die App gesendet und von dieser empfangen werden. Sie muss genau mit einer der Umleitungs-URIs übereinstimmen, die Sie im App-Registrierungsportal registriert haben, mit der Ausnahme, dass sie URL-codiert sein muss. Für native und mobile Apps sollten Sie den Standardwert verwenden https://login.microsoftonline.com/common/oauth2/nativeclient.
    Bereich Erforderlich Eine durch Leerzeichen getrennte Liste von Microsoft Graph-Berechtigungen, denen der Benutzer zustimmen soll. Diese Berechtigungen können Ressourcenberechtigungen wie User.Read und Mail.Read sowie OIDC-Bereiche wie offline_accessenthalten, was angibt, dass die App ein Aktualisierungstoken für den langlebigen Zugriff auf Ressourcen benötigt.
    response_mode Empfohlen Gibt die Methode an, die verwendet werden soll, um das resultierende Token zurück an die App zu senden. Kann query oder form_post sein.
    state Empfohlen Ein in der Anforderung enthaltener Wert, der auch in der Tokenantwort zurückgegeben wird. Dabei kann es sich um eine Zeichenfolge mit beliebigen Inhalten handeln. Ein zufällig generierter eindeutiger Wert wird in der Regel verwendet , um siteübergreifende Anforderungsfälschungsangriffe zu verhindern. Diese Eigenschaft wird auch 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.

    Nachdem die App die Autorisierungsanforderung gesendet hat, wird der Benutzer aufgefordert, seine Anmeldeinformationen für die Authentifizierung bei Microsoft einzugeben. Der Microsoft Identity Platform v2.0-Endpunkt stellt sicher, dass der Benutzer den im scope Abfrageparameter angegebenen Berechtigungen zugestimmt hat. Wenn eine Berechtigung vorhanden ist, der der Benutzer oder Administrator nicht zugestimmt hat, wird er aufgefordert, den erforderlichen Berechtigungen zuzustimmen. Weitere Informationen zur Microsoft Entra Zustimmungserfahrung finden Sie unter Anwendungszustimmung und Einführung in Berechtigungen und Zustimmung.

    Der folgende Screenshot zeigt exemplarisch ein Zustimmungsdialogfeld, das für ein Microsoft-Konto Benutzer angezeigt wird.

    Zustimmungsdialogfeld für Microsoft-Konto

    Autorisierungsantwort

    Wenn der Benutzer den von der App angeforderten Berechtigungen zustimmt, enthält die Antwort den Autorisierungscode im code Parameter. Hier sehen Sie ein Beispiel für eine erfolgreiche Antwort auf die vorherige Anforderung. Da der response_mode Parameter in der Anforderung auf queryfestgelegt wurde, wird die Antwort in der Abfragezeichenfolge der Umleitungs-URL zurückgegeben.

    HTTP/1.1 200 OK

https://localhost/myapp/?code=M0ab92efe-b6fd-df08-87dc-2c6500a7f84d&state=12345&session_state=fe1540c3-a69a-469a-9fa3-8a2470936421#
    Abfrageparameter
    Parameter Beschreibung
    code Der von der App angeforderte Autorisierungscode. Die App verwendet den Autorisierungscode, um ein Zugriffstoken für die Zielressource anzufordern. Autorisierungscodes sind kurzlebig und laufen in der Regel nach etwa 10 Minuten ab.
    state Wenn in der Anforderung ein Zustandsparameter enthalten ist, sollte derselbe Wert in der Antwort angezeigt werden. Die App sollte überprüfen, ob die Zustandswerte in der Anforderung und Antwort identisch sind. Diese Überprüfung hilft bei der Erkennung von CSRF-Angriffen (Cross-Site Request Forgery) auf den Client.
    session_state Ein eindeutiger Wert, der die aktuelle Benutzersitzung identifiziert. Dieser Wert ist eine GUID, sollte jedoch als undurchsichtiger Wert behandelt werden, der ohne Prüfung transferiert wird.

    3. Anfordern eines Zugriffstokens

    Die App verwendet die im vorherigen Schritt empfangene Autorisierung code , um ein Zugriffstoken anzufordern, indem eine POST Anforderung an den /token Endpunkt gesendet wird.

    Tokenanforderung

    // Line breaks for legibility only

POST /{tenant}/oauth2/v2.0/token HTTP/1.1
Host: https://login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded

client_id=11111111-1111-1111-1111-111111111111
&scope=user.read%20mail.read
&code=OAAABAAAAiL9Kn2Z27UubvWFPbm0gLWQJVzCTE9UkP3pSx1aXxUjq3n8b2JRLk4OxVXr...
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&grant_type=authorization_code
&client_secret=HF8Q~Krjqh4r...    // NOTE: Only required for web apps
    Parameter
    Parameter Erforderlich Beschreibung
    tenant Erforderlich Mit dem Wert {tenant} im Pfad der Anforderung kann gesteuert werden, wer sich bei der Anwendung anmelden kann. Die folgenden Werte sind zulässig:
  • common sowohl für Microsoft- als auch für Geschäfts-, Schul- und Unikonten
  • organizations nur für Geschäfts-, Schul- oder Unikonten
  • consumers nur für Microsoft-Konten
  • Mandantenbezeichner wie die Mandanten-ID oder der Domänenname.
    Weitere Informationen finden Sie unter Protokollgrundlagen.
    		•
    client_id Erforderlich Die Anwendungs-ID (Client), die der App vom Registrierungsportal zugewiesen wurde. Wird im Microsoft Graph-Anwendungs- und Dienstprinzipalobjekt auch als appId bezeichnet.
    grant_type Erforderlich Muss authorization_code für den Autorisierungscodefluss sein.
    scope Erforderlich Eine durch Leerzeichen getrennte Liste von Bereichen. Die Bereiche, die Ihre App in diesem Abschnitt anfordert, müssen mit oder einer Teilmenge der Bereiche übereinstimmen, die sie im Autorisierungsschritt in Schritt 2 angefordert hat. Wenn die in dieser Anforderung angegebenen Bereiche mehrere Ressourcenserver umfassen, gibt der v2.0-Endpunkt ein Token für die im ersten Bereich angegebene Ressource zurück.
    code Erforderlich Der Autorisierungscode , den Sie im Autorisierungsabschnitt in Schritt 2 abgerufen haben.
    redirect_uri Erforderlich Derselbe Umleitungs-URI-Wert, der zum Abrufen des Autorisierungscodes in Schritt 2 verwendet wurde.
    client_secret Für Web-Apps erforderlich Der geheime Clientschlüssel, den Sie im App-Registrierungsportal für Ihre App erstellt haben. Sie sollte nicht in einer nativen App verwendet werden, da geheime Clientschlüssel nicht zuverlässig auf Geräten gespeichert werden können. Dies ist für Web-Apps und Web-APIs erforderlich, die die möglichkeit haben, die client_secret sicher auf der Serverseite zu speichern.

    Tokenantwort

    Das Zugriffstoken enthält eine Liste der Berechtigungen, für die das Zugriffstoken im scope Parameter geeignet ist. Die Antwort ähnelt dem folgenden Beispiel.

    HTTP/1.1 200 OK
Content-type: application/json

{
    "token_type": "Bearer",
    "scope": "Mail.Read User.Read",
    "expires_in": 3736,
    "ext_expires_in": 3736,
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...",
    "refresh_token": "AwABAAAAvPM1KaPlrEqdFSBzjqfTGAMxZGUTdM0t4B4..."
}
    Eigenschaften des Antworttexts
    Parameter Beschreibung
    token_type Gibt den Tokentypwert an. Der einzige Typ, der Microsoft Entra ID unterstützt, ist Bearer.
    Bereich Eine durch Leerzeichen getrennte Liste der Microsoft Graph-Berechtigungen, für die das Zugriffstoken gültig ist.
    expires_in Gültigkeit des Zugriffstokens (in Sekunden).
    ext_expires_in Gibt eine verlängerte Lebensdauer für das Zugriffstoken (in Sekunden) an und wird verwendet, um Resilienz zu unterstützen, wenn der Tokenausstellungsdienst nicht reagiert.
    access_token Das angeforderte Zugriffstoken. Die App kann dieses Token verwenden, um Microsoft Graph aufzurufen.
    refresh_token Ein OAuth 2.0-Aktualisierungstoken. Die App kann dieses Token verwenden, um zusätzliche Zugriffstoken abzurufen, nachdem das aktuelle Zugriffstoken abläuft. Aktualisierungstoken haben eine lange Lebensdauer und können verwendet werden, um für längere Zeit Zugriff auf Ressourcen zu behalten. Ein Aktualisierungstoken wird nur zurückgegeben, wenn offline_access als scope Parameter enthalten war. Weitere Informationen finden Sie in der v2.0-Tokenreferenz.

    4. 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 das Profil des angemeldeten Benutzers ab.

    Anforderung

    GET https://graph.microsoft.com/v1.0/me  HTTP/1.1
Authorization: Bearer eyJ0eXAiO ... 0X2tnSQLEANnSPHY0gKcgw
Host: graph.microsoft.com

    Antwort

    Eine erfolgreiche Antwort sieht in etwa 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
Duration: 727.0022
Date: Thu, 20 Apr 2017 05:21:18 GMT
Content-Length: 407

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users/$entity",
    "businessPhones": [
        "425-555-0100"
    ],
    "displayName": "MOD Administrator",
    "givenName": "MOD",
    "jobTitle": null,
    "mail": "admin@contoso.com",
    "mobilePhone": "425-555-0101",
    "officeLocation": null,
    "preferredLanguage": "en-US",
    "surname": "Administrator",
    "userPrincipalName": "admin@contoso.com",
    "id": "10a08e2e-3ea2-4ce0-80cb-d5fdd4b05ea6"
}

    5. Verwenden des Aktualisierungstokens zum Erneuern eines abgelaufenen Zugriffstokens

    Zugriffstoken sind kurzlebig, und die App muss sie nach ihrem Ablauf aktualisieren, um weiterhin auf Ressourcen zugreifen zu können. Die App sendet dazu eine weitere POST Anforderung an den /token Endpunkt. Dieses Mal:

    • Bereitstellen des refresh_token anstelle des Codes im Anforderungstext
    • Geben Sie refresh_token anstelle von authorization_codeals grant_type an.

    Anforderung

    // Line breaks for legibility only

POST /{tenant}/oauth2/v2.0/token HTTP/1.1
Host: https://login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded

client_id=11111111-1111-1111-1111-111111111111
&scope=user.read%20mail.read
&refresh_token=OAAABAAAAiL9Kn2Z27UubvWFPbm0gLWQJVzCTE9UkP3pSx1aXxUjq...
&grant_type=refresh_token
&client_secret=jXoM3iz...      // NOTE: Only required for web apps
    Parameter
    Parameter Erforderlich Beschreibung
    tenant Erforderlich Mit dem Wert {tenant} im Pfad der Anforderung kann gesteuert werden, wer sich bei der Anwendung anmelden kann. Die folgenden Werte sind zulässig:
  • common sowohl für Microsoft- als auch für Geschäfts-, Schul- und Unikonten
  • organizations nur für Geschäfts-, Schul- oder Unikonten
  • consumers nur für Microsoft-Konten
  • Mandantenbezeichner wie die Mandanten-ID oder der Domänenname.
    Weitere Informationen finden Sie unter Protokollgrundlagen.
    		•
    client_id Erforderlich Die Anwendungs-ID (Client), die Ihrer App vom Registrierungsportal zugewiesen wurde. Wird im Microsoft Graph-Anwendungs- und Dienstprinzipalobjekt auch als appId bezeichnet.
    grant_type Erforderlich Muss refresh_token sein.
    scope Optional Eine durch Leerzeichen getrennte Liste von Berechtigungen (Bereichen). Die Berechtigungen, die Ihre App anfordert, müssen mit oder einer Teilmenge der Berechtigungen übereinstimmen, die sie in der ursprünglichen Autorisierungscodeanforderung in Schritt 2 angefordert hat.
    refresh_token Erforderlich Die refresh_token, die Ihre App während der Tokenanforderung in Schritt 3 abgerufen hat.
    client_secret Für Web-Apps erforderlich Der geheime Clientschlüssel, den Sie im App-Registrierungsportal für Ihre App erstellt haben. Verwenden Sie das Geheimnis nicht in einer nativen App, da client_secrets nicht zuverlässig auf Geräten gespeichert werden können. Dies ist für Web-Apps und Web-APIs erforderlich, die die möglichkeit haben, die client_secret sicher auf der Serverseite zu speichern.

    Antwort

    Eine erfolgreiche Tokenantwort sieht in etwa wie folgt aus.

    HTTP/1.1 200 OK
Content-type: application/json

{
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...",
    "token_type": "Bearer",
    "expires_in": 3599,
    "scope": "Mail.Read User.Read",
    "refresh_token": "AwABAAAAvPM1KaPlrEqdFSBzjqfTGAMxZGUTdM0t4B4...",
}
    Antworttextparameter
    Parameter Beschreibung
    access_token Das angeforderte Zugriffstoken. Die App kann dieses Token in Aufrufen von Microsoft Graph verwenden.
    token_type Gibt den Tokentypwert an. Der einzige Typ, der Microsoft Entra ID unterstützt, ist Bearer.
    expires_in Gültigkeit des Zugriffstokens (in Sekunden).
    scope Die Berechtigungen (Bereiche), für die das Zugriffstoken gültig ist.
    refresh_token Ein neues OAuth 2.0-Aktualisierungstoken. Ersetzen Sie das alte Aktualisierungstoken durch dieses neu abgerufene Aktualisierungstoken, um sicherzustellen, dass Ihre Aktualisierungstoken so lange wie möglich gültig bleiben.

    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 Autorisierungscodeflows 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

    • Sie können Microsoft Graph im Namen eines Benutzers aus verschiedenen Arten von Apps aufrufen, z. B. Single-Page-Apps, Web-Apps und mobile Apps. Weitere Informationen finden Sie unter Szenarien und unterstützte Authentifizierungsflows.
    • 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.