Registratie van beveiligde web-API-apps

Van toepassing op: Werknemerstenants Externe tenants (meer informatie)

In dit artikel wordt uitgelegd hoe u een toepassing registreert voor een beveiligde web-API.

Zie Quickstart: Een toepassing registreren bij het Microsoft Identity Platform voor de algemene stappen voor het registreren van een app.

Geaccepteerde tokenversie

Het Microsoft-identiteitsplatform kan v1.0-tokens en v2.0-tokens uitgeven. Raadpleeg Access-tokens voor meer informatie over deze tokens.

De tokenversie die uw API kan accepteren, is afhankelijk van de selectie ondersteunde accounttypen wanneer u de registratie van uw web-API-toepassing maakt in Azure Portal.

• Als de waarde van ondersteunde accounttypenAccounts in een organisatiedirectory en persoonlijke Microsoft-accounts (zoals Skype, Xbox, Outlook.com) is, moet de geaccepteerde tokenversie v2.0 zijn.
• Anders kan de geaccepteerde tokenversie v1.0 zijn.

Nadat u de toepassing hebt gemaakt, kunt u de geaccepteerde tokenversie bepalen of wijzigen door de volgende stappen uit te voeren:

1. Selecteer uw app in het Microsoft Entra-beheercentrum en selecteer vervolgens Manifest.
2. Zoek de eigenschap accessTokenAcceptedVersion in het manifest.
3. De waarde geeft aan Microsoft Entra op welke tokenversie de web-API accepteert.
   • Als de waarde 2 is, accepteert de web-API v2.0-tokens.
   • Als de waarde null is, accepteert de web-API v1.0-tokens.
4. Als u de tokenversie hebt gewijzigd, selecteert u Opslaan.

De web-API geeft aan welke tokenversie deze accepteert. Wanneer een client een token voor uw web-API aanvraagt vanuit het Microsoft-identiteitsplatform, krijgt de client een token dat aangeeft welke tokenversie de web-API accepteert.

Geen omleidings-URI

Web-API's hoeven geen omleidings-URI te registreren omdat er geen gebruiker interactief is aangemeld.

Beschikbaar gemaakte API

Andere instellingen die specifiek zijn voor web-API's zijn de beschikbare API en de weergegeven bereiken of app-rollen.

Bereiken en de toepassings-id-URI

Bereiken hebben meestal de vorm resourceURI/scopeName. Voor Microsoft Graph hebben de bereiken snelkoppelingen. User.Read is bijvoorbeeld een snelkoppeling voor https://graph.microsoft.com/user.read.

Definieer deze parameters tijdens de app-registratie:

• De resource-URI
• Een of meer bereiken
• Een of meer app-rollen

Standaard raadt de portal voor toepassingsregistratie aan dat u de resource-URI api://{clientId} gebruikt. Deze URI is uniek, maar kan niet door mensen worden gelezen. Als u de URI wijzigt, moet u ervoor zorgen dat de nieuwe waarde uniek is. De portal voor toepassingsregistratie zorgt ervoor dat u een geconfigureerd uitgeverdomein gebruikt.

Voor clienttoepassingen worden bereiken weergegeven als gedelegeerde machtigingen en app-rollen worden weergegeven als toepassingsmachtigingen voor uw web-API.

Bereiken worden ook weergegeven in het toestemmingsvenster dat wordt gepresenteerd aan gebruikers van uw app. Geef daarom de bijbehorende tekenreeksen op die het bereik beschrijven:

• Weergave voor een gebruiker.
• Weergave voor een tenantbeheerder, die beheerderstoestemming kan verlenen.

App-rollen kunnen niet worden toegestaan door een gebruiker (omdat ze worden gebruikt door een toepassing die de web-API namens zichzelf aanroept). Een tenantbeheerder moet toestemming geven voor clienttoepassingen van uw web-API die app-rollen beschikbaar maken. Zie Beheerderstoestemming voor meer informatie.

Gedelegeerde machtigingen beschikbaar maken (bereiken)

Als u gedelegeerde machtigingen of bereiken beschikbaar wilt maken, volgt u de stappen in Een toepassing configureren om een web-API beschikbaar te maken.

Als u het web-API-scenario volgt dat in deze set artikelen wordt beschreven, gebruikt u deze instellingen:

• URI voor de toepassings-id: accepteer de voorgestelde URI voor de toepassings-id (api://< clientId>) (indien hierom wordt gevraagd)
• Bereiknaam: toegang_als_gebruiker
• Wie kan toestemming geven: beheerders en gebruikers
• Weergavenaam van beheerderstoestemming: Toegang tot TodoListService als gebruiker
• Beschrijving van beheerderstoestemming: de TodoListService-web-API openen als gebruiker
• Weergavenaam van gebruikerstoestemming: Toegang tot TodoListService als gebruiker
• Beschrijving van gebruikerstoestemming: de TodoListService-web-API openen als gebruiker
• Status: ingeschakeld

Aanbeveling

Voor de URI van de toepassings-id kunt u deze bijvoorbeeld https://graph.microsoft.cominstellen op de fysieke instantie van de API. Dit kan handig zijn als de URL van de API die moet worden aangeroepen bekend is.

Als uw web-API wordt aangeroepen door een service- of daemon-app

Maak toepassingsmachtigingen beschikbaar in plaats van gedelegeerde machtigingen als uw API moet worden geopend door daemons, services of andere niet-interactieve (door een menselijke) toepassingen. Omdat daemon- en servicetypetoepassingen zonder toezicht worden uitgevoerd en worden geverifieerd met hun eigen identiteit, is er geen gebruiker om hun machtiging te 'delegeren'.

Toepassingsmachtigingen beschikbaar maken (app-rollen)

Volg de stappen in App-rollen toevoegen aan uw app om toepassingsmachtigingen beschikbaar te maken.

Onder Toegestane lidtypen in het deelvenster Rol voor app maken, selecteer Toepassingen. U kunt ook de rol toevoegen met behulp van de manifesteditor van de toepassing , zoals beschreven in het artikel.

Toegangstokens beperken tot specifieke clients-apps

App-rollen zijn het mechanisme dat een toepassingsontwikkelaar gebruikt om de machtigingen van de app beschikbaar te maken. De code van uw web-API moet controleren op app-rollen in de toegangstokens die worden ontvangen van aanroepers.

Als u een andere beveiligingslaag wilt toevoegen, kan een Microsoft Entra-tenantbeheerder de tenant zo configureren dat het Microsoft Identity Platform alleen beveiligingstokens voor de client-apps uitgeeft die ze hebben goedgekeurd voor API-toegang.

Als u de beveiliging wilt verbeteren door de uitgifte van tokens alleen te beperken tot client-apps waaraan app-rollen zijn toegewezen:

1. Selecteer uw app in het Microsoft Entra-beheercentrum onder EntraID-app-registraties>.
2. Ga op de Overzicht-pagina van de toepassing, in Essentials, naar de koppeling Beheerde toepassing in lokale directory om naar de pagina Overzicht van de Enterprise-toepassing te navigeren.
3. Selecteer Onder Beherende optie Eigenschappen.
4. Stel Opdracht vereist? in op Ja.
5. Selecteer Opslaan.

Microsoft Entra ID controleert nu op app-roltoewijzingen van clienttoepassingen die toegangstokens aanvragen voor uw web-API. Als er geen app-rollen aan een client-app zijn toegewezen, retourneert Microsoft Entra-id een foutbericht aan de client, vergelijkbaar met _invalid_client: AADSTS501051: Application \<application name\> isn't assigned to a role for the \<web API\>_.

Waarschuwing

GEBRUIK GEEN AADSTS-foutcodes of de bijbehorende berichttekenreeksen als letterlijke gegevens in de code van uw toepassing. De foutcodes 'AADSTS' en de tekenreeksen van het foutbericht die door Microsoft Entra-id worden geretourneerd, zijn niet onveranderbaar en kunnen op elk gewenst moment en zonder uw kennis door Microsoft worden gewijzigd. Als u vertakkingsbeslissingen in uw code neemt op basis van de waarden van de AADSTS-codes of de bijbehorende berichtreeksen, lopen de functionaliteit en stabiliteit van uw toepassing risico.

Volgende stap

Het volgende artikel in deze reeks is de configuratie van app-code.