Dela via

Auktorisera testkonsolen för utvecklarportalen genom att konfigurera OAuth 2.0-användarauktorisering

  • Artikel

GÄLLER FÖR: Utvecklare | Grundläggande | Basic v2 | Standard | Standard v2 | Premium | Premium v2

Många API:er stöder OAuth 2.0 för att skydda API:et och se till att endast giltiga användare har åtkomst, och de kan bara komma åt resurser som de har rätt till. Om du vill använda Azure API Managements interaktiva utvecklarkonsol med sådana API:er kan du konfigurera en extern provider för OAuth 2.0-användarauktorisering.

Genom att konfigurera OAuth 2.0-användarauktorisering i testkonsolen i utvecklarportalen får utvecklare ett bekvämt sätt att skaffa en OAuth 2.0-åtkomsttoken. Från testkonsolen skickas token sedan till serverdelen med API-anropet. Tokenverifiering måste konfigureras separat – antingen med hjälp av en JWT-valideringsprincip eller i serverdelstjänsten.

Förutsättningar

  • En API Management-instans.
  • En OAuth 2.0-provider.

Den här artikeln visar hur du konfigurerar din API Management-tjänstinstans för att använda OAuth 2.0-auktorisering i utvecklarportalens testkonsol, men den visar inte hur du konfigurerar en OAuth 2.0-provider.

Om du ännu inte har skapat en API Management-tjänstinstans läser du Skapa en API Management-tjänstinstans.

Scenarioöversikt

Om du konfigurerar OAuth 2.0-användarauktorisering i API Management kan utvecklarportalens testkonsol (och testkonsolen i Azure Portal) som klient hämta en token från auktoriseringsservern. Konfigurationen för varje OAuth 2.0-provider skiljer sig åt, även om stegen är liknande och de nödvändiga uppgifter som används för att konfigurera OAuth 2.0 i din API Management tjänstinstans är desamma. Den här artikeln visar ett exempel med Microsoft Entra-ID som OAuth 2.0-provider.

Följande är konfigurationsstegen på hög nivå:

  1. Registrera ett program (serverdelsapp) i Microsoft Entra ID för att representera API:et.

  2. Registrera ett annat program (klientapp) i Microsoft Entra-ID för att representera ett klientprogram som måste anropa API:et – i det här fallet testkonsolen för utvecklarportalen.

    I Microsoft Entra ID beviljar du behörigheter så att klientappen kan anropa serverdelsappen.

  3. Konfigurera testkonsolen i utvecklarportalen för att anropa ett API med OAuth 2.0-användarauktorisering.

  4. Konfigurera ett API för att använda OAuth 2.0-användarauktorisering.

  5. Lägg till en princip för att förauktorisera OAuth 2.0-token för varje inkommande begäran. Du kan använda principen validate-jwt för valfri OAuth 2.0-provider.

Den här konfigurationen stöder följande OAuth-flöde:

Översiktsgrafik för att visuellt konceptualisera följande flöde.

  1. Utvecklarportalen begär en token från Microsoft Entra-ID med autentiseringsuppgifterna för klientappen.

  2. Efter valideringen utfärdar Microsoft Entra-ID åtkomst-/uppdateringstoken.

  3. En utvecklare (användare av utvecklarportalen) gör ett API-anrop med auktoriseringshuvudet.

  4. Token verifieras med OAuth 2.0-providern med hjälp validate-jwt av principen. För Microsoft Entra ID-providern tillhandahåller validate-azure-ad-token API Management även principen.

  5. Baserat på valideringsresultatet får utvecklaren svaret i utvecklarportalen.

Typer av auktoriseringsbidrag

Azure API Management stöder följande OAuth 2.0-beviljandetyper (flöden). En beviljandetyp refererar till ett sätt för ett klientprogram (i det här sammanhanget testkonsolen i utvecklarportalen) att hämta en åtkomsttoken till ditt serverdels-API. Du kan konfigurera en eller flera beviljandetyper, beroende på din OAuth 2.0-provider och scenarier.

Följande är en sammanfattning på hög nivå. Mer information om beviljandetyper finns i OAuth 2.0 Authorization Framework - och OAuth-beviljandetyperna.

Bevilja typ beskrivning Scenarier
Auktoriseringskod Utbyter auktoriseringskod för token Appar på serversidan, till exempel webbappar
Auktoriseringskod + PKCE Förbättring av auktoriseringskodflöde som skapar en kodutmaning som skickas med auktoriseringsbegäran Mobila och offentliga klienter som inte kan skydda en hemlighet eller token
Implicit (inaktuell) Returnerar åtkomsttoken omedelbart utan ett extra auktoriseringskodutbytessteg Klienter som inte kan skydda en hemlighet eller token, till exempel mobilappar och ensidesappar

Rekommenderas vanligtvis inte på grund av inneboende risker med att returnera åtkomsttoken i HTTP-omdirigering utan bekräftelse på att den tas emot av klienten
Lösenord för resursägare Begär användarautentiseringsuppgifter (användarnamn och lösenord), vanligtvis med hjälp av ett interaktivt formulär För användning med mycket betrodda program

Bör endast användas när andra, säkrare flöden inte kan användas
Klientautentiseringsuppgifter Autentiserar och auktoriserar en app i stället för en användare Dator-till-dator-program som inte kräver en specifik användares behörighet att komma åt data, till exempel CLIs, daemons eller tjänster som körs på serverdelen

Säkerhetsfrågor

Tänk på hur beviljandetypen genererar en token, tokens omfång och hur token kan exponeras. En komprometterad token kan användas av en obehörig aktör för att få åtkomst till ytterligare resurser inom tokenomfånget.

När du konfigurerar OAuth 2.0-användarauktorisering i testkonsolen i utvecklarportalen:

  • Begränsa tokens omfång till det minimum som krävs för att utvecklare ska kunna testa API:erna. Begränsa omfånget till testkonsolen eller till de berörda API:erna. Stegen för att konfigurera tokenomfång beror på din OAuth 2.0-provider. Ett exempel visas senare i den här artikeln med hjälp av Microsoft Entra-ID.

    Beroende på dina scenarier kan du konfigurera mer eller mindre restriktiva tokenomfattningar för andra klientprogram som du skapar för åtkomst till serverdels-API:er.

  • Var extra försiktig om du aktiverar flödet klientautentiseringsuppgifter. Testkonsolen i utvecklarportalen ber inte om autentiseringsuppgifter när du arbetar med flödet Klientautentiseringsuppgifter. En åtkomsttoken kan oavsiktligt exponeras för utvecklare eller anonyma användare av utvecklarkonsolen.

Hålla reda på viktig information

I den här självstudien uppmanas du att registrera viktig information som du kan referera till senare:

  • ID för serverdelsprogram (klient): GUID för programmet som representerar serverdels-API:et
  • Omfång för serverdelsprogram: Ett eller flera omfång som du kan skapa för att komma åt API:et. Omfångsformatet är api://<Backend Application (client) ID>/<Scope Name> (till exempel api://1764e900-1827-4a0b-9182-b2c1841864c2/Read)
  • Klientprograms-ID (klient) : GUID för programmet som representerar utvecklarportalen
  • Hemligt värde för klientprogram: DET GUID som fungerar som hemlighet för interaktion med klientprogrammet i Microsoft Entra-ID

Registrera program med OAuth-servern

Du måste registrera två program med din OAuth 2.0-provider: en representerar serverdels-API:et som ska skyddas och en andra representerar klientprogrammet som anropar API:et – i det här fallet testkonsolen för utvecklarportalen.

Följande är exempelsteg med Microsoft Entra-ID som OAuth 2.0-provider. Mer information om appregistrering finns i Snabbstart: Konfigurera ett program för att exponera ett webb-API.

Registrera ett program i Microsoft Entra-ID för att representera API:et

  1. I Azure Portal söker du efter och väljer Appregistreringar.

  2. Välj Ny registrering.

  3. När sidan registrera ett program visas anger du programmets registreringsinformation:

    • I avsnittet Namn anger du ett beskrivande programnamn som ska visas för appens användare, till exempel backend-app.
    • I avsnittet Kontotyper som stöds väljer du ett alternativ som passar ditt scenario.

  4. Lämna avsnittet Omdirigerings-URI tomt. Senare lägger du till en omdirigerings-URI som genereras i OAuth 2.0-konfigurationen i API Management.

  5. Välj Registrera för att skapa programmet.

  6. På sidan Appöversikt letar du reda på värdet program-ID (klient) och registrerar det för senare.

  7. Under avsnittet Hantera på sidomenyn väljer du Exponera ett API och anger program-ID-URI :n med standardvärdet. Registrera det här värdet för senare.

  8. Välj knappen Lägg till ett omfång för att visa sidan Lägg till ett omfång:

    1. Ange ett omfångsnamn för ett omfång som stöds av API:et (till exempel Files.Read).
    2. I Vem kan samtycka?, gör du ett val för ditt scenario, till exempel Administratörer och användare. Välj Endast administratörer för scenarier med högre privilegier.
    3. Ange visningsnamn för administratörsmedgivande och beskrivning av administratörsmedgivande.
    4. Kontrollera att det aktiverade omfångstillståndet är markerat.

  9. Välj knappen Lägg till omfång för att skapa omfånget.

  10. Upprepa de föregående två stegen för att lägga till alla omfång som stöds av ditt API.

  11. När omfången har skapats antecknar du dem för användning i ett efterföljande steg.

Registrera ett annat program i Microsoft Entra-ID för att representera ett klientprogram

Registrera varje klientprogram som anropar API:et som ett program i Microsoft Entra-ID.

  1. I Azure Portal söker du efter och väljer Appregistreringar.

  2. Välj Ny registrering.

  3. När sidan registrera ett program visas anger du programmets registreringsinformation:

    • I avsnittet Namn anger du ett beskrivande programnamn som ska visas för appens användare, till exempel klientappen.
    • I avsnittet Kontotyper som stöds väljer du ett alternativ som passar ditt scenario.

  4. I avsnittet Omdirigerings-URI väljer du Webb och lämnar URL-fältet tomt för tillfället.

  5. Välj Registrera för att skapa programmet.

  6. På sidan Appöversikt letar du reda på värdet program-ID (klient) och registrerar det för senare.

  7. Skapa en klienthemlighet som programmet ska använda i ett efterföljande steg.

    1. Under avsnittet Hantera på sidomenyn väljer du Certifikat och hemligheter.
    2. Under Klienthemligheter väljer du + Ny klienthemlighet.
    3. Under Lägg till en klienthemlighet anger du en Beskrivning och väljer när nyckeln ska upphöra att gälla.
    4. Markera Lägga till.

När hemligheten skapas bör du notera nyckelvärdet för användning i ett efterföljande steg. Du kan inte komma åt hemligheten igen i portalen.

Bevilja behörigheter i Microsoft Entra-ID

Nu när du har registrerat två program för att representera API:et och testkonsolen beviljar du behörigheter så att klientappen kan anropa serverdelsappen.

  1. I Azure Portal söker du efter och väljer Appregistreringar.

  2. Välj din klientapp. Välj SEDAN API-behörigheter på sidomenyn.

  3. Välj + Lägg till behörighet.

  4. Under Välj ett API väljer du Mina API:er och letar sedan upp och väljer din serverdelsapp (appregistreringen för ditt serverdels-API).

  5. Välj Delegerade behörigheter och välj sedan lämpliga behörigheter till din serverdelsapp.

  6. Välj Lägg till behörigheter.

Valfritt:

  1. Gå till klientappens API-behörighetssida.

  2. Välj Bevilja administratörsmedgivande för ditt klientnamn> för <att bevilja medgivande åt alla användare i den här katalogen.

Konfigurera en OAuth 2.0-auktoriseringsserver i API Management

  1. I Azure Portal navigerar du till din API Management-instans.

  2. Under Utvecklarportalen på sidomenyn väljer du OAuth 2.0 + OpenID Connect.

  3. Under fliken OAuth 2.0 väljer du + Lägg till.

    OAuth 2.0-menyn

  4. Ange ett namn och en valfri beskrivning i fälten Namn och Beskrivning .

    Kommentar

    Dessa fält identifierar OAuth 2.0-auktoriseringsservern i den aktuella API Management-tjänsten. Deras värden kommer inte från OAuth 2.0-servern.

  5. Ange URL: en för klientregistreringssidan , till exempel https://contoso.com/login. På den här sidan kan användarna skapa och hantera sina konton, om din OAuth 2.0-provider stöder användarhantering av konton. Sidan varierar beroende på vilken OAuth 2.0-provider som används.

    Om din OAuth 2.0-provider inte har konfigurerat användarhantering av konton anger du en platshållar-URL här, till exempel url:en för ditt företag eller en URL som http://localhost.

    OAuth 2.0 ny server

  6. Nästa avsnitt i formuläret innehåller inställningarna auktoriseringsbidragstyper, Auktoriseringsslutpunkts-URL och Metodinställningar för auktoriseringsbegäran.

    • Välj en eller flera önskade typer av auktoriseringsbidrag. I det här exemplet väljer du auktoriseringskod (standard). Läs mer

    • Ange URL:en för auktoriseringsslutpunkten. Du kan hämta slutpunkts-URL:en från sidan Slutpunkter i en av appregistreringarna. För en app med en enda klientorganisation i Microsoft Entra-ID liknar den här URL:en en av följande URL:er, där {aad-tenant} ersätts med ID:t för din Microsoft Entra-klientorganisation.

      Vi rekommenderar att du använder v2-slutpunkten. API Management stöder dock både v1- och v2-slutpunkter.

      https://login.microsoftonline.com/{aad-tenant}/oauth2/v2.0/authorize (v2)

      https://login.microsoftonline.com/{aad-tenant}/oauth2/authorize (v1)

    • Metoden auktoriseringsbegäran anger hur auktoriseringsbegäran skickas till OAuth 2.0-servern. Välj POST.

    Ange auktoriseringsinställningar

  7. Ange tokenslutpunkts-URL, klientautentiseringsmetoder, metoden för att skicka åtkomsttoken och standardomfånget.

    • Ange URL:en för tokenslutpunkten. För en enskild klientapp i Microsoft Entra-ID liknar den en av följande URL:er, där {aad-tenant} ersätts med ID:t för din Microsoft Entra-klientorganisation. Använd samma slutpunktsversion (v2 eller v1) som du valde tidigare.

      https://login.microsoftonline.com/{aad-tenant}/oauth2/v2.0/token (v2)

      https://login.microsoftonline.com/{aad-tenant}/oauth2/token (v1)

    • Om du använder v1-slutpunkter lägger du till en brödtextparameter:
      * Namn: resurs.
      * Värde: serverdelsappens program-ID (klient)-ID.

    • Om du använder v2-slutpunkter :
      * Ange det serverdelsappsomfång som du skapade i fältet Standardomfång .
      * Ange värdet för accessTokenAcceptedVersion egenskapen till 2 i programmanifestet för både backend-app- och klientappregistreringarna.

    • Acceptera standardinställningarna för klientautentiseringsmetoder och metoden för att skicka åtkomsttoken.

  8. I Klientautentiseringsuppgifter anger du klient-ID och klienthemlighet, som du fick när klientappen skapades och konfigurerades.

  9. När klient-ID och klienthemlighet har angetts genereras omdirigerings-URI:n för auktoriseringskoden. Den här URI:n används för att konfigurera omdirigerings-URI:n i din OAuth 2.0-serverkonfiguration.

    I utvecklarportalen är URI-suffixet av formatet:

    • /signin-oauth/code/callback/{authServerName} för beviljandeflöde för auktoriseringskod
    • /signin-oauth/implicit/callback för implicit beviljandeflöde

    Lägga till klientautentiseringsuppgifter för OAuth 2.0-tjänsten

    Kopiera lämplig omdirigerings-URI till autentiseringssidan för din klientappsregistrering. I appregistreringen väljer du Autentisering>+ Lägg till en plattformswebb> och anger sedan omdirigerings-URI:n.

  10. Om Auktoriseringsbidragstyper har angetts till Resursägares lösenord används avsnittet Autentiseringsuppgifter för resursägares lösenord för att ange dessa autentiseringsuppgifter. Annars kan du lämna det tomt.

  11. Välj Skapa för att spara konfigurationen av API Management OAuth 2.0-auktoriseringsservern.

  12. Publicera om utvecklarportalen.

    Viktigt!

    När du gör OAuth 2.0-relaterade ändringar bör du publicera om utvecklarportalen efter varje ändring som relevanta ändringar (till exempel omfångsändring) annars inte kan spridas till portalen och därefter användas för att testa API:erna.

Konfigurera ett API för att använda OAuth 2.0-användarauktorisering

När du har sparat OAuth 2.0-serverkonfigurationen konfigurerar du ett API eller API:er för att använda den här konfigurationen.

Viktigt!

  • Om du konfigurerar OAuth 2.0-inställningar för användarauktorisering för ett API kan API Management hämta en token från auktoriseringsservern när du använder testkonsolen i Azure Portal- eller utvecklarportalen. Inställningarna för auktoriseringsservern läggs också till i API-definitionen och dokumentationen.
  • För OAuth 2.0-auktorisering vid körning måste klientappen hämta och presentera token och du måste konfigurera tokenverifiering i API Management eller serverdels-API:et. Ett exempel finns i Skydda ett API i Azure API Management med OAuth 2.0-auktorisering med Microsoft Entra-ID.

  1. Välj API:er på MENYN API Management till vänster.

  2. Välj namnet på önskat API och välj fliken Inställningar. Bläddra till avsnittet Säkerhet och välj sedan OAuth 2.0.

  3. Välj önskad auktoriseringsserver i listrutan och välj Spara.

    Konfigurera OAuth 2.0-auktoriseringsserver

Utvecklarportal – testa användarauktorisering för OAuth 2.0

När du har konfigurerat OAuth 2.0-auktoriseringsservern och konfigurerat API:et för att använda den servern kan du testa den genom att gå till utvecklarportalen och anropa ett API.

  1. Välj Utvecklarportal på den översta menyn på sidan Översikt för Azure API Management-instansen.

  2. Bläddra till alla åtgärder under API:et i utvecklarportalen.

  3. Välj Prova för att ta dig till utvecklarkonsolen.

  4. Observera ett nytt objekt i avsnittet Auktorisering som motsvarar den auktoriseringsserver som du nyss lade till.

  5. Välj Auktoriseringskod i listrutan auktorisering.

    Välj auktorisering av auktoriseringskod

  6. När du har tillfrågats loggar du in på Microsoft Entra-klientorganisationen.

    • Om du redan är inloggad på kontot kanske du inte uppmanas att göra det.

  7. Efter lyckad inloggning läggs en Authorization rubrik till i begäran med en åtkomsttoken från Microsoft Entra-ID. Följande är en förkortad exempeltoken (Base64-kodad):

    Authorization: Bearer eyJ0eXAiOi[...]3pkCfvEOyA

  8. Konfigurera önskade värden för de återstående parametrarna och välj Skicka för att anropa API:et.

Konfigurera en JWT-valideringsprincip för att förauktorisera begäranden

I konfigurationen hittills verifierar API Management inte åtkomsttoken. Den skickar bara token i auktoriseringshuvudet till serverdels-API:et.

Om du vill förauktorisera begäranden konfigurerar du en validate-jwt-princip för att verifiera åtkomsttoken för varje inkommande begäran. Om en begäran inte har en giltig token blockerar API Management den. När du använder Microsoft Entra-ID-providern kan du också använda policyn validate-azure-ad-token .

Följande exempelprincip, när den läggs till i <inbound> principavsnittet, kontrollerar värdet för målgruppsanspråket i en åtkomsttoken som hämtats från Microsoft Entra-ID som visas i auktoriseringshuvudet. Det returnerar ett felmeddelande om token inte är giltig. Konfigurera den här principen i ett principomfång som är lämpligt för ditt scenario.

  • openid-config I URL:en aad-tenant är klientorganisations-ID i Microsoft Entra-ID. Hitta det här värdet i Azure Portal, till exempel på sidan Översikt för din Microsoft Entra-resurs. Exemplet som visas förutsätter en Microsoft Entra-app med en enda klientorganisation och en v2-konfigurationsslutpunkt.
  • Värdet för claim är klient-ID för den serverdelsapp som du registrerade i Microsoft Entra-ID.
<validate-jwt header-name="Authorization" failed-validation-httpcode="401" failed-validation-error-message="Unauthorized. Access token is missing or invalid.">
    <openid-config url="https://login.microsoftonline.com/{aad-tenant}/v2.0/.well-known/openid-configuration" />
    <audiences>
        <audience>{audience-value - (ex:api://guid)}</audience>
    </audiences>
    <issuers>
        <issuer>{issuer-value - (ex: https://sts.windows.net/{tenant id}/)}</issuer>
    </issuers>
    <required-claims>
        <claim name="aud">
            <value>{backend-app-client-id}</value>
        </claim>
    </required-claims>
</validate-jwt>

Kommentar

Den föregående openid-config URL:en motsvarar v2-slutpunkten. För v1-slutpunkten openid-config använder du https://login.microsoftonline.com/{aad-tenant}/.well-known/openid-configuration.

Information om hur du konfigurerar principer finns i Ange eller redigera principer. Mer anpassning av JWT-valideringar finns i referensen validate-jwt . Api Management tillhandahåller validate-azure-ad-token även principen för att verifiera en JWT som tillhandahölls av Microsoft Entra-tjänsten.

Relaterat innehåll