Administratörsmedgivande på Microsoft-identitetsplattformen

  • Artikel

Vissa behörigheter kräver medgivande från en administratör innan de kan beviljas i en klientorganisation. Du kan också använda slutpunkten för administratörsmedgivande för att bevilja behörigheter till en hel klientorganisation.

När du skapar ett program som använder slutpunkten för administratörsmedgivande behöver appen vanligtvis en sida eller vy där administratören kan godkänna appens behörigheter. Den här sidan kan vara en del av appens registreringsflöde, en del av appens inställningar eller ett dedikerat "anslut"-flöde. I många fall är det klokt att appen visar den här "connect"-vyn först när en användare har loggat in med ett Microsoft-konto för arbete eller skola.

När du loggar in användaren i din app kan du identifiera den organisation som administratören tillhör innan du ber dem att godkänna nödvändiga behörigheter. Även om det inte är absolut nödvändigt kan det hjälpa dig att skapa en mer intuitiv upplevelse för organisationens användare.

Begära behörigheter från en katalogadministratör

När du är redo att begära behörigheter från organisationens administratör kan du omdirigera användaren till slutpunkten för Microsofts identitetsplattform administratörsmedgivande.

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 Villkor beskrivning
tenant Obligatoriskt Den katalogklient som du vill begära behörighet från. Kan anges i GUID- eller eget namnformat ELLER allmänt refereras till enligt organizations exemplet. Använd inte "common", eftersom personliga konton inte kan ge administratörsmedgivande förutom i kontexten för en klientorganisation. För att säkerställa bästa kompatibilitet med personliga konton som hanterar klienter använder du klientorganisations-ID:t när det är möjligt.
client_id Obligatoriskt Det program-ID (klient)-ID som administrationscentret för Microsoft Entra – Appregistreringar upplevelse som tilldelats din app.
redirect_uri Obligatoriskt Omdirigerings-URI:n där du vill att svaret ska skickas för din app att hantera. Den måste exakt matcha en av de omdirigerings-URI:er som du registrerade i appregistreringsportalen.
state Rekommenderat Ett värde som ingår i begäran som också returneras i tokensvaret. Det kan vara en sträng med valfritt innehåll. Använd tillståndet för att koda information om användarens tillstånd i appen innan autentiseringsbegäran inträffade, till exempel sidan eller vyn de var på.
scope Obligatoriskt Definierar den uppsättning behörigheter som begärs av programmet. Detta kan vara antingen statiskt (med hjälp av /.default) eller dynamiska omfång. Detta kan omfatta OIDC-omfången (openid, profile, email).

I det här läget kräver Microsoft Entra-ID att en klientadministratör loggar in för att slutföra begäran. Administratören uppmanas att godkänna alla behörigheter som du har begärt i parametern scope . Om du har använt ett statiskt (/.default) värde fungerar det som slutpunkten för administratörsmedgivande för v1.0 och begär medgivande för alla omfång som finns i de behörigheter som krävs (både användare och app). För att kunna begära appbehörigheter måste du använda värdet /.default . Om du inte vill att administratörer ska se en viss behörighet på skärmen för administratörsmedgivande hela tiden när du använder /.defaultär det bästa sättet att inte lägga behörigheten i avsnittet med nödvändiga behörigheter. I stället kan du använda dynamiskt medgivande för att lägga till de behörigheter som du vill ska finnas på medgivandeskärmen vid körning i stället för att använda /.default.

Lyckat svar

Om administratören godkänner behörigheterna för din app ser det lyckade svaret ut så här:

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 Katalogklientorganisationen som gav ditt program de behörigheter som begärdes, i GUID-format.
state Ett värde som ingår i begäran som också returneras i tokensvaret. Det kan vara en sträng med valfritt innehåll. Tillståndet används för att koda information om användarens tillstånd i appen innan autentiseringsbegäran inträffade, till exempel sidan eller vyn de var på.
scope Den uppsättning behörigheter som beviljats åtkomst till för programmet.
admin_consent Kommer att anges till True.

Varning

Använd aldrig klient-ID-värdet för parametern för att autentisera tenant eller auktorisera användare. Klientorganisations-ID-värdet kan uppdateras och skickas av dåliga aktörer för att personifiera ett svar på din app. Detta kan göra att ditt program exponeras för säkerhetsincidenter.

Felsvar

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

Om du lägger till parametrarna som visas i ett lyckat svar visas felparametrar som nedan.

Parameter Description
error En felkodssträng som kan användas för att klassificera typer av fel som inträffar och som kan användas för att reagera på fel.
error_description Ett specifikt felmeddelande som kan hjälpa en utvecklare att identifiera rotorsaken till ett fel.
state Ett värde som ingår i begäran som också returneras i tokensvaret. Det kan vara en sträng med valfritt innehåll. Tillståndet används för att koda information om användarens tillstånd i appen innan autentiseringsbegäran inträffade, till exempel sidan eller vyn de var på.
admin_consent Anges till för True att indikera att det här svaret inträffade i ett flöde för administratörsmedgivande.

Nästa steg