Delen via

Trigger voor verificatie gebeurtenissen voor Azure Functions clientbibliotheek voor Node

  • Artikel

Verificatiegebeurtenistrigger voor Azure Functions verwerkt alle back-endverwerking (bijvoorbeeld validatie van token/json-schema) voor binnenkomende HTTP-aanvragen voor verificatiegebeurtenissen. En biedt de ontwikkelaar een sterk getypt objectmodel met een versie om mee te werken, wat betekent dat de ontwikkelaar geen voorafgaande kennis hoeft te hebben van de JSON-nettoladingen voor aanvragen en antwoorden.

Dit projectframework biedt de volgende functies:

  • Tokenvalidatie voor het beveiligen van de API-aanroep
  • Objectmodel, typen en IDE intellisense
  • Inkomende en uitgaande validatie van de API-aanvraag- en antwoordschema's
  • Versiebeheer
  • Geen standaardcode nodig.

Aan de slag

Installeer het npm-pakket

npm install @azure/functions-authentication-events

Vereisten

De client verifiëren

Wanneer Azure AD verificatie-gebeurtenissenservice uw aangepaste extensie aanroept, wordt er een Authorization header met een Bearer {token}verzonden. Dit token vertegenwoordigt een service-naar-serviceverificatie waarin:

  • De 'resource', ook wel de doelgroep genoemd, is de toepassing die u registreert om uw API te vertegenwoordigen. Dit wordt vertegenwoordigd door de aud claim in het token.
  • De 'client' is een Microsoft-toepassing die de service Azure AD verificatie gebeurtenissen vertegenwoordigt. Het heeft een appId waarde van 99045fe1-7639-4a75-9d4a-577b6ca3810f. Dit wordt vertegenwoordigd door:
    • De azp claim in het token als uw toepassingseigenschap accessTokenAcceptedVersion is ingesteld op 2.
    • De appid claim in het token als de eigenschap van accessTokenAcceptedVersion uw resourcetoepassing is ingesteld op 1 of null.

Er zijn drie benaderingen voor het verwerken van het token. U kunt het gedrag aanpassen met behulp van toepassingsinstellingen zoals hieronder wordt weergegeven of via het bestand local.settings.json in lokale omgevingen.

Tokens valideren met behulp van Azure Functions Azure AD-verificatieintegratie

Wanneer u uw functie in productie uitvoert, wordt het ten zeerste aanbevolen om de integratie van Azure Functions Azure AD verificatie te gebruiken voor het valideren van binnenkomende tokens.

  1. Ga naar het tabblad Verificatie in uw functie-app
  2. Klik op Id-provider toevoegen
  3. Selecteer 'Microsoft' als id-provider
  4. Selecteer 'Geef de details van een bestaande app-registratie op'
  5. Voer de Application ID in van de app die uw API vertegenwoordigt in Azure AD

De verlener en toegestane doelgroep zijn afhankelijk van de accessTokenAcceptedVersion eigenschap van uw toepassing (vindt u in het 'Manifest' van de toepassing).

Als de accessTokenAcceptedVersion eigenschap is ingesteld op 2: 6. Stel de Issuer URL to "https://login.microsoftonline.com/{tenantId}/v2.0" 7. Set an 'Allowed Audience' to the Application ID (appId in')

Als de accessTokenAcceptedVersion eigenschap is ingesteld op 1 of null: 6. Stel de Issuer URL to "https://sts.windows.net/{tenantId}/" 7. Set an 'Allowed Audience' to the Application ID URI (also known asidentifierUri). It should be in the format ofin api://{azureFunctionAppName}.azurewebsites.net/{resourceApiAppId}orapi://{FunctionAppFullyQualifiedDomainName}/{resourceApiAppId} als u een aangepaste domeinnaam gebruikt.

De verificatiegebeurtenistrigger valideert standaard dat de integratie van Azure-functieverificatie is geconfigureerd en controleert of de client in het token is ingesteld op 99045fe1-7639-4a75-9d4a-577b6ca3810f (via de azp claims of appid in het token).

Als u uw API wilt testen op een andere client die niet is Azure AD verificatiegebeurtenisservice, zoals het gebruik van Postman, kunt u een optionele toepassingsinstelling configureren:

  • AuthenticationEvents__CustomCallerAppId : de GUID van de gewenste client. Indien niet opgegeven, 99045fe1-7639-4a75-9d4a-577b6ca3810f wordt ervan uitgegaan.

Laat de trigger het token valideren

In lokale omgevingen of omgevingen die niet worden gehost in de Azure Function-service, kan de trigger de tokenvalidatie uitvoeren. Stel de volgende toepassingsinstellingen in:

  • AuthenticationEvents__TenantId - uw tenant-id
  • AuthenticationEvents__AudienceAppId : dezelfde waarde als 'Toegestane doelgroep' in optie 1.
  • AuthenticationEvents__CustomCallerAppId (optioneel): de GUID van de gewenste client. Indien niet opgegeven, 99045fe1-7639-4a75-9d4a-577b6ca3810f wordt ervan uitgegaan.

Een voorbeeldbestand local.settings.json :

{
  "IsEncrypted": false,
  "Values": {
    "AzureWebJobsStorage": "UseDevelopmentStorage=true",
    "FUNCTIONS_WORKER_RUNTIME": "dotnet",
    "AuthenticationEvents__TenantId": "8615397b-****-****-****-********06c8",
    "AuthenticationEvents__AudienceAppId": "api://46f98993-****-****-****-********0038",
    "AuthenticationEvents__CustomCallerAppId": "46f98993-****-****-****-********0038"
  }
}

Geen tokenvalidatie

Als u het token niet wilt verifiëren tijdens de lokale ontwikkeling, stelt u de volgende toepassingsinstelling in:

  • AuthenticationEvents__BypassTokenValidation : de waarde van true zorgt ervoor dat de trigger niet controleert op een validatie van het token.

Snelstart

  • Visual Studio Code
    • Visual Studio Code starten
    • De terminalopdracht func init . --worker-runtime node uitvoeren via het opdrachtenpalet
    • De terminalopdracht func new uitvoeren via het opdrachtenpalet
    • Volg de aanwijzingen voor het maken van een project
    • De terminalopdracht npm install @azure/functions-authentication-events uitvoeren via het opdrachtenpalet
    • De terminalopdracht npm install uitvoeren via het opdrachtenpalet
    • De terminalopdracht npm run-script build uitvoeren via het opdrachtenpalet
  • Gebruik voor ontwikkelingsdoeleinden tokenvalidatie voor testen:
  • Voeg de AuthenticationEvents__BypassTokenValidation toepassingssleutel toe aan de sectie 'Waarden' in het bestand local.settings.json en stel de waarde in op true. Als u geen local.settings.json-bestand in uw lokale omgeving hebt, maakt u er een in de hoofdmap van uw functie-app.
{
  "IsEncrypted": false,
  "Values": {
    "AzureWebJobsStorage": "UseDevelopmentStorage=true",
    "FUNCTIONS_WORKER_RUNTIME": "node",
    "AuthenticationEvents__BypassTokenValidation": true
  }
}
  • Zodra het project is geladen, kunt u de voorbeeldcode uitvoeren en ziet u dat de toepassing van de Azure-functieontwikkelaar uw eindpunt laadt.

Belangrijkste concepten

De belangrijkste concepten van de Azure .NET SDK vindt u hier

Documentatie

  • Als de functie is gepubliceerd, is er een goed leesmateriaal over logboekregistratie en metrische gegevens die u hier kunt vinden

  • Zie (Link TBD) voor API-documentatie

  • Zodra dit wordt verplaatst naar de preview, zijn er geen wijzigingen die fouten veroorzaken. Dit is net zo eenvoudig als het verwijderen van de nuget-bron die verwijst naar de persoonlijke preview.

Voorbeelden

Ga als volgt te werk om tokenvergroting te testen.

  • Open het project dat in de vorige stap is gemaakt. (Snelstart)
  • Voer de toepassing uit. func host start
  • Zodra de toepassing van de Azure Functions-ontwikkelaar is gestart, kopieert u de luister-URL die wordt weergegeven bij het opstarten van de toepassing.
  • Opmerking: alle verificatiefuncties worden vermeld, in het geval dat er één functielistener is geregistreerd met de naam 'OnTokenIssuanceStart'
  • Uw functie-eindpunt is dan een combinatie van de luister-URL en functie, bijvoorbeeld: "http://localhost:7071/runtime/webhooks/AuthenticationEvents?code=(YOUR_CODE)& function=OnTokenIssuanceStart"
  • Plaats de volgende nettolading met iets als Postman of Fiddler.
  • Stappen voor het gebruik van Postman vindt u (Koppeling TBD)
{
    "type": "microsoft.graph.authenticationEvent.tokenIssuanceStart",
    "source": "/tenants/00000001-0000-0ff1-ce00-000000000000/applications/ef9e995c-efdb-4e76-97a9-8cdfc6e06afc",
    "data": {
        "@odata.type": "microsoft.graph.onTokenIssuanceStartCalloutData",
        "tenantId": "00000001-0000-0ff1-ce00-000000000000",
        "authenticationEventListenerId": "f2390d57-9664-4dde-b625-f0115925e1e2",
        "customAuthenticationExtensionId": "9cc1c1ed-5f04-4fdf-85c0-94a7c6ea819c",
        "authenticationContext": {
            "correlationId": "f4bd1870-b774-4fa5-ba78-e08ac6be14c0",
            "client": {
                "ip": "127.0.0.1",
                "locale": "en-us",
                "market": "en-us"
            },
            "protocol": "OAUTH2.0",
            "clientServicePrincipal": {
                "id": "eedfddb9-304e-4d62-aa83-24700a0bcf0e",
                "appId": "ef9e995c-efdb-4e76-97a9-8cdfc6e06afc",
                "appDisplayName": "",
                "displayName": "Test application"
            },
            "resourceServicePrincipal": {
                "id": "eedfddb9-304e-4d62-aa83-24700a0bcf0e",
                "appId": "ef9e995c-efdb-4e76-97a9-8cdfc6e06afc",
                "appDisplayName": "",
                "displayName": "Test application"
            },
            "user": {
                "companyName": "Evo Sts Test",
                "country": "",
                "id": "69d24544-c420-4721-a4bf-106f2378d9f6",
                "mail": "testadmin@evostsoneboxtest.com",
                "onPremisesSamAccountName": "testadmin",
                "onPremisesSecurityIdentifier": "testadmin",
                "preferredDataLocation": "",
                "userPrincipalName": "testadmin@evostsoneboxtest.com"
            }
        }
    }
}
  • Als het goed is, ziet u dit antwoord:
{
    "data": {
        "@odata.type": "microsoft.graph.onTokenIssuanceStartResponseData",
        "actions": [
            {
                "@odata.type": "ProvideClaimsForToken",
                "claims": [
                    {
                        "DateOfBirth": "01/01/2000"
                    },
                    {
                        "CustomRoles": [
                            "Writer",
                            "Editor"
                        ]
                    }
                ]
            }
        ]
    }
}

Problemen oplossen

  • Visual Studio Code
    • Als u in Visual Studio Code wordt uitgevoerd, krijgt u een foutbericht in de lijn van de lokale Azure Storage-emulator is niet beschikbaar. U kunt de emulator handmatig starten.! (Opmerking: Azure Storage-emulator is nu afgeschaft en de voorgestelde vervanging is Azurite)
    • Als u Visual Studio Code op Mac gebruikt, gebruikt u Azurite
    • Als u de volgende fout ziet in Windows (het is een fout) bij het uitvoeren van het gemaakte project.
    • Dit kan worden opgelost door deze opdracht in PowerShell Set-ExecutionPolicy -ExecutionPolicy Unrestricted -Scope LocalMachine uit te voeren. Meer informatie hierover vindt u hier en hier

Volgende stappen

Raadpleeg deze website voor meer informatie over Azure SDK

Publiceren

  • Volg de instructies hier om uw Azure-toepassing te maken en te publiceren. </azure/azure-functions/functions-develop-vs?tabs=in-process#publish-to-azure>
  • Als u het gepubliceerde eindpunt voor posten wilt bepalen, combineert u het azure-functie-eindpunt dat u hebt gemaakt, routeert u naar de listener en listenercode. De listen-code kunt u vinden door naar uw Azure-functietoepassing te navigeren, App-sleutels te selecteren en de waarde van AuthenticationEvents_extension te kopiëren.
  • Bijvoorbeeld: "https://azureautheventstriggerdemo.azurewebsites.net/runtime/webhooks/AuthenticationEvents?code=(AuthenticationEvents_extension_key)& function=OnTokenIssuanceStart"
  • Zorg ervoor dat uw productieomgeving de juiste toepassingsinstellingen voor tokenverificatie heeft.
  • U kunt de gepubliceerde functie opnieuw testen door de bovenstaande nettolading op het nieuwe eindpunt te posten.

Bijdragen

Zie de handleiding voor bijdragen voor meer informatie over het bijdragen aan deze opslagplaats.

Wij verwelkomen bijdragen en suggesties voor dit project. Voor de meeste bijdragen moet u instemmen met een licentieovereenkomst voor bijdragers (CLA: Contributor License Agreement) waarin u verklaart dat u gerechtigd bent ons het recht te geven uw bijdrage te gebruiken, en dat u dit ook doet. Ga naar https://cla.microsoft.com voor meer informatie.

Wanneer u een pull-aanvraag indient, wordt met een CLA-bot automatisch bepaald of u een CLA moet verschaffen en wordt de pull-aanvraag dienovereenkomstig opgemaakt (bijvoorbeeld met een label of commentaar). Volg gewoon de instructies van de bot. U hoeft dit slechts één keer te doen voor alle opslagplaatsen met behulp van onze CLA.

Op dit project is de Microsoft Open Source Code of Conduct (Microsoft Open Source-gedragscode) van toepassing. Zie de Veelgestelde vragen over de gedragscode voor meer informatie of neem contact op opencode@microsoft.com met eventuele aanvullende vragen of opmerkingen.