Beheerderstoestemming op het Microsoft Identity-platform

  • Artikel

Voor sommige machtigingen is toestemming van een beheerder vereist voordat ze binnen een tenant kunnen worden verleend. U kunt ook het eindpunt voor beheerderstoestemming gebruiken om machtigingen te verlenen aan een hele tenant.

Wanneer u een toepassing bouwt die gebruikmaakt van het eindpunt voor beheerderstoestemming, heeft de app doorgaans een pagina of weergave nodig waarin de beheerder de machtigingen van de app kan goedkeuren. Deze pagina kan deel uitmaken van de registratiestroom van de app, een deel van de instellingen van de app of een toegewezen stroom voor verbinding maken. In veel gevallen is het logisch dat de app deze weergave 'verbinding maken' alleen weergeeft nadat een gebruiker zich heeft aangemeld met een Microsoft-werk- of schoolaccount.

Wanneer u de gebruiker aanmeldt bij uw app, kunt u de organisatie identificeren waartoe de beheerder behoort voordat u de gebruiker vraagt de benodigde machtigingen goed te keuren. Hoewel dit niet strikt noodzakelijk is, kunt u hiermee een intuïtievere ervaring maken voor uw gebruikers van uw organisatie.

De machtigingen aanvragen van een directorybeheerder

Wanneer u klaar bent om machtigingen aan te vragen van de beheerder van uw organisatie, kunt u de gebruiker omleiden naar het eindpunt van de Microsoft Identity Platform-beheerderstoestemming.

https://login.microsoftonline.com/{tenant}/v2.0/adminconsent
        ?client_id=535fb089-9ff3-47b6-9bfb-4f1264799865
        &scope=https://graph.microsoft.com/Calendars.Read https://graph.microsoft.com/Mail.Send
        &redirect_uri=http://localhost/myapp/permissions
        &state=12345
Parameter Voorwaarde Beschrijving
tenant Vereist De directorytenant waaruit u toestemming wilt aanvragen. Kan worden opgegeven in GUID of beschrijvende naamnotatie OF algemeen waarnaar wordt verwezen organizations, zoals in het voorbeeld wordt weergegeven. Gebruik 'common' niet, aangezien persoonlijke accounts geen toestemming van de beheerder kunnen geven, behalve in de context van een tenant. Gebruik indien mogelijk de tenant-id om de beste compatibiliteit te garanderen met persoonlijke accounts die tenants beheren.
client_id Vereist De toepassings-id (client) die door het Microsoft Entra-beheercentrum wordt App-registraties ervaring toegewezen aan uw app.
redirect_uri Vereist De URI voor omleiding waar u wilt dat het antwoord wordt verzonden voor uw app. Deze moet exact overeenkomen met een van de omleidings-URI's die u hebt geregistreerd in de app-registratieportal.
state Aanbevolen Een waarde die is opgenomen in de aanvraag die ook wordt geretourneerd in het tokenantwoord. Het kan een tekenreeks zijn van elke door u gewenste inhoud. Gebruik de status voor het coderen van informatie over de status van de gebruiker in de app voordat de verificatieaanvraag is opgetreden, zoals de pagina of weergave waarop ze zich bevonden.
scope Vereist Hiermee definieert u de set machtigingen die door de toepassing worden aangevraagd. Bereiken kunnen statische (met gebruik van /.default) of dynamische bereiken zijn. Dit kan de OIDC-bereiken (openid, profile of email) omvatten.

Op dit moment is voor Microsoft Entra-id een tenantbeheerder vereist om zich aan te melden om de aanvraag te voltooien. De beheerder wordt gevraagd alle machtigingen goed te keuren die u in de parameter scope hebt aangevraagd. Als u een statische waarde (/.default) hebt gebruikt, werkt deze als het eindpunt voor v1.0-beheerderstoestemming en vraagt u toestemming aan voor alle bereiken die zijn gevonden in de vereiste machtigingen voor de app (gebruiker en app). Als u app-machtigingen wilt aanvragen, moet u de /.default waarde gebruiken. Als u niet wilt dat beheerders een bepaalde machtiging constant zien in het scherm voor beheerderstoestemming bij gebruik van /.default, is het raadzaam om de machtiging niet in de sectie vereiste machtigingen te plaatsen. In plaats daarvan kunt u dynamische toestemming gebruiken om de machtigingen toe te voegen die u tijdens runtime in het toestemmingsscherm wilt hebben, in plaats van /.default te gebruiken.

Succesvolle respons

Als de beheerder de machtigingen voor uw app goedkeurt, ziet het geslaagde antwoord er als volgt uit:

http://localhost/myapp/permissions
    ?admin_consent=True
    &tenant=fa00d692-e9c7-4460-a743-29f2956fd429
    &scope=https://graph.microsoft.com/Calendars.Read https://graph.microsoft.com/Mail.Send
    &state=12345
Parameter Description
tenant De directorytenant die uw toepassing de benodigde machtigingen heeft toegekend, in GUID-indeling.
state Een waarde die is opgenomen in de aanvraag die ook wordt geretourneerd in het tokenantwoord. Het kan een tekenreeks zijn van elke door u gewenste inhoud. De status wordt gebruikt voor het coderen van informatie over de status van de gebruiker in de app voordat de verificatieaanvraag is opgetreden, zoals de pagina of weergave waarop ze zich bevonden.
scope De set machtigingen waartoe toegang is verleend voor de toepassing.
admin_consent Wordt ingesteld op True.

Waarschuwing

Gebruik nooit de tenant-id-waarde van de tenant parameter om gebruikers te verifiëren of te autoriseren. De tenant-id-waarde kan worden bijgewerkt en verzonden door slechte actoren om een reactie op uw app te imiteren. Dit kan ertoe leiden dat uw toepassing wordt blootgesteld aan beveiligingsincidenten.

Foutrespons

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+d320620c-3d56-42bc-bc45-4cdd85c41f00%0d%0aCorrelation+ID%3a+8478d534-5b2c-4325-8c2c-51395c342c89%0d%0aTimestamp%3a+2019-09-24+18%3a34%3a26Z
        &state=12345

Toevoegen aan de parameters wordt als geslaagd antwoord, foutparameters worden weergegeven zoals hieronder.

Parameter Description
error Een foutcodereeks die kan worden gebruikt voor het classificeren van typen fouten die optreden en die kan worden gebruikt om op fouten te reageren.
error_description Een specifiek foutbericht waarmee een ontwikkelaar de hoofdoorzaak van een fout kan identificeren.
state Een waarde die is opgenomen in de aanvraag die ook wordt geretourneerd in het tokenantwoord. Het kan een tekenreeks zijn van elke door u gewenste inhoud. De status wordt gebruikt voor het coderen van informatie over de status van de gebruiker in de app voordat de verificatieaanvraag is opgetreden, zoals de pagina of weergave waarop ze zich bevonden.
admin_consent Wordt ingesteld op True om aan te geven dat dit antwoord is opgetreden in een stroom voor beheerderstoestemming.

Volgende stappen