Condividi tramite

Trigger degli eventi di autenticazione per Funzioni di Azure libreria client per Node

  • Articolo

Authentication Event Trigger for Funzioni di Azure gestisce tutte le elaborazioni back-end, ad esempio la convalida dello schema token/json, per le richieste HTTP in ingresso per gli eventi di autenticazione. Fornisce allo sviluppatore un modello a oggetti fortemente tipizzato e con controllo delle versioni da usare, ovvero lo sviluppatore non deve avere alcuna conoscenza preliminare dei payload JSON di richiesta e risposta.

Questo framework di progetto offre le funzionalità seguenti:

  • Convalida dei token per la protezione della chiamata API
  • Modello a oggetti, digitazione e intellisense dell'IDE
  • Convalida in ingresso e in uscita degli schemi di richiesta e risposta dell'API
  • Controllo delle versioni
  • Nessuna necessità di codice boilerplate.

Guida introduttiva

Installare il pacchetto npm

npm install @azure/functions-authentication-events

Prerequisiti

Autenticare il client

Quando il servizio eventi di autenticazione di Azure AD chiama l'estensione personalizzata, invierà un'intestazione Authorization con .Bearer {token} Questo token rappresenta un servizio per l'autenticazione del servizio in cui:

  • La "risorsa", nota anche come destinatari, è l'applicazione registrata per rappresentare l'API. Questa operazione è rappresentata dall'attestazione aud nel token.
  • Il "client" è un'applicazione Microsoft che rappresenta il servizio eventi di autenticazione di Azure AD. Ha un appId valore di 99045fe1-7639-4a75-9d4a-577b6ca3810f. Questo è rappresentato da:
    • Attestazione azp nel token se la proprietà dell'applicazione accessTokenAcceptedVersion è impostata su 2.
    • Attestazione appid nel token se la proprietà dell'applicazione della accessTokenAcceptedVersion risorsa è impostata su 1 o null.

Esistono tre approcci per gestire il token. È possibile personalizzare il comportamento usando le impostazioni dell'applicazione , come illustrato di seguito o tramite il file local.settings.json negli ambienti locali.

Convalidare i token usando Funzioni di Azure'integrazione dell'autenticazione di Azure AD

Quando si esegue la funzione nell'ambiente di produzione, è consigliabile usare l'integrazione dell'autenticazione di Azure AD Funzioni di Azure per convalidare i token in ingresso.

  1. Passare alla scheda "Autenticazione" nell'app per le funzioni
  2. Fare clic su "Aggiungi provider di identità"
  3. Selezionare "Microsoft" come provider di identità
  4. Selezionare "Specificare i dettagli di una registrazione dell'app esistente"
  5. Immettere l'oggetto dell'app che rappresenta l'API Application ID in Azure AD

L'autorità emittente e il gruppo di destinatari consentiti dipendono dalla accessTokenAcceptedVersion proprietà dell'applicazione (è disponibile nel "Manifesto" dell'applicazione).

Se la accessTokenAcceptedVersion proprietà è impostata su 2: 6. Impostare appId Issuer URL to "https://login.microsoftonline.com/{tenantId}/v2.0" 7. Set an 'Allowed Audience' to the Application ID (')

Se la accessTokenAcceptedVersion proprietà è impostata su 1 o null: 6. Impostare identifierUri Issuer URL to "https://sts.windows.net/{tenantId}/" 7. Set an 'Allowed Audience' to the Application ID URI (also known as). It should be in the format ofapi://{azureFunctionAppName}.azurewebsites.net/{resourceApiAppId}orapi://{FunctionAppFullyQualifiedDomainName}/{resourceApiAppId}' se si usa un nome di dominio personalizzato.

Per impostazione predefinita, il trigger dell'evento di autenticazione convaliderà che l'integrazione dell'autenticazione della funzione di Azure sia configurata e verificherà che il client nel token sia impostato 99045fe1-7639-4a75-9d4a-577b6ca3810f su (tramite le azp attestazioni o appid nel token).

Se si vuole testare l'API su un altro client che non è servizio eventi di autenticazione di Azure AD, ad esempio l'uso di Postman, è possibile configurare un'impostazione dell'applicazione facoltativa :

  • AuthenticationEvents__CustomCallerAppId : guid del client desiderato. Se non specificato, 99045fe1-7639-4a75-9d4a-577b6ca3810f si presuppone .

Chiedere al trigger di convalidare il token

In ambienti o ambienti locali non ospitati nel servizio Funzioni di Azure, il trigger può eseguire la convalida del token. Impostare le impostazioni dell'applicazione seguenti:

  • AuthenticationEvents__TenantId - ID tenant
  • AuthenticationEvents__AudienceAppId : lo stesso valore di "Destinatari consentiti" nell'opzione 1.
  • AuthenticationEvents__CustomCallerAppId (facoltativo): guid del client desiderato. Se non specificato, 99045fe1-7639-4a75-9d4a-577b6ca3810f si presuppone .

Un file di esempio 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"
  }
}

Nessuna convalida dei token

Se si vuole non autenticare il token durante lo sviluppo locale, impostare l'impostazione dell'applicazione seguente:

  • AuthenticationEvents__BypassTokenValidation : il valore di true fa sì che il trigger non controlli la convalida del token.

Avvio rapido

  • Visual Studio Code
    • Avviare Visual Studio Code
    • Eseguire il comando func init . --worker-runtime node del terminale tramite il riquadro comandi
    • Eseguire il comando func new del terminale tramite il riquadro comandi
    • Seguire le istruzioni di creazione del progetto
    • Eseguire il comando npm install @azure/functions-authentication-events del terminale tramite il riquadro comandi
    • Eseguire il comando npm install del terminale tramite il riquadro comandi
    • Eseguire il comando npm run-script build del terminale tramite il riquadro comandi
  • A scopo di sviluppo, il turno di convalida dei token per il test:
  • Aggiungere la chiave dell'applicazione AuthenticationEvents__BypassTokenValidation alla sezione "Valori" nel file local.settings.json e impostarla su true. Se non si dispone di un file local.settings.json nell'ambiente locale, crearne uno nella radice dell'app per le funzioni.
{
  "IsEncrypted": false,
  "Values": {
    "AzureWebJobsStorage": "UseDevelopmentStorage=true",
    "FUNCTIONS_WORKER_RUNTIME": "node",
    "AuthenticationEvents__BypassTokenValidation": true
  }
}
  • Dopo aver caricato il progetto, è possibile eseguire il codice di esempio e dovrebbe essere visualizzato il caricamento dell'endpoint dell'applicazione di Funzioni di Azure da parte dello sviluppatore.

Concetti chiave

I concetti chiave di Azure .NET SDK sono disponibili qui

Documentazione

  • Una funzione è stata pubblicata, è disponibile una buona lettura sulla registrazione e sulle metriche disponibili qui

  • Per la documentazione dell'API, vedere (Link TBD)

  • Quando si passa all'anteprima, non verranno apportate modifiche di rilievo e sarebbe semplice quanto rimuovere l'origine nuget che punta all'anteprima privata.

Esempio

Per testare l'aumento dei token, eseguire le operazioni seguenti.

  • Aprire il progetto creato nel passaggio precedente. (Guida introduttiva)
  • Eseguire l'applicazione. func host start
  • Dopo l'avvio dell'applicazione per sviluppatori di funzioni di Azure, copiare l'URL di ascolto visualizzato con l'applicazione viene avviato.
  • Nota: tutte le funzioni di autenticazione sono elencate, nel caso in cui sia presente un listener di funzioni registrato denominato "OnTokenIssuanceStart"
  • L'endpoint della funzione sarà quindi una combinazione dell'URL di ascolto e della funzione, ad esempio: "http://localhost:7071/runtime/webhooks/AuthenticationEvents?code=(YOUR_CODE)& function=OnTokenIssuanceStart"
  • Inserire il payload seguente usando qualcosa come Postman o Fiddler.
  • I passaggi per l'uso di Postman sono disponibili (Link 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"
            }
        }
    }
}
  • Verrà visualizzata questa risposta:
{
    "data": {
        "@odata.type": "microsoft.graph.onTokenIssuanceStartResponseData",
        "actions": [
            {
                "@odata.type": "ProvideClaimsForToken",
                "claims": [
                    {
                        "DateOfBirth": "01/01/2000"
                    },
                    {
                        "CustomRoles": [
                            "Writer",
                            "Editor"
                        ]
                    }
                ]
            }
        ]
    }
}

Risoluzione dei problemi

  • Visual Studio Code
    • Se in esecuzione in Visual Studio Code, viene visualizzato un errore lungo le righe dell'emulatore di archiviazione di Azure locale non disponibile, è possibile avviare l'emulatore manualmente. (Nota: l'emulatore di Archiviazione di Azure è ora deprecato e la sostituzione suggerita è Azurite)
    • Se si usa Visual Studio Code in Mac, usare Azurite
    • Se viene visualizzato l'errore seguente in Windows (si tratta di un bug) quando si tenta di eseguire il progetto creato.
    • Questo problema può essere risolto eseguendo questo comando in PowerShell Set-ExecutionPolicy -ExecutionPolicy Unrestricted -Scope LocalMachine altre informazioni su questo problema sono disponibili qui e qui

Passaggi successivi

Per altre informazioni su Azure SDK, vedere questo sito Web

Pubblica

  • Seguire le istruzioni riportate qui per creare e pubblicare il applicazione Azure. </azure/azure-functions/functions-develop-vs?tabs=in-process#publish-to-azure>
  • Per determinare l'endpoint di pubblicazione pubblicato, combinare l'endpoint della funzione di Azure creato, indirizzare al listener e al codice listener, è possibile trovare il codice di ascolto passando all'applicazione per le funzioni di Azure, selezionando "Chiavi app" e copiando il valore di AuthenticationEvents_extension.
  • Ad esempio: "https://azureautheventstriggerdemo.azurewebsites.net/runtime/webhooks/AuthenticationEvents?code=(AuthenticationEvents_extension_key)& function=OnTokenIssuanceStart"
  • Assicurarsi che l'ambiente di produzione disponga delle impostazioni dell'applicazione corrette per l'autenticazione del token.
  • Ancora una volta è possibile testare la funzione pubblicata pubblicando il payload precedente nel nuovo endpoint.

Contributo

Per informazioni dettagliate sul contributo a questo repository, vedere la guida ai contributi.

In questo progetto sono benvenuti i contributi e i suggerimenti. Per la maggior parte dei contenuti è necessario sottoscrivere un contratto di licenza di collaborazione (CLA, Contributor License Agreement) che stabilisce che l'utente ha il diritto di concedere, e di fatto concede a Microsoft i diritti d'uso del suo contributo. Per informazioni dettagliate, vedere https://cla.microsoft.com.

Quando si invia una richiesta pull, un bot CLA determina automaticamente se è necessario specificare un contratto CLA e completare la richiesta pull in modo appropriato (ad esempio con un'etichetta e un commento). Seguire le istruzioni specificate dal bot. È necessario eseguire questa operazione una sola volta in tutti i repository usando l'interfaccia della riga di comando.

Questo progetto ha adottato il Codice di comportamento di Microsoft per l'open source. Per altre informazioni, vedere Code of Conduct FAQ (Domande frequenti sul Codice di comportamento Open Source di Microsoft) oppure contattare opencode@microsoft.com per eventuali altre domande o commenti.