Notitie
Voor toegang tot deze pagina is autorisatie vereist. U kunt proberen u aan te melden of de directory te wijzigen.
Voor toegang tot deze pagina is autorisatie vereist. U kunt proberen de mappen te wijzigen.
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:
- Selecteer uw app in het Microsoft Entra-beheercentrum en selecteer vervolgens Manifest.
- Zoek de eigenschap accessTokenAcceptedVersion in het manifest.
- 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.
- 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.com
instellen 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:
- Selecteer uw app in het Microsoft Entra-beheercentrum onder EntraID-app-registraties>.
- 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.
- Selecteer Onder Beherende optie Eigenschappen.
- Stel Opdracht vereist? in op Ja.
- 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.