Dela via

Skyddat webb-API: Appregistrering

  • Artikel

Den här artikeln beskriver hur du registrerar ett program för ett skyddat webb-API.

Vanliga steg för att registrera en app finns i Snabbstart: Registrera ett program med Microsofts identitetsplattform.

Godkänd tokenversion

Microsofts identitetsplattform kan utfärda v1.0-token och v2.0-token. Mer information om dessa token finns i Åtkomsttoken.

Vilken tokenversion ditt API kan acceptera beror på valet av kontotyper som stöds när du skapar din webb-API-programregistrering i Azure Portal.

  • Om värdet för Kontotyper som stöds är Konton i en organisationskatalog och personliga Microsoft-konton (till exempel Skype, Xbox, Outlook.com), måste den godkända tokenversionen vara v2.0.
  • Annars kan den godkända tokenversionen vara v1.0.

När du har skapat programmet kan du bestämma eller ändra den godkända tokenversionen genom att följa dessa steg:

  1. I administrationscentret för Microsoft Entra väljer du din app och väljer sedan Manifest.
  2. Hitta egenskapen accessTokenAcceptedVersion i manifestet.
  3. Värdet anger för Microsoft Entra vilken tokenversion webb-API:et accepterar.
    • Om värdet är 2 accepterar webb-API:et v2.0-token.
    • Om värdet är null accepterar webb-API:et v1.0-token.
  4. Om du har ändrat tokenversionen väljer du Spara.

Webb-API:et anger vilken tokenversion den accepterar. När en klient begär en token för webb-API:et från Microsofts identitetsplattform hämtar klienten en token som anger vilken tokenversion webb-API:et accepterar.

Ingen omdirigerings-URI

Webb-API:er behöver inte registrera en omdirigerings-URI eftersom ingen användare är interaktivt inloggad.

Exponerat API

Andra inställningar som är specifika för webb-API:er är det exponerade API:et och de exponerade omfången eller approllerna.

Omfång och program-ID-URI

Omfång har vanligtvis formuläret resourceURI/scopeName. För Microsoft Graph har omfången genvägar. Är till exempel User.Read en genväg för https://graph.microsoft.com/user.read.

Under appregistreringen definierar du följande parametrar:

  • Resurs-URI:n
  • Ett eller flera omfång
  • En eller flera approller

Som standard rekommenderar programregistreringsportalen att du använder resurs-URI api://{clientId}:n . Den här URI:n är unik men inte läsbar för människor. Om du ändrar URI:n kontrollerar du att det nya värdet är unikt. Programregistreringsportalen ser till att du använder en konfigurerad utgivardomän.

För klientprogram visas omfång som delegerade behörigheter och approller visas som programbehörigheter för webb-API:et.

Omfång visas också i medgivandefönstret som visas för användare av din app. Ange därför motsvarande strängar som beskriver omfånget:

  • Som en användare ser.
  • Som visas av en klientorganisationsadministratör, som kan bevilja administratörsmedgivande.

Approller kan inte godkännas av en användare (eftersom de används av ett program som anropar webb-API:et för sig självt). En klientadministratör måste godkänna klientprogram för webb-API:et som exponerar approller. Mer information finns i Administratörsmedgivande .

Exponera delegerade behörigheter (omfång)

Om du vill exponera delegerade behörigheter eller omfång följer du stegen i Konfigurera ett program för att exponera ett webb-API.

Om du följer med i webb-API-scenariot som beskrivs i den här uppsättningen artiklar använder du följande inställningar:

  • Program-ID-URI: Godkänn den föreslagna program-ID-URI:n (api://< clientId>) (om du uppmanas att göra det)
  • Omfångsnamn: access_as_user
  • Vem kan samtycka: Administratörer och användare
  • Visningsnamn för administratörsmedgivande: Åtkomst till TodoListService som användare
  • Beskrivning av administratörsmedgivande: Åtkomst till TodoListService-webb-API:et som användare
  • Visningsnamn för användarmedgivande: Åtkomst till TodoListService som användare
  • Beskrivning av användarmedgivande: Åtkomst till TodoListService-webb-API:et som användare
  • Tillstånd: Aktiverad

Dricks

För program-ID-URI:n har du möjlighet att ange den till den fysiska utfärdaren för API:et, till exempel https://graph.microsoft.com. Detta kan vara användbart om URL:en för API:et som måste anropas är känd.

Om ditt webb-API anropas av en tjänst eller daemonapp

Exponera programbehörigheter i stället för delegerade behörigheter om ditt API ska nås av daemoner, tjänster eller andra icke-interaktiva program (av en människa). Eftersom program av daemon- och tjänsttyp körs obevakade och autentiserar med sin egen identitet finns det ingen användare som kan "delegera" sin behörighet.

Exponera programbehörigheter (approller)

Om du vill exponera programbehörigheter följer du stegen i Lägg till approller i din app.

I fönstret Skapa approll under Tillåtna medlemstyper väljer du Program. Du kan också lägga till rollen med hjälp av programmanifestredigeraren enligt beskrivningen i artikeln.

Begränsa åtkomsttoken till specifika klientappar

Approller är den mekanism som programutvecklare använder för att exponera appens behörigheter. Webb-API:ets kod bör söka efter approller i de åtkomsttoken som den tar emot från anropare.

Om du vill lägga till ytterligare ett säkerhetslager kan en Microsoft Entra-klientadministratör konfigurera sin klientorganisation så att Microsofts identitetsplattform endast utfärdar säkerhetstoken till de klientappar som de har godkänt för API-åtkomst.

Öka säkerheten genom att begränsa tokenutfärdande endast till klientappar som har tilldelats approller:

  1. I administrationscentret för Microsoft Entra väljer du din app under Identitetsprogram>> Appregistreringar.
  2. På programmets översiktssida går du till Essentials och letar reda på och väljer länken Hanterat program i den lokala katalogen för att navigera till sidan Översikt över företagsprogram.
  3. Välj Egenskaper under Hantera.
  4. Ange Tilldelning krävs? till Ja.
  5. Välj Spara.

Microsoft Entra-ID söker nu efter approlltilldelningar av klientprogram som begär åtkomsttoken för ditt webb-API. Om en klientapp inte har tilldelats några approller returnerar Microsoft Entra-ID ett felmeddelande till klienten som liknar _invalid_client: AADSTS501051: Application \<application name\> isn't assigned to a role for the \<web API\>_.

Varning

Använd INTE AADSTS-felkoder eller deras meddelandesträngar som literaler i programmets kod. Felkoderna "AADSTS" och felmeddelandesträngarna som returneras av Microsoft Entra-ID:t är inte oföränderliga och kan ändras av Microsoft när som helst och utan din vetskap. Om du fattar förgreningsbeslut i koden baserat på värdena för AADSTS-koderna eller deras meddelandesträngar riskerar du programmets funktioner och stabilitet.

Gå vidare

Nästa artikel i den här serien är Konfiguration av appkod.