Exponera omfång i ett skyddat webb-API

Gäller för: Personalklienter (läs mer)

Den här artikeln beskriver hur du lägger till omfång i ett program för ett skyddat webb-API.

Förutsättningar

• Registrera en ny app i administrationscentret för Microsoft Entra, som endast konfigurerats för konton i den här organisationskatalogen. Mer information finns i Registrera ett program . Registrera följande värden från programöversiktssidan för senare användning:
  • App-ID (klient-ID)
  • Katalog-ID (hyresgäst)

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 hyresgästadministratör måste ge samtycke till klientprogram för ditt webb-API 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

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 klientadministratören 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 Entra ID>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\>_.

Nästa steg

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