Share 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.

Voer de stappen uit in de sectie Een toepassing registreren van quickstart: Een app registreren bij het Microsoft Identity Platform.

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.

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.

Een bereik toevoegen

Tip

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

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. Meld u aan bij het Microsoft Entra-beheercentrum als ten minste een cloudtoepassing Beheer istrator.

  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. Blader naar Identiteitstoepassingen>> App-registraties en selecteer vervolgens de app-registratie van uw API.

  4. Selecteer Een API weergeven

  5. Selecteer Toevoegen naast de URI van de toepassings-id als u er nog geen hebt geconfigureerd.

    U kunt de standaardwaarde api://<application-client-id> of een ander ondersteund URI-patroon voor app-id's gebruiken. 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.

  6. Selecteer Een bereik toevoegen:

    An app registration's Expose an API pane in the Azure portal

  7. 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. Selecteer Alleen beheerders voor machtigingen met meer bevoegdheden. Beheerders en gebruikers
    Weergavenaam van beheerderstoestemming Een korte beschrijving van het doel van het bereik die alleen beheerders te zien krijgen. Read-only access to Employee records
    Beschrijving van beheerderstoestemming Een uitvoeriger beschrijving van de machtiging die door het bereik wordt verleend en die alleen aan beheerders wordt weergegeven. Allow the application to have read-only access to all Employee data.
    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. Read-only access to your Employee records
    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. Allow the application to have read-only access to your Employee data.

  8. Stel de Status in op Ingeschakeld en selecteer Bereik toevoegen.

  9. (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:

Veld Voorbeeldwaarde
Naam van bereik Employees.Write.All
Wie kan toestemming verlenen? Alleen beheerders
Weergavenaam van beheerderstoestemming Write access to Employee records
Beschrijving van beheerderstoestemming Allow the application to have write access to all Employee data.
Weergavenaam van gebruikerstoestemming Geen (leeg laten)
Beschrijving van gebruikerstoestemming Geen (leeg laten)

Stel de Status in op Ingeschakeld en selecteer Bereik toevoegen.

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:

Screenshot of the Expose an API pane showing two exposed scopes.

Zoals in de afbeelding wordt weergegeven, is de volledige tekenreeks van een bereik een samenvoeging van de URI voor de app-ID van uw web-API en de Bereiknaam 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 stappen

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