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

  • Artikel
  • 4 minuter för att läsa

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

Förutsättningar

Registrera webb-API:et

För att ge begränsad åtkomst till resurserna i ditt webb-API måste du först registrera API:et med Microsofts identitetsplattform.

  1. Utför stegen i avsnittet Registrera ett program i Snabbstart: Registrera en app med Microsofts identitetsplattform.
  2. Hoppa över avsnitten Lägg till en omdirigerings-URI och Konfigurera plattformsinställningar . Du behöver inte konfigurera en omdirigerings-URI för ett webb-API eftersom ingen användare är inloggad interaktivt.
  3. Hoppa över avsnittet Lägg till autentiseringsuppgifter för tillfället. Endast om ditt API har åtkomst till ett underordnat API behöver det egna autentiseringsuppgifter, ett scenario som inte beskrivs i den här artikeln.

När ditt webb-API är registrerat är du redo att lägga till de omfång som API:ets kod kan använda för att ge detaljerad behörighet till konsumenter av ditt API.

Lägga till ett omfång

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.

Följ först de här stegen för att skapa ett exempelomfång med namnet Employees.Read.All:

  1. Logga in på Azure-portalen.

  2. Om du har åtkomst till flera klienter använder du filtret Kataloger + prenumerationer på den översta menyn för att välja den klientorganisation som innehåller klientappens registrering.

  3. Välj Azure ActiveDirectory-appregistreringar> och välj sedan api:ets appregistrering.

  4. Välj Exponera ett API

  5. Välj Ange bredvid Program-ID-URI om du ännu inte har konfigurerat en.

    Du kan använda standardvärdet api://<application-client-id> för eller något annat URI-mönster för app-ID som stöds. 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 unikt.

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

    An app registration's Expose an API pane in the Azure portal

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

    Fält Beskrivning Exempel
    Namn på sökomfång Namnet på omfånget. 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. Välj Endast administratörer för behörigheter på högre nivå. Administratörer och användare
    Visningsnamn för administratörsmedgivande En kort beskrivning av omfångets syfte som endast administratörer ser. Read-only access to Employee records
    Beskrivning av administratörsmedgivande En mer detaljerad beskrivning av behörigheten som beviljas av det omfång som endast administratörer ser. Allow the application to have read-only access to all Employee data.
    Visningsnamn för användarmedgivande En kort beskrivning av omfattningens syfte. Visas endast för användare om du anger Vem kan samtycka till administratörer och användare. Read-only access to your Employee records
    Beskrivning av användarmedgivande En mer detaljerad beskrivning av behörigheten som beviljas av omfånget. Visas endast för användare om du anger Vem kan samtycka till administratörer och användare. Allow the application to have read-only access to your Employee data.

  8. Ange Tillstånd till Aktiverad och välj sedan Lägg till omfång.

  9. (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 auktorisera klientprogrammet för åtkomst till ditt webb-API. 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 program-ID :t (klient) för det klientprogram som du vill förauktorisera. Till exempel för en webbapp som du har registrerat tidigare.
    3. Under Auktoriserade omfång väljer du de omfång för vilka du vill förhindra medgivande och väljer sedan Lägg till program.

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

Lägg sedan till ett annat exempelomfång med namnet Employees.Write.All som endast administratörer kan godkänna. 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 :

Fält Exempelvärde
Namn på sökomfång Employees.Write.All
Vem kan ge medgivande Endast administratörer
Visningsnamn för administratörsmedgivande Write access to Employee records
Beskrivning av administratörsmedgivande Allow the application to have write access to all Employee data.
Visningsnamn för användarmedgivande Ingen (lämna tomt)
Beskrivning av användarmedgivande Ingen (lämna tomt)

Verifiera 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, liknande den här bilden:

Screenshot of the Expose an API pane showing two exposed scopes.

Som du ser i bilden är en omfattnings fullständiga sträng sammanlänkningen av webb-API:ets program-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 serien konfigurerar du en klientapps registrering med åtkomst till ditt webb-API 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 Microsofts identitetsplattform. 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. Din resurs 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.

Nästa steg

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.

Konfigurera en appregistrering för webb-API-åtkomst