Delen via

Quickstart: Een toepassing configureren om een web-API beschikbaar te maken

  • Artikel

In deze quickstart 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 als cloudtoepassingsbeheerder aan bij het Microsoft Entra-beheercentrum.
  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. Selecteer In de app-registratie onder Beheren de optie 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 zowel de API-toepassing als de toepassing die u machtigingen wilt toevoegen aan beide een eigenaar hebben, 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 Werknemersrecords
    De toegestane ledentypen Hiermee geeft u op of de app-rol kan worden toegewezen aan gebruikers/groepen en/of toepassingen Toepassingen
    Value 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

Tip

Stappen in dit artikel kunnen enigszins variëren op basis van de portal waaruit u begint.

Wanneer de web-API is geregistreerd, hebt u een app-rol en -eigenaar toegewezen, kunt u bereiken toevoegen aan de code van de API, zodat deze een gedetailleerde machtiging 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 bereiken waarnaar u verwijst in de code van de API en moet globaal 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
    Naam van bereik De naam van uw bereik. 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. Beheerders mogen alleen worden gebruikt voor machtigingen met hogere bevoegdheden. Beheerders en gebruikers
    Weergavenaam van beheerderstoestemming Een korte beschrijving van het doel van het bereik die alleen beheerders te zien krijgen. Alleen-lezentoegang tot werknemersrecords
    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.
    Weergavenaam van gebruikerstoestemming Een korte beschrijving van het doel van het bereik. Wordt alleen aan gebruikers weergegeven als u Wie kan instemmen met deze machtiging hebt ingesteld op Beheerders en gebruikers. Alleen-lezentoegang tot uw werknemersrecords
    Beschrijving van gebruikerstoestemming Een uitvoeriger beschrijving van de machtiging die door het bereik wordt verleend. Wordt alleen aan gebruikers weergegeven als u Wie kan instemmen met deze machtiging 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
Naam van bereik Employees.Write.All
Wie kan toestemming verlenen? Alleen beheerders
Weergavenaam van beheerderstoestemming Schrijftoegang tot werknemersrecords
Beschrijving van beheerderstoestemming Hiermee staat u toe dat de toepassing schrijftoegang heeft tot alle gegevens van werknemers.
Weergavenaam van gebruikerstoestemming Geen (leeg laten)
Beschrijving van gebruikerstoestemming Geen (leeg laten)
Staat/provincie Ingeschakeld

De beschikbaar gemaakte bereiken verifiëren

Als u beide voorbeeldbereiken hebt toegevoegd die in de vorige secties worden beschreven, worden deze weergegeven in het deelvenster Een API beschikbaar maken van de app-registratie van uw web-API, vergelijkbaar met de volgende afbeelding:

Schermopname van het deelvenster Een API weergeven, waarin twee bereiken worden weergegeven.

De volledige tekenreeks van het bereik is de samenvoeging van de URI van de toepassings-id van uw web-API en de naam van het bereik. 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 beschikbaar gemaakte bereiken 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 een registratie van een client-app is verleend voor toegang tot uw web-API, kan de client een OAuth 2.0-toegangstoken verlenen door 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 aanvullende bereiken indien nodig later weergeven. Houd er rekening mee dat uw web-API meerdere bereiken kan weergeven die aan verschillende bewerkingen gekoppeld zijn. Uw resource kan de toegang tot de web-API tijdens runtime beheren door het bereik (scp) claims te evalueren in het OAuth 2.0-toegangstoken dat het ontvangt.

Volgende stap

Nu u uw web-API beschikbaar hebt gemaakt door de bereiken ervan te configureren, configureert u de registratie van uw clienttoepassing met machtigingen voor toegang tot de bereiken.

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