Konfigurera ett program för att exponera ett webb-API

I den här guiden registrerar du ett webb-API med Microsofts identitetsplattform och exponerar den för klientappar genom att lägga till ett omfång. Genom att registrera ditt webb-API och exponera det via omfång, tilldela en ägar- och approll kan du ge behörighetsbaserad åtkomst till dess resurser till behöriga användare och klientappar som har åtkomst till ditt API.

Förutsättningar

• Ett Azure-konto med en aktiv prenumeration. Om du inte har något skapar du ett konto kostnadsfritt.
• Ett program som är registrerat i administrationscentret för Microsoft Entra. Om du inte har något kan du registrera ett program nu.

Registrera webb-API:et

Åtkomst till API:er kräver konfiguration av åtkomstomfattningar och roller. Om du vill exponera dina webb-API:er för resursprogram för klientprogram konfigurerar du åtkomstomfattningar och roller för API:et. Om du vill att ett klientprogram ska få åtkomst till ett webb-API konfigurerar du behörigheter för åtkomst till API:et i appregistreringen. För att ge begränsad åtkomst till resurserna i webb-API:et måste du först registrera API:et med Microsofts identitetsplattform.

1. Logga in på administrationscentret för Microsoft Entra som minst molnprogramadministratör.
2. Om du har åtkomst till flera klienter, använd ikonen Inställningar på den översta menyn för att växla till den klient som innehåller appregistreringen från menyn Kataloger + prenumerationer.
3. Utför stegen i registrera ett program och hoppa över avsnittet Omdirigerings-URI (valfritt). Du behöver inte konfigurera en omdirigerings-URI för ett webb-API eftersom ingen användare är inloggad interaktivt.

Tilldela programägare

1. I din appregistrering går du till Hantera, väljer Ägare och Lägg till ägare.
2. I det nya fönstret letar du upp och väljer de ägare som du vill tilldela till programmet. Markerade ägare visas i den högra panelen. När du är klar bekräftar du med Välj. Appens ägare visas nu i ägarlistan.

Tilldela app-roll

1. Under Hantera i appregistreringen väljer du Approller och Skapa approll.

2. Ange sedan approllens attribut i fönstret Skapa approll . För den här genomgången kan du använda exempelvärdena eller ange egna.

   Fält	Beskrivning	Exempel
   Visningsnamn	Namnet på din applikationsroll	Anställningsregister
   Tillåtna medlemstyper	Anger om approllen kan tilldelas till användare/grupper och/eller program	Appar
   Värde	Värdet som visas i "roller"-anspråket för en token	Employee.Records
   Beskrivning	En mer detaljerad beskrivning av appens roll	Applikationer har åtkomst till anställdas register

3. Markera kryssrutan för att aktivera approllen och välj Använd sedan.

Lägg till omfång

Med webb-API:et registrerat och en app-roll och ägare tilldelad kan du lägga till omfång i API:ets kod så att den ger detaljerad behörighet till konsumenter.

Koden i ett klientprogram begär behörighet att utföra åtgärder som definierats av webb-API:et genom att skicka en åtkomsttoken tillsammans med dess begäranden till den skyddade resursen (webb-API:et). Webb-API:et utför sedan endast den begärda åtgärden om den åtkomsttoken som den tar emot innehåller de omfång som krävs för åtgärden.

Lägga till ett omfång som kräver administratörs- och användarmedgivande

Följ först dessa steg för att skapa ett exempelomfång med namnet Employees.Read.All:

1. Välj exponerar ett API.

2. Längst upp på sidan väljer du Lägg tillbredvid Program-ID-URI. Detta är api://<application-client-id>som standard . App-ID-URI:n fungerar som prefix för de omfång som du refererar till i API:ets kod och måste vara globalt unik. Välj Spara.

3. Välj Lägg till ett omfång:

   

4. Ange sedan omfångets attribut i fönstret Lägg till ett omfång . För den här genomgången kan du använda exempelvärdena eller ange egna.

   Fält	Beskrivning	Exempel
   Omfångsnamn	Namnet på din omfattning. En vanlig namngivningskonvention för omfång är resource.operation.constraint.	Employees.Read.All
   Vem kan ge medgivande	Om det här omfånget kan godkännas av användare eller om administratörsmedgivande krävs. Endast administratörer bör användas för behörigheter med högre privilegier.	Administratörer och användare
   Visningsnamn för administratörsmedgivande	En kort beskrivning av omfångets syfte som endast administratörer ser.	Skrivskyddad åtkomst till anställdas poster
   Beskrivning av administratörsmedgivande	En mer detaljerad beskrivning av den behörighet som beviljas inom det användningsområde som endast administratörer kan se.	Tillåt att programmet har skrivskyddad åtkomst till alla anställdas data.
   Visningsnamn för användarmedgivande	En kort beskrivning av omfångets syfte. Visas endast för användare om du anger Vem kan samtycka till administratörer och användare.	Skrivskyddad åtkomst till dina anställdas poster
   Beskrivning av användarmedgivande	En mer detaljerad beskrivning av behörigheten som omfånget beviljar. Visas endast för användare om du anger Vem kan samtycka till administratörer och användare.	Tillåt att programmet har skrivskyddad åtkomst till dina anställdas data.
   Staten	Om omfånget är aktiverat eller inaktiverat.	Aktiverad

5. Välj Lägg till definitionsområde.

6. (Valfritt) Om du vill förhindra att användare av din app uppmanas att ge sitt medgivande till de omfång som du har definierat kan du i förväg ge klientprogrammet åtkomst till webb-API:et. Förauktorisera endast de klientprogram som du litar på eftersom användarna inte har möjlighet att neka medgivande.

   1. Under Auktoriserade klientprogram väljer du Lägg till ett klientprogram.
   2. Ange Applikation (klient) ID för den klientapplikation som du vill förauktorisera. Till exempel en webbapplikation som du tidigare har registrerat.
   3. Under Auktoriserade omfång väljer du de omfång som du vill utelämna medgivandefråga och väljer sedan Lägg till program.

   Om du har följt det här valfria steget är klientappen nu en förauktoriserat klientprogram (PCA) och användarna uppmanas inte att ge sitt medgivande när de loggar in på den.

Lägga till ett omfång som kräver administratörsmedgivande

Lägg sedan till ett annat exempelomfång med namnet Employees.Write.All som endast administratörer kan samtycka till. Omfång som kräver administratörsmedgivande används vanligtvis för att ge åtkomst till åtgärder med högre privilegier, och ofta av klientprogram som körs som serverdelstjänster eller daemoner som inte loggar in en användare interaktivt.

Om du vill lägga till exempelomfånget Employees.Write.All följer du stegen i avsnittet Lägg till ett omfång och anger dessa värden i fönstret Lägg till ett omfång . Välj Lägg till omfång när du är klar:

Granska de exponerade omfången

Om du har lagt till båda exempelomfattningarna som beskrivs i föregående avsnitt visas de i fönstret Exponera ett API i webb-API:ets appregistrering, på ett sätt som liknar följande bild:

Omfångets fullständiga sträng är sammanlänkningen av din webb-API:s Application ID URI och omfångets omfångsnamn. Om webb-API:ets program-ID-URI till exempel är https://contoso.com/api och omfångsnamnet är Employees.Read.Allär det fullständiga omfånget:

https://contoso.com/api/Employees.Read.All

Använda de exponerade omfången

I nästa artikel i den här serien konfigurerar du en klientapps registrering med åtkomst till webb-API:et och de omfång som du definierade genom att följa stegen i den här artikeln.

När en klientappsregistrering har beviljats behörighet att komma åt ditt webb-API kan klienten utfärdas en OAuth 2.0-åtkomsttoken av identitetsplattformen. När klienten anropar webb-API:et visas en åtkomsttoken vars omfångsanspråk (scp) är inställt på de behörigheter som du har angett i klientens appregistrering.

Du kan göra ytterligare omfång tillgängliga senare, vid behov. Tänk på att ditt webb-API kan exponera flera omfång som är associerade med flera åtgärder. Resursen kan styra åtkomsten till webb-API:et vid körning genom att utvärdera omfångsanspråken (scp) i OAuth 2.0-åtkomsttoken som den tar emot.

Gå vidare

Nu när du har exponerat webb-API:et genom att konfigurera dess omfång konfigurerar du klientappens registrering med behörighet att komma åt omfången.