Toegang tot API's in uw API-centrum autoriseren

Configureer instellingen voor het autoriseren van toegang tot API's in uw API-centrum. Deze instellingen:

  • Schakel API-authenticatie en autorisatie in door gebruik te maken van API-sleutels, OAuth 2.0-autorisatie of een ander HTTP-beveiligingsschema
  • Verificatieconfiguraties koppelen aan API-versies in uw inventaris
  • Toegang tot API-versies voor aangewezen gebruikers of groepen beheren via toegangsbeleid
  • Geautoriseerde gebruikers in staat stellen API's te testen in de API Center-portal

Vereiste voorwaarden

Optie 1: VERIFICATIE van API-sleutel configureren

Voer de volgende stappen uit voor een API die ondersteuning biedt voor VERIFICATIE van API-sleutels.

1. API-sleutel opslaan in Azure Key Vault

Als u de API-sleutel wilt opslaan als een geheim in de sleutelkluis, raadpleegt u Geheim instellen en ophalen in Key Vault.

Toegang tot de sleutelkluis door gebruik te maken van de beheerde identiteit van je API-centrum.

Een beheerde identiteit inschakelen in uw API-centrum

Voor dit scenario gebruikt uw API-centrum een beheerde identiteit voor toegang tot Azure-resources. Afhankelijk van uw behoeften schakelt u een door het systeem toegewezen of een of meer door de gebruiker toegewezen beheerde identiteiten in.

In de volgende voorbeelden ziet u hoe u een door het systeem toegewezen beheerde identiteit inschakelt met behulp van Azure Portal of de Azure CLI. Op hoog niveau zijn configuratiestappen vergelijkbaar voor een door de gebruiker toegewezen beheerde identiteit.

  1. Ga in de portal naar uw API-centrum.
  2. Selecteer beheerde identiteiten in het zijbalkmenu onder Beveiliging.
  3. Selecteer Systeem toegewezen en stel de status in op Aan.
  4. Selecteer Opslaan.

De beheerde identiteit de rol 'Key Vault Secrets User' toewijzen

Als u het importeren van de assets wilt toestaan, wijst u de beheerde identiteit van uw API-centrum de rol Key Vault Secrets User toe in uw Azure-sleutelkluis. U kunt de portal of de Azure CLI gebruiken.

  1. Ga in de portal naar uw sleutelkluis.
  2. Selecteer toegangsbeheer (IAM) in het zijbalkmenu.
  3. Selecteer + Roltoewijzing toevoegen.
  4. Stel op de Roltoewijzing-pagina als volgt de waarden in:
    1. Selecteer Key Vault Secrets User op het tabblad Rol.
    2. Op het tabblad Leden, in Toegang toewijzen aan - Beheerde identiteit> selecteren+ Leden selecteren.
    3. Selecteer op de pagina Beheerde identiteiten de door het systeem toegewezen beheerde identiteit van uw API-center dat u in de vorige sectie hebt toegevoegd. Klik op Selecteren.
    4. Selecteer Beoordelen en toewijzen.

2. API-sleutelconfiguratie toevoegen

Caution

Extra zorg is vereist bij het gebruik van een clientreferentiestroom met de testconsole van de ontwikkelaarsportal. Bekijk beveiligingsoverwegingen. Bij het gebruik van API-sleutels en OAuth 2.0-geheimen kan elke gebruiker met toegang tot het ontwikkelportaal API's gebruiken. OAuth 2.0 autorisatiecodeflow met PKCE wordt aanbevolen om het blootstellen van geheimen te voorkomen.

  1. Ga in de portal naar uw API-centrum.

  2. Selecteer onder Beheerautorisatie>+ configuratie toevoegen.

  3. Stel bij Toevoegen de volgende waarden in: Screenshot van het configureren van een API-sleutel in het portaal.

    Omgeving Beschrijving
    Titel Voer een naam in voor de autorisatie.
    Beschrijving Voer desgewenst een beschrijving in voor de autorisatie.
    Beveiligingsschema Selecteer API-sleutel.
    Locatie van API-sleutel Selecteer hoe de sleutel wordt weergegeven in API-aanvragen. Beschikbare waarden zijn Header (aanvraagheader) en Query (queryparameter).
    Parameternaam van API-sleutel Voer de naam in van de HTTP-header of queryparameter die de API-sleutel bevat. Voorbeeld: x-api-key
    API-sleutel Geheimenreferentie van de Sleutelkluis Selecteer Selecteer en selecteer het abonnement, de sleutelkluis en het geheim dat u hebt opgeslagen. Voorbeeld: https://<key-vault-name>.vault.azure.net/secrets/<secret-name>

  4. Klik op Creëren.

Nadat je deze configuratie hebt voltooid, ga je naar de sectie 'Voeg authenticatie aan een API-versie' toe om de API-sleutelconfiguratie aan een API-versie te koppelen.

Optie 2: OAuth 2.0-autorisatie configureren

Voer de volgende stappen uit voor een API die OAuth 2.0-autorisatie ondersteunt. U kunt een of beide van de volgende stromen configureren:

  • Autorisatiecodestroom met PKCE (Proof Key for Code Exchange) - Verifieer gebruikers in de browser, zoals in de API Center-portal.
  • Clientreferenties stroom - voor toepassingen waarvoor geen specifieke gebruikersmachtigingen zijn vereist.

Important

Je kunt geen API-sleutels en OAuth 2.0-geheimen gebruiken als je anonieme toegang voor het klantportaal inschakelt. Als je anonieme toegang instelt voor het klantportaal, wordt de instelling genegeerd en faalt de autorisatie van de testconsole.

Caution

Extra zorg is vereist bij het gebruik van een clientreferentiestroom met de testconsole van de ontwikkelaarsportal. Bekijk beveiligingsoverwegingen. Bij het gebruik van API-sleutels en OAuth 2.0-geheimen kan elke gebruiker met toegang tot het ontwikkelportaal API's gebruiken. OAuth 2.0 autorisatiecodeflow met PKCE wordt aanbevolen om het blootstellen van geheimen te voorkomen.

1. Een OAuth 2.0-app maken

Maak een app-registratie in een id-provider, zoals de Microsoft Entra-tenant die is gekoppeld aan uw abonnement. De stappen zijn afhankelijk van uw id-provider.

In het volgende voorbeeld ziet u hoe u een app-registratie maakt in Microsoft Entra ID.

  1. Meld u aan bij Azure Portal met voldoende machtigingen in de tenant.
  2. Ga naar Microsoft Entra ID>+ Nieuwe registratie.
  3. Op de pagina Een toepassing registreren :
    1. Voer in Naam een beschrijvende naam in.
    2. Selecteer in Ondersteunde accounttypes een geschikte optie, zoals Accounts in deze organisatiemap alleen (Enkele tenant).
    3. Voor de autorisatiecodeflow, selecteer in Redirect URISingle-page application (SPA) en voer de URI van je API Center-portaal in: https://<service-name>.portal.<location>.azure-api-center.ms. Vervang <service-name> door de naam van uw API-centrum en <location> door de implementatielocatie. Voorbeeld: https://myapicenter.portal.eastus.azure-api-center.ms
    4. Selecteer Registreren.
  4. Selecteer onder Beherende optie Certificaten en geheimen>+ Nieuw clientgeheim.
    1. Voer een beschrijving in.
    2. Selecteer een optie voor Verlopen.
    3. Selecteer Toevoegen.
    4. Kopieer de waarde van het clientgeheim voordat u de pagina verlaat. U hebt deze nodig in de volgende sectie.
  5. Voeg desgewenst API-bereiken toe aan uw app-registratie. Zie Een toepassing configureren om een web-API beschikbaar te maken.

Bij het configureren van OAuth 2.0 in uw API-centrum hebt u de volgende waarden nodig uit de app-registratie:

  • Toepassings-id (client) op de pagina Overzicht en het clientgeheim dat u hebt gekopieerd.
  • De volgende endpoint-URL's van Overzicht>Endpoints:
    • OAuth2.0-autorisatie-eindpunt (v2)
    • OAuth 2.0-tokeneindpunt (v2) ( ook gebruikt als eindpunt voor tokenvernieuwing)
  • Api-bereiken die u hebt geconfigureerd.

2. Clientgeheim opslaan in Azure Key Vault

Zie Geheim instellen en ophalen in Key Vault om het clientgeheim op te slaan in de sleutelkluis.

Toegang tot de sleutelkluis door gebruik te maken van de beheerde identiteit van je API-centrum.

Een beheerde identiteit inschakelen in uw API-centrum

Voor dit scenario gebruikt uw API-centrum een beheerde identiteit voor toegang tot Azure-resources. Afhankelijk van uw behoeften schakelt u een door het systeem toegewezen of een of meer door de gebruiker toegewezen beheerde identiteiten in.

In de volgende voorbeelden ziet u hoe u een door het systeem toegewezen beheerde identiteit inschakelt met behulp van Azure Portal of de Azure CLI. Op hoog niveau zijn configuratiestappen vergelijkbaar voor een door de gebruiker toegewezen beheerde identiteit.

  1. Ga in de portal naar uw API-centrum.
  2. Selecteer beheerde identiteiten in het zijbalkmenu onder Beveiliging.
  3. Selecteer Systeem toegewezen en stel de status in op Aan.
  4. Selecteer Opslaan.

De beheerde identiteit de rol 'Key Vault Secrets User' toewijzen

Als u het importeren van de assets wilt toestaan, wijst u de beheerde identiteit van uw API-centrum de rol Key Vault Secrets User toe in uw Azure-sleutelkluis. U kunt de portal of de Azure CLI gebruiken.

  1. Ga in de portal naar uw sleutelkluis.
  2. Selecteer toegangsbeheer (IAM) in het zijbalkmenu.
  3. Selecteer + Roltoewijzing toevoegen.
  4. Stel op de Roltoewijzing-pagina als volgt de waarden in:
    1. Selecteer Key Vault Secrets User op het tabblad Rol.
    2. Op het tabblad Leden, in Toegang toewijzen aan - Beheerde identiteit> selecteren+ Leden selecteren.
    3. Selecteer op de pagina Beheerde identiteiten de door het systeem toegewezen beheerde identiteit van uw API-center dat u in de vorige sectie hebt toegevoegd. Klik op Selecteren.
    4. Selecteer Beoordelen en toewijzen.

3. OAuth 2.0-configuratie toevoegen

  1. Ga in de portal naar uw API-centrum.

  2. Selecteer onder Beheerautorisatie>+ configuratie toevoegen.

  3. Op Add-configuratie stel je de volgende waarden in:

    Schermopname van het configureren van OAuth 2.0 in de portal.

    Opmerking

    Gebruik waarden uit de app-registratie die u eerder hebt gemaakt. Zoek voor Microsoft Entra ID de Client-ID op de Overzicht-pagina van de app-registratie en de URL-eindpunten op Overzicht>Eindpunten.

    Omgeving Beschrijving
    Titel Voer een naam in voor de autorisatie.
    Beschrijving Voer desgewenst een beschrijving in voor de autorisatie.
    Beveiligingsschema Selecteer OAuth2.
    Client-ID Voer de client-id (GUID) in van de app die u hebt gemaakt in uw id-provider.
    Clientsecret Selecteer het abonnement, de sleutelkluis en het clientgeheim dat u hebt opgeslagen.

    Voorbeeld: https://<key-vault-name>.vault.azure.net/secrets/<secret-name>
    Autorisatie-URL Voer het OAuth 2.0-autorisatie-eindpunt in voor de id-provider.

    Voorbeeld voor Microsoft Entra-id: https://login.microsoftonline.com/<tenant>/oauth2/v2.0/authorize
    Token-URL Voer het OAuth 2.0-tokeneindpunt in voor de id-provider.

    Voorbeeld voor Microsoft Entra-id: https://login.microsoftonline.com/<tenant>/oauth2/v2.0/token
    URL vernieuwen Voer het OAuth 2.0-tokenvernieuwingseindpunt in voor de id-provider. Voor de meeste providers hetzelfde als de token-URL

    Voorbeeld voor Microsoft Entra-id: https://login.microsoftonline.com/<tenant>/oauth2/v2.0/token
    OAuth2-stroom Selecteer een of beide OAuth 2.0-stromen: Autorisatiecode (PKCE) en clientreferenties.
    Scopes Voer een of meer API-bereiken in die zijn geconfigureerd voor uw API, gescheiden door spaties. Als er geen reikwijdtes zijn geconfigureerd, voer .default in.

  4. Selecteer Maken om de configuratie op te slaan.

Nadat u deze configuratie hebt voltooid, gaat u naar de sectie Verificatie toevoegen aan een API-versie om de OAuth 2.0-configuratie te koppelen aan een API-versie.

Optie 3: Instellingen configureren voor een ander HTTP-beveiligingsschema

Voer de volgende stappen uit voor API's die gebruikmaken van een ander HTTP-beveiligingsschema, zoals basisverificatie of bearer-tokens die geen OAuth 2.0 gebruiken. Mogelijk moet u deze optie kiezen voor verouderde API's.

Ga in de portal naar uw API-centrum.

  1. Selecteer onder Beheerautorisatie>+ configuratie toevoegen.

  2. Op Add-configuratie stel je de volgende waarden in:

    Omgeving Beschrijving
    Titel Voer een naam in voor de autorisatie.
    Beschrijving Voer desgewenst een beschrijving in voor de autorisatie.
    Beveiligingsschema Selecteer HTTP.
    Verificatieschema Selecteer het verificatieschema dat door de API wordt gebruikt. Voorbeelden hiervan zijn de schema's in de volgende tabel.
    Verificatieschema Beschrijving
    Basic Verzendt username:password als een met Base64 gecodeerde tekenreeks in de Authorization: Basic <credentials> header.
    Bearer Hiermee wordt een ander token dan een OAuth 2.0-toegangstoken in de Authorization: Bearer <token> header verzonden.
    Samenvatting Een uitdaging-antwoordsysteem waarbij de server een nonce verzendt; de client reageert met een hash van inloggegevens + nonce.
    Aangepast Een ander mechanismeschema, zoals een leverancierspecifiek schema.

Nadat u deze configuratie hebt voltooid, gaat u naar de volgende sectie om de configuratie te koppelen aan een API-versie.

Verificatieconfiguratie toevoegen aan een API-versie

Nadat u een verificatieschema hebt geconfigureerd, koppelt u de configuratie aan een API-versie.

  1. Ga in de portal naar uw API-centrum.

  2. Selecteer Assets onder Inventaris.

  3. Selecteer de API waaraan u de configuratie wilt koppelen.

  4. Selecteer onder DetailsVersies en selecteer vervolgens de doel-API-versie.

  5. Selecteer Access beheren in het contextmenu voor de API-versie. Schermopname van het koppelen van een verificatieconfiguratie aan een API-versie in de portal.

  6. Selecteer bij Toegang beheren+ Authenticatie toevoegen.

  7. Selecteer een beschikbare verificatieconfiguratie.

  8. Klik op Creëren.

Opmerking

Je kunt meerdere authenticatieconfiguraties toevoegen aan een API-versie (bijvoorbeeld zowel de API-sleutel als OAuth 2.0), als de API dat ondersteunt. U kunt ook dezelfde configuratie toevoegen aan meerdere API-versies.

Toegang beheren voor specifieke gebruikers of groepen

Configureer een toegangsbeleid waarmee gebruikers of groepen de rol Api Center Credential Access Reader worden toegewezen, met het bereik van specifieke verificatieconfiguraties in een API-versie. Deze rol geeft aangewezen gebruikers de mogelijkheid om een API te testen in het API Center-portaal.

  1. Ga in de portal naar uw API-centrum.

  2. Ga naar een API-versie met een verificatieconfiguratie.

  3. Selecteer Toegang beheren.

  4. Selecteer een verificatieconfiguratie die u wilt beheren.

  5. Selecteer toegangsbeleid bewerken in de vervolgkeuzelijst. Schermopname van het toevoegen van een toegangsbeleid in de portal.

  6. Selecteer op de pagina Toegang beherende optie + Gebruikers toevoegen > of + Groepen toevoegen>.

  7. Gebruikers of groepen zoeken en selecteren. U kunt meerdere items selecteren.

  8. Klik op Select.

Aanbeveling

Als u gebruikers of groepen wilt verwijderen, selecteert u Verwijderen in het contextmenu op de pagina Toegang beheren .

De API testen in de API Center-portal

Test een API die u hebt geconfigureerd voor verificatie en gebruikerstoegang.

Aanbeveling

U kunt ook zichtbaarheidsinstellingen configureren om te bepalen welke API's worden weergegeven voor alle aangemelde gebruikers in de portal.

  1. Ga in de portal naar uw API-centrum.

  2. Selecteer in de API Center Portal de Portaalinstellingen>API Center-portaal weergeven.

  3. Selecteer een API en selecteer vervolgens een versie met een verificatiemethode die is geconfigureerd.

  4. Selecteer onder Optiesde optie Documentatie weergeven. Schermopname van API-details in de API Center-portal.

  5. Selecteer een bewerking en selecteer vervolgens Deze API uitproberen.

  6. Controleer de verificatie-instellingen. Als u toegang hebt, selecteert u Verzenden. Schermopname van het testen van een API in de testconsole van de API Center-portal.

  7. Een geslaagde bewerking retourneert een 200 OK antwoordcode en antwoordtekst. Een mislukte bewerking retourneert een foutbericht.

Verwante inhoud

  • Last updated on