Delen via

Een toepassing configureren om een web-API beschikbaar te maken

In deze handleiding registreert u een web-API bij het Microsoft Identity Platform en maakt u deze beschikbaar voor client-apps door een bereik toe te voegen. Door uw web-API te registreren en beschikbaar te maken via bereiken, een eigenaar en app-rol toe te wijzen, kunt u machtigingen bieden voor de resources voor geautoriseerde gebruikers en client-apps die toegang hebben tot uw API.

Vereisten

De web-API registreren

Toegang tot API's vereist configuratie van toegangsbereiken en -rollen. Als u web-API's van uw resourcetoepassing beschikbaar wilt maken voor clienttoepassingen, configureert u toegangsbereiken en rollen voor de API. Als u wilt dat een clienttoepassing toegang heeft tot een web-API, configureert u machtigingen voor toegang tot de API in de app-registratie. Als u toegang via bereiken tot de resources in uw web-API wilt instellen, moet u de API eerst registreren bij het Microsoft Identity Platform.

  1. Meld u aan bij het Microsoft Entra-beheercentrum als minimaal Cloudtoepassingsbeheerder.
  2. Als u toegang hebt tot meerdere tenants, gebruikt u het pictogram Instellingen in het bovenste menu om over te schakelen naar de tenant met de app-registratie vanuit het menu Mappen en abonnementen.
  3. Voer de stappen in het registreren van een toepassing uit en sla de sectie Omleidings-URI (optioneel) over. U hoeft geen omleidings-URI voor een web-API te configureren omdat er geen gebruiker interactief is aangemeld.

Toepassingseigenaar toewijzen

  1. In de app-registratie, onder Beheren, selecteer Eigenaren en Eigenaren toevoegen.
  2. Zoek en selecteer in het nieuwe venster de eigenaar(s) die u aan de toepassing wilt toewijzen. Geselecteerde eigenaren worden weergegeven in het rechterdeelvenster. Als u klaar bent, bevestigt u dit met Selecteren. De app-eigenaar(s) wordt nu weergegeven in de lijst met eigenaren.

Notitie

Zorg ervoor dat een eigenaar is toegewezen aan zowel de API-toepassing als de toepassing waaraan u machtigingen wilt toevoegen, anders wordt de API niet vermeld bij het aanvragen van API-machtigingen.

App-rol toewijzen

  1. Selecteer app-rollen in uw app-registratie onder Beheren en App-rol maken.

  2. Geef vervolgens de kenmerken van de app-rol op in het deelvenster App-rol maken. Voor deze procedure kunt u de voorbeeldwaarden gebruiken of uw eigen waarden opgeven.

    Veld Omschrijving Voorbeeld
    Weergavenaam De naam van uw app-rol Personneldossiers
    De toegestane ledentypen Hiermee geeft u op of de app-rol kan worden toegewezen aan gebruikers/groepen en/of toepassingen Toepassingen
    Waarde De waarde die wordt weergegeven in de claim 'rollen' van een token Employee.Records
    Beschrijving Een gedetailleerdere beschrijving van de app-rol Toepassingen hebben toegang tot werknemersrecords

  3. Schakel het selectievakje in om de app-rol in te schakelen en selecteer vervolgens Toepassen.

Een bereik toevoegen

Wanneer de web-API is geregistreerd, een app-rol en eigenaar is toegewezen, kunt u scopes toevoegen aan de code van de API, zodat deze gedetailleerde machtigingen kan bieden aan consumenten.

De code in een clienttoepassing vraagt machtigingen aan voor het uitvoeren van bewerkingen die zijn gedefinieerd door de web-API door een toegangstoken en de bijbehorende aanvragen aan de beveiligde bron (de web-API) door te geven. Uw web-API voert de aangevraagde bewerking alleen uit als het toegangstoken dat wordt ontvangen, de bereiken bevat die voor de bewerking vereist zijn.

Voer eerst de volgende stappen uit om een voorbeeldbereik te maken met de naam Employees.Read.All:

  1. Selecteer Een API beschikbaar maken.

  2. Selecteer Boven aan de pagina de optie Toevoegen naast de URI van de toepassings-id. Dit is standaard ingesteld op api://<application-client-id>. De URI van de App-ID fungeert als voorvoegsel voor de scope waarnaar u verwijst in de API-code en moet wereldwijd uniek zijn. Selecteer Opslaan.

  3. Selecteer Een bereik toevoegen:

    Het deelvenster Een API weergeven van een app-registratie in de Azure-portal

  4. Geef vervolgens de kenmerken van het bereik op in het deelvenster Een bereik toevoegen. Voor deze procedure kunt u de voorbeeldwaarden gebruiken of uw eigen waarden opgeven.

    Veld Omschrijving Voorbeeld
    Bereiknaam De naam van uw scope. Een algemene naamconventie voor bereiken is resource.operation.constraint. Employees.Read.All
    Wie kan toestemming verlenen? Of gebruikers toestemming kunnen verlenen voor dit bereik, of dat toestemming van de beheerder is vereist. Alleen beheerders moeten worden gebruikt voor machtigingen met hogere rechten. Beheerders en gebruikers
    Weergavenaam van beheerderstoestemming Een korte beschrijving van het doel van het bereik die alleen beheerders te zien krijgen. Alleen-lezentoegang tot werknemersgegevens
    Beschrijving van beheerderstoestemming Een uitvoeriger beschrijving van de machtiging die door het bereik wordt verleend en die alleen aan beheerders wordt weergegeven. Hiermee staat u toe dat de toepassing alleen-lezentoegang heeft tot alle werknemersgegevens.
    Gebruikerstoestemmingsweergavenaam Een korte beschrijving van het doel van het bereik. Wordt alleen aan gebruikers weergegeven als u Wie kan instemmen hebt ingesteld op Beheerders en gebruikers. Alleen-lezentoegang tot uw werknemersgegevens
    Beschrijving van gebruikerstoestemming Een uitvoeriger beschrijving van de toestemming die binnen de scope wordt verleend. Wordt alleen aan gebruikers weergegeven als u Wie kan instemmen hebt ingesteld op Beheerders en gebruikers. Sta toe dat de toepassing alleen-lezentoegang heeft tot uw werknemersgegevens.
    Staat/provincie Of het bereik is ingeschakeld of uitgeschakeld. Ingeschakeld

  5. Selecteer Bereik toevoegen.

  6. (Optioneel) Als u vragen om toestemming door gebruikers van uw toepassing wilt onderdrukken voor de bereiken die u hebt gedefinieerd, kunt u de clienttoepassing vooraf autoriseren voor toegang tot uw web-API. U moet uitsluitend die clienttoepassingen vooraf autoriseren die u vertrouwt, omdat uw gebruikers niet de mogelijkheid hebben om toestemming te weigeren.

    1. Selecteer onder Geautoriseerde clienttoepassingen de optie Een clienttoepassing toevoegen.
    2. Voer de toepassings-id (client) in van de client-toepassing die u vooraf wilt autoriseren. Bijvoorbeeld een web-toepassing die u eerder hebt geregistreerd.
    3. Selecteer onder Geautoriseerde bereiken de bereiken waarvoor u de vraag om toestemming wilt onderdrukken en selecteer vervolgens Toepassing toevoegen.

    Als u deze optionele stap hebt gevolgd, is de clienttoepassing nu een vooraf geautoriseerde clienttoepassing (PCA) en worden gebruikers niet om toestemming gevraagd wanneer ze zich aanmelden.

Voeg vervolgens nog een voorbeeldbereik toe met de naam Employees.Write.All waarvoor alleen beheerders toestemming kunnen verlenen. Bereiken waarvoor toestemming van beheerders nodig is, worden doorgaans gebruikt voor toegang tot bewerkingen waarvoor een speciale machtiging nodig is, en worden vaak gebruikt door clienttoepassingen die worden uitgevoerd als back-endservices of daemons die een gebruiker niet interactief aanmelden.

Als u het Employees.Write.All voorbeeldbereik wilt toevoegen, volgt u de stappen in de sectie Een bereik toevoegen en geeft u deze waarden op in het deelvenster Een bereik toevoegen. Selecteer Bereik toevoegen wanneer u klaar bent:

Veld Voorbeeldwaarde
Bereiknaam Employees.Write.All
Wie kan toestemming verlenen? Alleen beheerders
Weergavenaam van beheerderstoestemming Schrijftoegang tot werknemersdossiers
Beschrijving van beheerderstoestemming Hiermee staat u toe dat de toepassing schrijftoegang heeft tot alle gegevens van werknemers.
Gebruikerstoestemmingsweergavenaam Geen (leeg laten)
Beschrijving van gebruikerstoestemming Geen (leeg laten)
Staat/provincie Ingeschakeld

De openbare bereiken verifiëren

Als u beide voorbeeldbereiken hebt toegevoegd die in de eerdere secties worden beschreven, zullen ze verschijnen in het deelvenster Een API Exposeren van de app-registratie van uw web-API, vergelijkbaar met onderstaande afbeelding.

Schermopname van het deelvenster API Exposeren, waarin twee toegestane scopes worden weergegeven.

De volledige tekenreeks van het bereik is de samenvoeging van uw web-API's Applicatie-ID URI en de Bereiknaam. Als de URI voor de app-ID van uw web-API bijvoorbeeld https://contoso.com/api is en uw bereiknaam Employees.Read.All is, is dit het volledige bereik:

https://contoso.com/api/Employees.Read.All

De ingerichte scopes gebruiken

In het volgende artikel in deze reeks configureert u de registratie van een client-app met toegang tot uw web-API en de bereiken die u hebt gedefinieerd door de stappen in dit artikel te volgen.

Zodra er toestemming is verleend voor de registratie van een client-app om toegang te krijgen tot uw web-API, kan de client een OAuth 2.0-toegangstoken ontvangen van het identiteitsplatform. Wanneer de client de web-API aanroept, wordt een toegangstoken weergegeven waarvan de bereikclaim (scp) is ingesteld op de machtigingen die u hebt opgegeven in de app-registratie van de client.

U kunt indien nodig later aanvullende bereiken weergeven. Houd er rekening mee dat uw web-API meerdere scopes kan blootstellen die aan verschillende bewerkingen gekoppeld zijn. Uw resource kan de toegang tot de web-API tijdens de uitvoering controleren door de scope claims (scp) in het OAuth 2.0-toegangstoken dat het ontvangt te evalueren.

Volgende stap

Nu u uw web-API hebt blootgesteld door het bereik ervan te configureren, configureert u de registratie van uw clienttoepassing voor toegang tot het bereik.

Een app-registratie configureren voor toegang tot de web-API