Administratoreinwilligung auf Microsoft Identity Platform
Einige Berechtigungen erfordern eine Administratoreneinwilligung, bevor sie innerhalb eines Mandanten erteilt werden können. Sie können auch den Endpunkt für die Administratoreinwilligung verwenden, um Berechtigungen für einen gesamten Mandanten zu erteilen.
Empfohlen: Anmelden des Benutzers bei Ihrer App
Beim Erstellen einer Anwendung, die den Endpunkt für die Administratorzustimmung verwendet, benötigt die App in der Regel eine Seite/Ansicht, die dem Administrator das Genehmigen der App-Berechtigungen gestattet. Diese Seite kann Teil des Anmelde-Flows der App, Teil der App-Einstellungen oder ein dedizierter Flow „Verbinden“ sein. In vielen Fällen ist es sinnvoll, wenn die App diese Ansicht „Verbinden“ erst anzeigt, wenn ein Benutzer sich mit einem Geschäfts-, Schul- oder Unikonto von Microsoft angemeldet hat.
Durch das Anmelden des Benutzers bei der App können Sie die Organisation identifizieren, der der Administrator angehört, bevor Sie zur Genehmigung der nötigen Berechtigungen auffordern. Auch wenn es nicht unbedingt erforderlich ist, können Sie für Ihre Organisationsbenutzer auf diese Weise eine intuitivere Benutzeroberfläche erstellen.
Anfordern der Berechtigungen von einem Verzeichnisadministrator
Wenn Sie dazu bereit sind, vom Administrator der Organisation Berechtigungen anzufordern, können Sie den Benutzer zum Endpunkt für die Administratorzustimmung von Microsoft Identity Platform umleiten.
https://login.microsoftonline.com/{tenant}/v2.0/adminconsent
?client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&scope=https://graph.microsoft.com/Calendars.Read https://graph.microsoft.com/Mail.Send
&redirect_uri=http://localhost/myapp/permissions
&state=12345
Parameter | Condition | Beschreibung |
---|---|---|
tenant |
Erforderlich | Der Verzeichnismandant, von dem Sie die Berechtigung anfordern möchten. Kann als eindeutiger Bezeichner oder Anzeigename bereitgestellt oder mit organizations generisch referenziert werden, wie im Beispiel gezeigt. Verwenden Sie nicht „Allgemein“, weil persönliche Konten die Administratoreinwilligung nur im Kontext eines Mandanten bereitstellen können. Um die bestmögliche Kompatibilität mit persönlichen Konten sicherzustellen, die Mandanten verwalten, sollten Sie nach Möglichkeit die Mandanten-ID verwenden. |
client_id |
Erforderlich | Die Anwendungs-ID (Client-ID), die Ihrer App auf der Benutzeroberfläche „App-Registrierungen“ im Microsoft Entra Admin Center zugewiesen ist. |
redirect_uri |
Erforderlich | Der Umleitungs-URI, an den die Antwort zur Verarbeitung durch die App gesendet werden soll. Er muss genau mit einem der Umleitungs-URIs übereinstimmen, die Sie im Portal registriert haben. |
state |
Empfohlen | Ein in der Anforderung enthaltener Wert, der auch in der Antwort zurückgegeben wird. Es kann sich um eine Zeichenfolge mit jedem beliebigen Inhalt handeln. Der Status wird verwendet, um Informationen über den Status des Benutzers in der App zu codieren, bevor die Authentifizierungsanforderung aufgetreten ist, z.B. Informationen zu der Seite oder Ansicht, die der Benutzer besucht hat. |
scope |
Erforderlich | Definiert den von der Anwendung angeforderten Satz an Berechtigungen. Dies können statische (mit /.default ) oder dynamische Bereiche sein. Dies kann auch die OIDC-Bereiche (openid , profile , email ) einschließen. |
An diesem Punkt erzwingt Microsoft Entra ID, dass sich nur ein Mandantenadministrator anmelden kann, um die Anforderung abzuschließen. Der Administrator wird aufgefordert, alle Berechtigungen zu genehmigen, die Sie für den Parameter scope
angefordert haben. Wenn Sie einen statischen Wert (/.default
) verwendet haben, funktioniert er wie der v1.0-Endpunkt für die Administratoreinwilligung und fordert die Zustimmung für alle Bereiche an, die in den erforderlichen Berechtigungen gefunden werden (Benutzer und App). Zum Anfordern von App-Berechtigungen muss der Wert /.default
verwendet werden. Wenn Administratoren bei Verwendung von /.default
eine bestimmte Berechtigung nicht jedes Mal auf dem Bildschirm für die Administratoreinwilligung angezeigt werden soll, empfiehlt es sich, die Berechtigung nicht im Abschnitt für erforderliche Berechtigungen zu platzieren. Stattdessen können Sie eine dynamische Einwilligung verwenden, um die gewünschten Berechtigungen für den Einwilligungsbildschirm zur Laufzeit hinzuzufügen, anstatt /.default
zu verwenden.
Erfolgreiche Antwort
Wenn der Administrator die Berechtigungen für Ihre Anwendung genehmigt, lautet die erfolgreiche Antwort wie folgt:
http://localhost/myapp/permissions
?admin_consent=True
&tenant=aaaabbbb-0000-cccc-1111-dddd2222eeee
&scope=https://graph.microsoft.com/Calendars.Read https://graph.microsoft.com/Mail.Send
&state=12345
Parameter | BESCHREIBUNG |
---|---|
tenant |
Der Verzeichnismandant, der Ihrer Anwendung die angeforderten Berechtigungen erteilt hat, im GUID-Format. |
state |
Ein in der Anforderung enthaltener Wert, der auch in der Tokenantwort zurückgegeben wird. Es kann sich um eine Zeichenfolge mit jedem beliebigen Inhalt handeln. Der Status wird verwendet, um Informationen über den Status des Benutzers in der App zu codieren, bevor die Authentifizierungsanforderung aufgetreten ist, z.B. Informationen zu der Seite oder Ansicht, die der Benutzer besucht hat. |
scope |
Die Berechtigungen, zu denen der App Zugang gewährt wurde. |
admin_consent |
Wird auf True festgelegt. |
Warnung
Verwenden Sie niemals den Wert der Mandanten-ID des tenant
-Parameters, um Benutzer zu authentifizieren oder zu autorisieren. Der Wert der Mandanten-ID kann aktualisiert und von schädlichen Akteuren gesendet werden, um eine Antwort auf Ihre App zu imitieren. Dies kann dazu führen, dass Ihre Anwendung Sicherheitsincidents ausgesetzt wird.
Fehlerantwort
http://localhost/myapp/permissions
?admin_consent=True
&error=consent_required
&error_description=AADSTS65004%3a+The+resource+owner+or+authorization+server+denied+the+request.%0d%0aTrace+ID%3a+0000aaaa-11bb-cccc-dd22-eeeeee333333%0d%0aCorrelation+ID%3a+8478d534-5b2c-4325-8c2c-51395c342c89%0d%0aTimestamp%3a+2019-09-24+18%3a34%3a26Z
&state=12345
Wenn Sie zu den Parametern hinzugefügt werden, die in einer erfolgreichen Antwort angezeigt werden, werden Fehlerparameter wie unten dargestellt.
Parameter | BESCHREIBUNG |
---|---|
error |
Eine Fehlercodezeichenfolge, die verwendet werden kann, um unterschiedliche Arten auftretender Fehler zu klassifizieren und um auf Fehler zu reagieren. |
error_description |
Eine spezifische Fehlermeldung, mit der ein Entwickler die Grundursache eines Fehlers identifizieren kann. |
state |
Ein in der Anforderung enthaltener Wert, der auch in der Tokenantwort zurückgegeben wird. Es kann sich um eine Zeichenfolge mit jedem beliebigen Inhalt handeln. Der Status wird verwendet, um Informationen über den Status des Benutzers in der App zu codieren, bevor die Authentifizierungsanforderung aufgetreten ist, z.B. Informationen zu der Seite oder Ansicht, die der Benutzer besucht hat. |
admin_consent |
Wird auf True festgelegt, um anzugeben, dass diese Antwort bei einem Datenfluss zur Administratoreinwilligung aufgetreten ist. |
Nächste Schritte
- Lesen Sie die Informationen unter Anmelden von Azure Active Directory-Benutzern mit dem mehrinstanzenfähigen Anwendungsmuster.
- Ausführlichere Informationen zur OAuth 2.0-Protokollunterstützung für Zustimmung während des Flows zum Gewähren des Autorisierungscodes.
- Ausführlichere Informationen zur Verwendung des Zustimmungsframeworks durch mehrinstanzenfähige Anwendungen zur Implementierung von Benutzer- und Administratoreinwilligung mit Unterstützung für erweiterte Anwendungsmuster mit mehreren Ebenen.
- Grundlegendes zu Microsoft Entra-Anwendungsgenehmigungen