Feedback Bearbeiten

Ohne Benutzer zugreifen

  • Artikel
  • 9 Minuten Lesedauer

Einige Apps rufen Microsoft Graph mit ihrer eigenen Identität und nicht im Namen eines Benutzers auf. In vielen Fällen handelt es sich bei diesen Apps um Hintergrunddienste oder Daemons, die auf einem Server ausgeführt werden, ohne dass ein Benutzer angemeldet ist. Ein Beispiel für eine solche App ist ein E-Mail-Archivierungsdienst, der nachts reaktiviert und ausgeführt wird. In einigen Fällen rufen Apps, bei deren Ausführung ein Benutzer angemeldet ist, Microsoft Graph auch unter ihrer eigenen Identität auf. Beispiel: Eine App muss Funktionen verwenden, die höhere Rechte in einer Organisation erfordern als jene, über die der angemeldete Benutzer verfügen mag.

Apps, die Microsoft Graph mit ihrer eigenen Identität aufrufen, verwenden den Fluss zur Gewährung von OAuth 2.0 -Clientanmeldeinformationen, um Zugriffstoken von Azure AD abzurufen. Dieser Artikel beschreibt schrittweise das grundlegende Verfahren zum Konfigurieren eines Diensts und zum Verwenden des Flusses zur Gewährung von OAuth-Clientanmeldeinformationen, um ein Zugriffstoken abzurufen.

Authentifizierungs- und Autorisierungsschritte

Befolgen Sie diese grundlegenden Schritte zum Konfigurieren eines Dienstes und zum Abrufen eines Tokens vom Microsoft Identity Platform-Endpunkt, mit dem Ihr Dienst Microsoft Graph unter seiner eigenen Identität aufrufen kann.

  1. Registrieren der App
  2. Konfigurieren von Berechtigungen für Microsoft Graph in der App
  3. Einholen der Administratorzustimmung
  4. Abrufen eines Zugriffstokens
  5. Aufrufen von Microsoft Graph unter Verwendung des Zugriffstokens

1. Registrieren der App

Für die Authentifizierung beim Microsoft Identity Platform-Endpunkt müssen Sie Ihre App zunächst im Azure App-Registrierungsportal registrieren. Sie können entweder ein Microsoft-Konto oder ein Geschäfts-, Schul- oder Unikonto zum Registrieren Ihrer App verwenden.

Für einen Dienst, der Microsoft Graph unter seiner eigenen Identität aufrufen soll, müssen Sie Ihre App für die Webplattform registrieren und die folgenden Werte kopieren:

  • Die Anwendung-ID, die vom Azure-App-Registrierungsportal zugewiesen wurde.
  • Ein geheimer Clientschlüssel oder ein Anwendungsgeheimnis, entweder ein Kennwort oder ein öffentliches/privates Schlüsselpaar (Zertifikat).
  • Eine Umleitungs-URL, damit der Dienst Tokenantworten empfangen kann.
  • Eine Umleitungs-URL, damit der Dienst Antworten mit Administratorzustimmung empfangen kann, wenn Ihre App Funktionen zum Anfordern der Administratorzustimmung implementiert.

Schritte zum Konfigurieren einer App mit dem Azure-App-Registrierungsportal finden Sie unter Apps registrieren.

Mit dem Fluss zur Gewährung von OAuth 2.0-Clientanmeldeinformationen authentifiziert sich Ihre App direkt beim Microsoft Identity Platform/token-Endpunkt, und zwar unter Verwendung der von Azure AD zugewiesenen Anwendungs-ID und des mit dem Portal erstellten geheimen Clientschlüssels.

2. Konfigurieren von Berechtigungen für Microsoft Graph

Microsoft Graph stellt Anwendungsberechtigungen für Apps zur Verfügung, die Microsoft Graph unter ihrer eigenen Identität aufrufen (Microsoft Graph macht auch delegierte Berechtigungen für Apps verfügbar, die Microsoft Graph im Namen eines Benutzers aufrufen).

Sie konfigurieren diese Anwendungsberechtigungen vorab, wenn Sie Ihre App registrieren. Anwendungsberechtigungen erfordern immer die Zustimmung eines Administrators. Ein Administrator kann diesen Berechtigungen entweder im Azure-Portal zustimmen, wenn die App in seiner Organisation installiert wird, oder Sie können eine Anmeldefunktionalität in der App bereitstellen, über die Administratoren den von Ihnen konfigurierten Berechtigungen zustimmen können. Sobald die Administratorzustimmung von Azure AD aufgezeichnet wurde, kann Ihre App Token anfordern, ohne dass eine erneute Zustimmung erforderlich ist. Ausführliche Informationen zu den in Microsoft Graph verfügbaren Berechtigungen finden Sie in der Berechtigungsreferenz.

Um Anwendungsberechtigungen für Ihre App im Azure-App-Registrierungsportal zu konfigurieren, wählen Sie unter den API-Berechtigungen einer Anwendung die Option Berechtigung hinzufügen aus, wählen Sie Microsoft Graph, und wählen Sie dann die von Ihrer App benötigten Berechtigungen im Dialogfeld Anwendungsberechtigungen aus.

Der folgende Screenshot zeigt das Dialogfeld Berechtigungen auswählen für Microsoft Graph-Anwendungsberechtigungen.

Wählen Sie das Fenster „Berechtigungen“ für Microsoft Graph-Anwendungsberechtigungen aus.

Wichtig

Konfigurieren Sie den Berechtigungssatz mit den geringsten Berechtigungen, die von Ihrer App zur Verbesserung der Sicherheit benötigt werden. Weitere Informationen finden Sie unter Verbessern der Sicherheit mit dem Prinzip der geringsten Berechtigung.

Ein Administrator kann für Sie die Berechtigungen, die Ihre App benötigt, im Azure-Portal gewähren, häufig ist es jedoch besser, Administratoren eine Anmeldefunktionalität über den Microsoft Identity Platform/adminconsent-Endpunkt zur Verfügung zu stellen.

Wichtig

Wenn Sie Änderungen an den konfigurierten Berechtigungen vornehmen, müssen Sie auch den Prozess für die Administratorzustimmung wiederholen. Im App-Registrierungsportal vorgenommene Änderungen werden nicht wiedergegeben, bis die Zustimmung des Mandantenadministrators erneut erteilt wurde.

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
Parameter Bedingung Beschreibung
tenant Erforderlich Der Verzeichnismandant, von dem Sie eine Berechtigung anfordern möchten. Dieser Wert kann im GUID- oder Anzeigenamenformat angegeben werden. Wenn Sie nicht wissen, zu welchem Mandanten der Benutzer gehört, und Sie eine Anmeldung mit jedem Mandanten ermöglichen möchten, 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 für die Weiterarbeitung durch Ihre App gesendet werden soll. Er muss mit einem der Umleitung-URIs übereinstimmen, die Sie im Portal registriert haben. Er muss URL-codiert sein muss und kann zusätzliche Pfadsegmente enthalten.
state Empfohlen Ein Wert, der in der Anforderung enthalten ist und ebenfalls in der Tokenantwort zurückgegeben wird. Es kann eine Zeichenfolge beliebigen Inhalts sein. Der Status wird verwendet, um Informationen über den Status des Benutzers in der App vor dem Versand der Authentifizierungsanforderung zu codieren, z. B. die Seite oder die Ansicht, auf bzw. in der sich der Benutzer befunden hat.

Bei an den /adminconsent-Endpunkt gesendeten Anforderungen erzwingt Azure AD, dass sich nur ein Mandantenadministrator anmelden kann, um die Anforderung auszuführen. Der Administrator wird aufgefordert, alle Anwendungsberechtigungen zu genehmigen, die Sie für Ihre App im App-Registrierungsportal angefordert haben.

Der folgende Screenshot zeigt exemplarisch das Zustimmungsdialogfeld, das dem Administrator von Azure AD angezeigt wird:

Dialogfeld zur Administratorzustimmung

Antwort

Wenn der Administrator die Berechtigungen für Ihre Anwendung genehmigt, sieht die erfolgreiche Antwort wie folgt aus:

// Line breaks are for legibility only.

GET https://localhost/myapp/permissions
?tenant=a8990e1f-ff32-408a-9f8e-78d3b9139b95&state=12345
&admin_consent=True
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 und ebenfalls in der Tokenantwort zurückgegeben wird. Es kann eine Zeichenfolge beliebigen Inhalts sein. Der Status wird verwendet, um Informationen über den Status des Benutzers in der App vor dem Versand der Authentifizierungsanforderung zu codieren, z. B. die Seite oder die Ansicht, auf bzw. in der sich der Benutzer befunden hat.
admin_consent Auf true festgelegt.

Testen: Sie können dies selbst ausprobieren, indem Sie die Anforderung unten in einen Browser einfügen. Wenn Sie sich als globaler Administrator für einen Azure AD-Mandanten anmelden, wird Ihnen das Dialogfeld zur Administratorzustimmung für die App angezeigt. (Dies ist eine andere App als die zuvor im Screenshot des Dialogfelds zur Administratorzustimmung abgebildete.)

https://login.microsoftonline.com/common/adminconsent?client_id=6731de76-14a6-49ae-97bc-6eba6914391e&state=12345&redirect_uri=https://localhost/myapp/permissions

4. Abrufen 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 https://graph.microsoft.com/.default als Wert für den scope-Parameter in der Tokenanforderung übergeben. Einzelheiten finden Sie in der Beschreibung zum scope-Parameter in der nachstehenden Tokenanforderung.

Tokenanforderung

Sie senden eine POST-Anforderung an den Identity Platform/token-Endpunkt, um ein Zugriffstoken abzurufen:

// 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 eine Berechtigung anfordern möchten. Dieser Wert kann im GUID- oder in einem Anzeigenamenformat angegeben werden.
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 er 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. Dieses Token kann die App in Aufrufen verwenden, die an Microsoft Graph gesendet werden.
expires_in Gültigkeit des Zugriffstokens (in Sekunden).
ext_expires_in Wird verwendet, um eine verlängerte Lebensdauer des Zugriffstokens anzugeben und Ausfallsicherheit zu unterstützen, wenn der Tokenausstellungsdienst nicht antwortet.
token_type Gibt den Tokentypwert an. Der einzige von Azure AD unterstützte Typ ist Bearer.

5. Aufrufen von Microsoft Graph unter Verwendung des Zugriffstokens

Sobald Sie über ein Zugriffstoken verfügen, können Sie damit Microsoft Graph aufrufen, indem Sie das Token in den Authorization-Header einer Anforderung einschließen. Die folgende Anforderung ruft das Profil eines bestimmten Benutzers ab. Ihre App muss über die Berechtigung User.Read.All verfügen, um diese API aufzurufen.

GET https://graph.microsoft.com/v1.0/users/12345678-73a6-4952-a53a-e9916737ff7f
Authorization: Bearer eyJ0eXAiO ... 0X2tnSQLEANnSPHY0gKcgw
Host: graph.microsoft.com

Eine erfolgreiche Antwort sieht ähnlich wie die folgende 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: 309.0273
Date: Wed, 26 Apr 2017 19:53:49 GMT
Content-Length: 407

{
    "@odata.context":"https://graph.microsoft.com/v1.0/$metadata#users/$entity",
    "id":"12345678-73a6-4952-a53a-e9916737ff7f",
    "businessPhones":[
        "+1 555555555"
    ],
    "displayName":"Chris Green",
    "givenName":"Chris",
    "jobTitle":"Software Engineer",
    "mail":null,
    "mobilePhone":"+1 5555555555",
    "officeLocation":"Seattle Office",
    "preferredLanguage":null,
    "surname":"Green",
    "userPrincipalName":"ChrisG@contoso.onmicrosoft.com"
}

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, bei deren Ausführung ein Benutzer angemeldet ist, die Microsoft Graph aber auch unter ihrer eigenen Identität aufrufen, z. B. um Funktionen zu verwenden, die höhere Berechtigungen erfordern als jene, über die der Benutzer verfügt.

Apps, die Microsoft Graph mit ihrer eigenen Identität aufrufen, verwenden den Fluss zur Gewährung von OAuth 2.0-Clientanmeldeinformationen, um sich bei Azure AD zu authentifizieren und ein Token abzurufen. Für den Microsoft Identity Platform-Endpunkt können Sie dieses Szenario mit den folgenden Ressourcen weiter untersuchen:

Überlegungen zum Endpunkt

Microsoft wird weiterhin den Endpunkt Azure AD unterstützen. Es gibt einige Unterschiede zwischen der Verwendung des Microsoft Identity Platform-Endpunkts und des Azure AD-Endpunkts. Bei der Verwendung des Azure AD-Endpunkts:

  • Wenn Ihre App mehrinstanzenfähig ist, müssen Sie sie im Azure-Portal explizit als mehrinstanzenfähig konfigurieren.
  • Es gibt keinen Endpunkt für die Administratorzustimmung, stattdessen kann Ihre App die Administratorzustimmung während der Laufzeit anfordern, indem Sie den Parameter prompt=admin_consent zu einer Autorisierungsanforderung hinzufügen. Weitere Informationen finden Sie unter Auslösen von Azure AD-Consent Framework zur Laufzeit unter Integrieren von Anwendungen in Azure Active Directory.
  • Die Parameter in Autorisierungs- und Tokenanforderungen sind verschieden. Es gibt z. B. keinen scope-Parameter in Azure AD-Endpunktanforderungen; stattdessen wird der resource-Parameter verwendet, um den URI der Ressource anzugeben (resource=https://graph.microsoft.com), für die Autorisierung (für Administratorzustimmung) oder ein Token angefordert wird.

Sie können dieses Szenario mit den folgenden Ressourcen weiter untersuchen:

  • Weitere Informationen zur Verwendung des Microsoft Identity Platform-Endpunkts mit verschiedenen Arten von Anwendungen finden Sie unter Erste Schritte-Links in der Microsoft Identity Platform-Dokumentation.
  • Informationen zur Microsoft Authentication Library (MSAL) und Servermiddleware für die Verwendung mit dem Microsoft Identity Platform-Endpunkt finden Sie unter Microsoft-Authentifizierungsbibliotheken.

Siehe auch