Share via


Een aangepaste claimprovider configureren voor een tokenuitgifte-gebeurtenis

In dit artikel wordt beschreven hoe u een aangepaste claimprovider configureert voor een begin-gebeurtenis voor tokenuitgifte. Met behulp van een bestaande Azure Functions REST API registreert u een aangepaste verificatie-extensie en voegt u kenmerken toe die u verwacht te parseren vanuit uw REST API. Als u de aangepaste verificatie-extensie wilt testen, registreert u een voorbeeld van een OpenID-Verbinding maken-toepassing om een token op te halen en de claims weer te geven.

Vereisten

  • Een Azure-abonnement met de mogelijkheid om Azure Functions te maken. Als u geen bestaand Azure-account hebt, meldt u zich aan voor een gratis proefversie of gebruikt u de voordelen van uw Visual Studio-abonnement wanneer u een account maakt.
  • Een Azure Function-app met een HTTP-triggerfunctie die is geconfigureerd voor een begingebeurtenis voor tokenuitgifte. Als u nog geen tokenuitgifte hebt, volgt u de stappen in het maken van een http-triggerfunctie voor het starten van een tokenuitgifte.
  • Een basiskennis van de concepten die worden behandeld in het overzicht van aangepaste verificatie-extensies.
  • Een Microsoft Entra ID-tenant. U kunt een klant- of personeelstenant gebruiken voor deze handleiding.
    • Gebruik voor externe tenants een gebruikersstroom voor registratie en aanmelding.

Stap 1: Een aangepaste verificatie-extensie registreren

U configureert nu een aangepaste verificatie-extensie, die wordt gebruikt door Microsoft Entra ID om uw Azure-functie aan te roepen. De aangepaste verificatie-extensie bevat informatie over uw REST API-eindpunt, de claims die worden geparseerd vanuit uw REST API en hoe u zich kunt verifiëren bij uw REST API. Volg deze stappen om een aangepaste verificatie-extensie te registreren bij uw Azure Function-app.

Notitie

U kunt maximaal 100 aangepaste uitbreidingsbeleidsregels hebben.

Een aangepaste verificatie-extensie registreren

  1. Meld u aan bij Azure Portal als ten minste een toepassing Beheer istrator en verificatie Beheer istrator.
  2. Zoek en selecteer Microsoft Entra-id en selecteer Bedrijfstoepassingen.
  3. Selecteer Aangepaste verificatie-extensies en selecteer vervolgens Een aangepaste extensie maken.
  4. Selecteer in Basis het gebeurtenistype TokenIssuanceStart en selecteer Volgende.
  5. Vul in Endpoint Configuration de volgende eigenschappen in:
    • Naam : een naam voor uw aangepaste verificatie-extensie. Bijvoorbeeld tokenuitgifte.
    • Doel-URL : de {Function_Url} URL van uw Azure-functie. Ga naar de pagina Overzicht van uw Azure Function-app en selecteer vervolgens de functie die u hebt gemaakt. Selecteer op de pagina Overzicht van functie ophalen de optie Functie-URL ophalen en gebruik het kopieerpictogram om de URL te kopiëren.
    • Beschrijving : een beschrijving voor uw aangepaste verificatie-extensies.
  6. Selecteer Volgende.
  7. Selecteer in API-verificatie de optie Nieuwe app-registratie maken om een app-registratie te maken die uw functie-app vertegenwoordigt.
  8. Geef de app een naam, bijvoorbeeld azure Functions-verificatie-gebeurtenissen-API.
  9. Selecteer Volgende.
  10. Voer in Claims de kenmerken in die u verwacht dat uw aangepaste verificatie-extensie wordt geparseerd vanuit uw REST API en wordt samengevoegd in het token. Voeg de volgende claims toe:
    • dateOfBirth
    • customRoles
    • apiVersion
    • correlationId
  11. Selecteer Volgende en vervolgens Maken, waarmee de aangepaste verificatie-extensie en de bijbehorende toepassingsregistratie worden geregistreerd.
  12. Noteer de app-id onder API-verificatie, die nodig is voor het instellen van omgevingsvariabelen in uw Azure Function-app.

Zodra de aangepaste verificatie-extensie is gemaakt, moet u machtigingen verlenen aan de API. De aangepaste verificatie-extensie gebruikt client_credentials voor verificatie bij de Azure Function-app met behulp van de Receive custom authentication extension HTTP requests machtiging.

  1. Open de pagina Overzicht van de nieuwe aangepaste verificatie-extensie. Noteer de app-id onder API-verificatie, omdat deze nodig is bij het toevoegen van een id-provider.

  2. Selecteer Onder API-verificatie de optie Machtiging verlenen.

  3. Er wordt een nieuw venster geopend en nadat u zich hebt aangemeld, worden machtigingen aangevraagd voor het ontvangen van HTTP-aanvragen voor aangepaste verificatie-extensies. Hierdoor kan de aangepaste verificatie-extensie worden geverifieerd bij uw API. Selecteer Accepteren.

    Schermopname van hoe beheerderstoestemming verlenen.

Stap 2: een OpenID-Verbinding maken-app configureren om verrijkte tokens te ontvangen

Als u een token wilt ophalen en de aangepaste verificatie-extensie wilt testen, kunt u de https://jwt.ms app gebruiken. Het is een webtoepassing van Microsoft die de gedecodeerde inhoud van een token weergeeft (de inhoud van het token verlaat uw browser nooit).

2.1 Een testwebtoepassing registreren

Volg deze stappen om de jwt.ms-webtoepassing te registreren:

  1. Selecteer Microsoft Entra ID op de startpagina in Azure Portal.

  2. Selecteer App-registraties> Nieuwe registratie.

  3. Voer een naam in voor de toepassing. Bijvoorbeeld mijn testtoepassing.

  4. Onder Ondersteunde accounttypen selecteert u Enkel accounts in deze organisatieadreslijst.

  5. Selecteer web in de vervolgkeuzelijst Een platform selecteren in de omleidings-URI en voer https://jwt.ms het tekstvak URL in.

  6. Selecteer Registreren om de app-registratie te voltooien.

    Schermopname van het selecteren van het ondersteunde accounttype en de omleidings-URI.

  7. Kopieer op de pagina Overzicht van uw app-registratie de toepassings-id (client). De app-id wordt in latere stappen aangeduid als de {App_to_enrich_ID} id. In Microsoft Graph wordt ernaar verwezen door de eigenschap appId .

    Schermopname van het kopiëren van de toepassings-id.

2.2 Impliciete stroom inschakelen

De jwt.ms testtoepassing maakt gebruik van de impliciete stroom. Impliciete stroom inschakelen in de registratie van mijn testtoepassing :

  1. Selecteer Verificatie onder Beheren.
  2. Schakel onder Impliciete toekenning en hybride stromen het selectievakje ID-tokens (gebruikt voor impliciete en hybride stromen) in.
  3. Selecteer Opslaan.

2.3 Uw app inschakelen voor een claimtoewijzingsbeleid

Er wordt een claimtoewijzingsbeleid gebruikt om te selecteren welke kenmerken die worden geretourneerd uit de aangepaste verificatie-extensie worden toegewezen aan het token. Als u wilt toestaan dat tokens worden uitgebreid, moet u de registratie van de toepassing expliciet inschakelen om toegewezen claims te accepteren:

  1. Selecteer Manifest in de registratie van mijn testtoepassing onder Beheren.
  2. Zoek in het manifest het acceptMappedClaims kenmerk en stel de waarde in op true.
  3. Stel de accessTokenAcceptedVersion in op 2.
  4. Als u de wijzigingen wilt opslaan, selecteert u Opslaan.

Het volgende JSON-fragment laat zien hoe u deze eigenschappen configureert.

{
	"id": "22222222-0000-0000-0000-000000000000",
	"acceptMappedClaims": true,
	"accessTokenAcceptedVersion": 2,  
    ...
}

Waarschuwing

Stel eigenschap acceptMappedClaims niet in op true voor apps met meerdere tenants. Hierdoor kunnen kwaadwillende actoren claimtoewijzingsbeleid voor uw toepassingen maken. Configureer in plaats daarvan een aangepaste ondertekeningssleutel.

Ga door naar de volgende stap, wijs een aangepaste claimprovider toe aan uw app.

Stap 3: Een aangepaste claimprovider toewijzen aan uw app

Als u tokens wilt uitgeven met claims die binnenkomen vanuit de aangepaste verificatie-extensie, moet u een aangepaste claimprovider toewijzen aan uw toepassing. Dit is gebaseerd op de tokendoelgroep, dus de provider moet worden toegewezen aan de clienttoepassing om claims te ontvangen in een id-token en aan de resourcetoepassing om claims in een toegangstoken te ontvangen. De aangepaste claimprovider is afhankelijk van de aangepaste verificatie-extensie die is geconfigureerd met de startgebeurtenislistener voor tokenuitgifte. U kunt kiezen of alle claims of een subset claims van de aangepaste claimprovider zijn toegewezen aan het token.

Notitie

U kunt slechts 250 unieke toewijzingen maken tussen toepassingen en aangepaste extensies. Als u dezelfde aangepaste extensieaanroep wilt toepassen op meerdere apps, raden we u aan om verificatieEventListeners Microsoft Graph API te gebruiken om listeners voor meerdere toepassingen te maken. Dit wordt niet ondersteund in Azure Portal.

Volg deze stappen om de toepassing Mijn test te verbinden met uw aangepaste verificatie-extensie:

De aangepaste verificatie-extensie toewijzen als een bron van een aangepaste claimprovider;

  1. Selecteer Microsoft Entra ID op de startpagina in Azure Portal.

  2. SelecteerBedrijfstoepassingen en selecteer vervolgens onder Beheren alle toepassingen. Zoek en selecteer Mijn testtoepassing in de lijst.

  3. Ga op de overzichtspagina van mijn testtoepassing naar Beheren en selecteer Eenmalige aanmelding.

  4. Selecteer Bewerken onder Kenmerken en claims.

    Schermopname van het configureren van app-claims.

  5. Vouw het menu Geavanceerde instellingen uit.

  6. Selecteer Configureren naast aangepaste claimprovider.

  7. Vouw de vervolgkeuzelijst Aangepaste claimprovider uit en selecteer de tokenuitgiftegebeurtenis die u eerder hebt gemaakt.

  8. Selecteer Opslaan.

Wijs vervolgens de kenmerken van de aangepaste claimprovider toe, die als claims in het token moeten worden uitgegeven:

  1. Selecteer Nieuwe claim toevoegen om een nieuwe claim toe te voegen. Geef een naam op voor de claim die u wilt uitgeven, bijvoorbeeld dateOfBirth.

  2. Selecteer onder Bron kenmerk en kies customClaimsProvider.dateOfBirth in de vervolgkeuzelijst Bronkenmerk.

    Schermopname van het toevoegen van een claimtoewijzing aan uw app.

  3. Selecteer Opslaan.

  4. Herhaal dit proces om de kenmerken customClaimsProvider.customRoles, customClaimsProvider.apiVersion en customClaimsProvider.correlationId en de bijbehorende naam toe te voegen. Het is een goed idee om de naam van de claim te koppelen aan de naam van het kenmerk.

Stap 4: Uw Azure-functie beveiligen

De aangepaste verificatie-extensie van Microsoft Entra maakt gebruik van server-naar-serverstroom om een toegangstoken te verkrijgen dat in de HTTP-header naar uw Azure-functie Authorization wordt verzonden. Wanneer u uw functie publiceert naar Azure, met name in een productieomgeving, moet u het token valideren dat is verzonden in de autorisatieheader.

Als u uw Azure-functie wilt beveiligen, volgt u deze stappen om Microsoft Entra-verificatie te integreren, voor het valideren van binnenkomende tokens met de registratie van uw API-toepassingsregistratie voor Azure Functions-verificatie-gebeurtenissen. Kies een van de volgende tabbladen op basis van uw tenanttype.

Notitie

Als de Azure-functie-app wordt gehost in een andere Azure-tenant dan de tenant waarin uw aangepaste verificatie-extensie is geregistreerd, kiest u het tabblad Open ID Verbinding maken.

4.1 Microsoft Entra-id-provider gebruiken

Gebruik de volgende stappen om Microsoft Entra toe te voegen als id-provider aan uw Azure Function-app.

  1. Zoek en selecteer in Azure Portal de functie-app die u eerder hebt gepubliceerd.

  2. Selecteer Verificatie onder Instellingen.

  3. Selecteer Id-provider toevoegen.

  4. Selecteer Microsoft als id-provider.

  5. Selecteer Workforce als tenanttype.

  6. Selecteer onder App-registratie een bestaande app-registratie in deze map voor het app-registratietype en kies de API-app-registratie van Azure Functions-verificatie-gebeurtenissen die u eerder hebt gemaakt bij het registreren van de aangepaste claimprovider.

  7. Voer de volgende URL van de verlener in, https://login.microsoftonline.com/{tenantId}/v2.0waar {tenantId} is de tenant-id van uw personeelstenant.

  8. Selecteer onder Niet-geverifieerde aanvragen HTTP 401 Niet geautoriseerd als id-provider.

  9. Hef de selectie van de tokenopslagoptie op.

  10. Selecteer Toevoegen om verificatie toe te voegen aan uw Azure-functie.

    Schermopname die laat zien hoe u verificatie toevoegt aan uw functie-app in een personeelstenant.

4.2 OpenID Verbinding maken id-provider gebruiken

Als u de Microsoft-id-provider hebt geconfigureerd, slaat u deze stap over. Als de Azure-functie wordt gehost onder een andere tenant dan de tenant waarin uw aangepaste verificatie-extensie is geregistreerd, volgt u deze stappen om uw functie te beveiligen:

Een clientgeheim maken

  1. Selecteer Microsoft Entra ID> op de startpagina van Azure Portal App-registraties.
  2. Selecteer de API-app-registratie van azure Functions-verificatie-gebeurtenissen die u eerder hebt gemaakt.
  3. Selecteer Certificaten en geheimen Clientgeheimen>>Nieuw clientgeheim.
  4. Selecteer een vervaldatum voor het geheim of geef een aangepaste levensduur op, voeg een beschrijving toe en selecteer Toevoegen.
  5. Noteer de waarde van het geheim voor gebruik in uw clienttoepassingscode. Deze geheimwaarde wordt nooit meer weergegeven nadat u deze pagina hebt verlaten.

Voeg de OpenID Verbinding maken id-provider toe aan uw Azure Function-app.

  1. Zoek en selecteer de functie-app die u eerder hebt gepubliceerd.

  2. Selecteer Verificatie onder Instellingen.

  3. Selecteer Id-provider toevoegen.

  4. Selecteer OpenID Verbinding maken als id-provider.

  5. Geef een naam op, zoals Contoso Microsoft Entra ID.

  6. Voer onder de vermelding Metagegevens de volgende URL in naar de document-URL. Vervang de {tenantId} door uw Microsoft Entra-tenant-id.

    https://login.microsoftonline.com/{tenantId}/v2.0/.well-known/openid-configuration
    
  7. Voer onder de app-registratie de toepassings-id (client-id) in van de API-app-registratie van Azure Functions-verificatie-gebeurtenissen die u eerder hebt gemaakt.

  8. Ga terug naar de Azure-functie, onder de app-registratie, voer het clientgeheim in.

  9. Hef de selectie van de tokenopslagoptie op.

  10. Selecteer Toevoegen om de OpenID-Verbinding maken id-provider toe te voegen.

Stap 5: De toepassing testen

Voer de volgende stappen uit om uw aangepaste claimprovider te testen:

  1. Open een nieuwe privébrowser en navigeer en meld u aan via de volgende URL.

    https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/authorize?client_id={App_to_enrich_ID}&response_type=id_token&redirect_uri=https://jwt.ms&scope=openid&state=12345&nonce=12345
    
  2. Vervang door {tenantId} uw tenant-id, tenantnaam of een van uw geverifieerde domeinnamen. Bijvoorbeeld: contoso.onmicrosoft.com.

  3. Vervang door {App_to_enrich_ID} de client-id van mijn testtoepassing .

  4. Nadat u zich hebt aangemeld, krijgt u uw gedecodeerde token te zien op https://jwt.ms. Controleer of de claims van de Azure-functie worden weergegeven in het gedecodeerde token, bijvoorbeeld dateOfBirth.

Zie ook