Registratie van beveiligde web-API-apps

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

Voor de gebruikelijke stappen om een app te registeren, gaat u naar Quickstart: Een toepassing registreren bij het Microsoft-identiteitsplatform.

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 ondersteunde accounttypen die u selecteert wanneer u de registratie van uw web-API-toepassing maakt in Azure Portal.

• Als de waarde van ondersteunde accounttypen Accounts 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 uitgeversdomein 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 Toestemming van de beheerder 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:

• Toepassings-id-URI: accepteer de voorgestelde toepassings-id-URI (api://< clientId>) (indien gevraagd)
• Bereiknaam: access_as_user
• Wie kan toestemming verlenen?: beheerders en gebruikers
• Weergavenaam van de beheerderstoestemming: TodoListService openen als gebruiker
• Beschrijving van de beheerderstoestemming: hiermee opent u de TodoListService-web-API als gebruiker
• Weergavenaam van de gebruikerstoestemming: TodoListService openen als gebruiker
• Beschrijving van toestemming van de gebruiker: hiermee opent u de TodoListService-Web-API als een gebruikers
• Status: ingeschakeld

Tip

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 mens gebruikte) 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.

Selecteer in het deelvenster App-rol maken onder Toegestane ledentypen de optie Toepassingen. Of voeg de rol toe 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 in het Microsoft Entra-beheercentrum uw app onder >
2. Zoek en selecteer op de overzichtspagina van de toepassing in Essentials de beheerde toepassing in de lokale mapkoppeling om naar de overzichtspagina van de toepassing te gaan.
3. Selecteer Eigenschappen onder Beheren.
4. Is toewijzing vereist? naar Nee.
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 hun berichttekenreeksen als letterlijke tekens 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 Configuratie van app-code.