Creare un'API REST con un evento di avvio del rilascio di token per Funzioni di Azure (anteprima)
Questo articolo descrive come creare un'API REST con un evento di avvio del rilascio di token usando la libreria NuGet Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents . Creare una funzione trigger HTTP in Visual Studio e distribuirla nel portale di Azure, a cui è possibile accedervi tramite Funzioni di Azure.
Prerequisiti
- Conoscenza di base dei concetti trattati in Panoramica delle estensioni di autenticazione personalizzate.
- Una sottoscrizione di Azure con la possibilità di creare Funzioni di Azure. Se non si ha un account Azure esistente, iscriversi per ottenere una versione di valutazione gratuita o usare i vantaggi della sottoscrizione di Visual Studio quando si crea un account.
- Tenant di Microsoft Entra ID. È possibile usare un tenant del cliente o della forza lavoro per questa guida pratica.
- Visual Studio con il carico di lavoro Sviluppo di Azure per Visual Studio configurato.
Questo articolo descrive come creare un'API REST con un evento di avvio del rilascio di token usando la libreria NuGet Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents . Creare una funzione trigger HTTP in Visual Studio e distribuirla nel portale di Azure, a cui è possibile accedervi tramite Funzioni di Azure.
Prerequisiti
- Conoscenza di base dei concetti trattati in Panoramica delle estensioni di autenticazione personalizzate.
- Una sottoscrizione di Azure con la possibilità di creare Funzioni di Azure. Se non si ha un account Azure esistente, iscriversi per ottenere una versione di valutazione gratuita o usare i vantaggi della sottoscrizione di Visual Studio quando si crea un account.
- Tenant di Microsoft Entra ID. È possibile usare un tenant del cliente o della forza lavoro per questa guida pratica.
- Visual Studio Code, con l'estensione Funzioni di Azure abilitata.
Creare e compilare l'app per le funzioni di Azure
In questo passaggio si crea un'API della funzione trigger HTTP usando Visual Studio, si installano i pacchetti NuGet necessari e si copiano nel codice di esempio. Compilare il progetto ed eseguire la funzione in locale per estrarre l'URL della funzione.
Creare l'app per le funzioni di Azure
Per creare un'app per le funzioni di Azure, seguire questa procedura:
- Aprire Visual Studio e selezionare Crea un nuovo progetto.
- Cercare e selezionare Funzioni di Azure, quindi selezionare Avanti.
- Assegnare un nome al progetto, ad esempio AuthEventsTrigger. È consigliabile trovare una corrispondenza con il nome della soluzione con il nome del progetto.
- Selezionare una località per il progetto. Selezionare Avanti.
- Selezionare .NET 6.0 (supporto a lungo termine) come framework di destinazione.
- Selezionare Trigger HTTP come tipo di funzione e il livello di autorizzazione è impostato su Funzione. Seleziona Crea.
Installare pacchetti NuGet e compilare il progetto
Dopo aver creato il progetto, è necessario installare i pacchetti NuGet necessari e compilare il progetto.
- Nel menu in alto di Visual Studio selezionare Progetto, quindi Gestisci pacchetti NuGet.
- Selezionare la scheda Sfoglia , quindi cercare e selezionare Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents. Nel riquadro destro selezionare Installa.
- Applicare e accettare le modifiche nei popup visualizzati.
Aggiungere il codice di esempio
L'API della funzione è l'origine di attestazioni aggiuntive per il token. Ai fini di questo articolo, vengono hardcodati i valori per l'app di esempio. Nell'ambiente di produzione recuperare informazioni sull'utente dall'archivio dati esterno.
Nel file Function1.cs sostituire l'intero contenuto del file con il codice seguente:
using System;
using System.Threading.Tasks;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Azure.WebJobs;
using Microsoft.Extensions.Logging;
using Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents.TokenIssuanceStart;
using Microsoft.Azure.WebJobs.Extensions.WebJobsAuthenticationEvents;
namespace AuthEventTrigger
{
public static class Function1
{
[FunctionName("onTokenIssuanceStart")]
public static WebJobsAuthenticationEventResponse Run(
// [WebJobsAuthenticationEventsTriggerAttribute] WebJobsTokenIssuanceStartRequest request, ILogger log)
// The WebJobsAuthenticationEventsTriggerAttribute attribute can be used to specify and audience app ID, authority URL and authorized party app id. This is an alternative route to setting up Authorization values instead of Environment variables or EzAuth
[WebJobsAuthenticationEventsTriggerAttribute(AudienceAppId = "Enter custom authentication extension app ID here",
AuthorityUrl = "Enter authority URI here",
AuthorizedPartyAppId = "Enter the Authorized Party App Id here")]WebJobsTokenIssuanceStartRequest request, ILogger log)
{
try
{
// Checks if the request is successful and did the token validation pass
if (request.RequestStatus == RequestStatusType.Successful)
{
// Fetches information about the user from external data store
// Add new claims to the token's response
request.Response.Actions.Add(new WebJobsProvideClaimsForToken(
new WebjobsAuthenticationEventsTokenClaim("dateOfBirth", "01/01/2000"),
new WebjobsAuthenticationEventsTokenClaim("customRoles", "Writer", "Editor"),
new WebjobsAuthenticationEventsTokenClaim("apiVersion", "1.0.0"),
new WebjobsAuthenticationEventsTokenClaim("correlationId", request.Data.AuthenticationContext.CorrelationId.ToString())
));
}
else
{
// If the request fails, such as in token validation, output the failed request status, such as in token validation or response validation.
log.LogInformation(request.StatusMessage);
}
return await request.Completed();
}
catch (Exception ex)
{
return await request.Failed(ex);
}
}
}
}
Suggerimento
Per scopi di sviluppo e test locali, aprire local.settings.json e aggiungere il AzureWebJobsStorage valore e AzureWebJobsSecretStorageType come illustrato nel frammento di codice seguente:
{
"IsEncrypted": false,
"Values": {
"AzureWebJobsStorage": "",
"AzureWebJobsSecretStorageType": "files",
"FUNCTIONS_WORKER_RUNTIME": "dotnet"
}
}
Compilare ed eseguire il progetto
Il progetto è stato creato e il codice di esempio è stato aggiunto. A questo momento si compila ed esegue il progetto per estrarre l'URL della funzione.
- Passare a Compila nel menu in alto e selezionare Compila soluzione.
- Premere F5 o selezionare AuthEventsTrigger dal menu in alto per eseguire la funzione.
- Copiare l'URL della funzione dal terminale che viene visualizzato quando si esegue la funzione. Questa operazione può essere usata durante la configurazione di un'estensione di autenticazione personalizzata.
Distribuire la funzione e pubblicare in Azure
La funzione deve essere distribuita in Azure usando l'IDE. Verificare di aver eseguito correttamente l'accesso all'account Azure in modo che la funzione possa essere pubblicata.
Nella Esplora soluzioni fare clic con il pulsante destro del mouse sul progetto e scegliere Pubblica.
In Destinazione selezionare Azure, quindi selezionare Avanti.
Selezionare App per le funzioni di Azure (Windows) per La destinazione specifica, selezionare App per le funzioni di Azure (Windows) e quindi selezionare Avanti.
Nell'istanza di Function usare l'elenco a discesa Nome sottoscrizione per selezionare la sottoscrizione in cui verrà creata la nuova app per le funzioni.
Selezionare la posizione in cui si vuole pubblicare la nuova app per le funzioni e selezionare Crea nuovo.
Nella pagina App per le funzioni (Windows) usare le impostazioni dell'app per le funzioni come specificato nella tabella seguente, quindi selezionare Crea.
Impostazione Valore suggerito Description Nome Nome globalmente univoco Nome che identifica la nuova app per le funzioni. I caratteri validi sono a-z(senza distinzione tra maiuscole e minuscole),0-9e-.Abbonamento Sottoscrizione in uso Sottoscrizione in cui viene creata la nuova app per le funzioni. Gruppo di risorse myResourceGroup Selezionare un gruppo di risorse esistente o denominarne uno nuovo in cui si creerà l'app per le funzioni. Tipo di piano Consumo (serverless) Piano di hosting che definisce come vengono allocate le risorse all'app per le funzioni. Location Area preferita Selezionare un'area vicina o vicina ad altri servizi a cui le funzioni possono accedere. Archiviazione di Azure Account di archiviazione L'account di archiviazione di Azure è necessario per il runtime di Funzioni. Selezionare Nuovo per configurare un account di archiviazione per utilizzo generico. Application Insights Predefinita Funzionalità di Monitoraggio di Azure. Questa opzione è selezionata automaticamente, selezionare quella che si vuole usare o configurare una nuova. Attendere alcuni istanti per la distribuzione dell'app per le funzioni. Al termine della finestra, selezionare Fine.
Verrà aperto un nuovo riquadro Pubblica . Nella parte superiore selezionare Pubblica. Attendere alcuni minuti che l'app per le funzioni venga distribuita e visualizzata nella portale di Azure.
Configurare le variabili di ambiente per la funzione di Azure (facoltativo)
È possibile configurare le variabili di ambiente per il Funzioni di Azure invece di usare l'attributo AuthenticationEventsTrigger per implementare l'autenticazione e l'autorizzazione del servizio app Azure predefinite. Queste variabili di ambiente possono essere hardcoded nell'attributo o configurate nel portale di Azure, ma non entrambe.
Configurare le variabili di ambiente nel codice
Modificare le AuthenticationEventsTriggerAuthorityUrlproprietà , AudienceAppId e AuthorizedPartyAppId (facoltative), come illustrato nel frammento di codice seguente.
[FunctionName("onTokenIssuanceStart")]
public async static Task<AuthenticationEventResponse> Run(
[AuthenticationEventsTrigger(
AudienceAppId = "Enter custom authentication extension app ID here",
AuthorityUrl = "Enter authority URI here", // The .well-known/openid-configuration endpoint is appended to the AuthorityUrl in the SDK
AuthorizedPartyAppId = "Enter the Authorized Party App Id here")] TokenIssuanceStartRequest request, ILogger log)
Configurare le variabili di ambiente nel portale di Azure
Accedere al portale di Azure come almeno un Amministrazione istrator dell'applicazione o un Amministrazione istrator di autenticazione.
Passare all'app per le funzioni creata e in Impostazioni selezionare Configurazione.
In Impostazioni applicazione selezionare Nuova impostazione applicazione e aggiungere le variabili di ambiente seguenti e i valori associati.
Nome Valore AuthenticationEvents__AudienceAppId ID app dell'estensione per l'autenticazione personalizzata AuthenticationEvents__AuthorityUrl • Tenant della forza lavoro https://login.microsoftonline.com/<tenantID>
• tenant esternohttps://<mydomain>.ciamlogin.comAuthenticationEvents__AuthorizedPartyAppId 99045fe1-7639-4a75-9d4a-577b6ca3810fSelezionare Salva per salvare le impostazioni dell'applicazione.
Suggerimento
La variabile di ambiente AuthenticationEvents__AuthorizedPartyAppId è facoltativa e può essere usata a scopo di sviluppo. Non è strettamente necessario per questo scenario.
Creare e compilare l'app per le funzioni di Azure
In questo passaggio si crea un'API della funzione trigger HTTP usando Visual Studio Code, si installano i pacchetti NuGet necessari e si copiano nel codice di esempio. Si compilerà il progetto ed eseguirà la funzione in locale per estrarre l'URL della funzione.
Creare l'app per le funzioni di Azure
Per creare un'app per le funzioni di Azure, seguire questa procedura:
Aprire Visual Studio Code.
Selezionare l'icona Nuova cartella nella finestra Esplora risorse e creare una nuova cartella per il progetto, ad esempio AuthEventsTrigger.
Selezionare l'icona dell'estensione di Azure sul lato sinistro della schermata. Se non è già stato fatto, accedere all'account Azure.
Nella barra Dell'area di lavoro selezionare l'icona >Funzioni di Azure Crea nuovo progetto.
Nella barra superiore selezionare il percorso per creare il progetto.
Selezionare C# come linguaggio e .NET 6.0 LTS come runtime .NET.
Selezionare Trigger HTTP come modello.
Specificare un nome per il progetto, ad esempio AuthEventsTrigger.
Accettare Company.Function come spazio dei nomi, con AccessRights impostato su Function.
Installare pacchetti NuGet e compilare il progetto
Dopo aver creato il progetto, è necessario installare i pacchetti NuGet necessari e compilare il progetto.
Aprire il terminale in Visual Studio Code e passare alla cartella del progetto.
Immettere il comando seguente nella console per installare il pacchetto NuGet Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents .
dotnet add package Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents --prerelease
Aggiungere il codice di esempio
L'API della funzione è l'origine di attestazioni aggiuntive per il token. Ai fini di questo articolo, vengono hardcodati i valori per l'app di esempio. Nell'ambiente di produzione recuperare informazioni sull'utente dall'archivio dati esterno.
Sostituire l'intero contenuto del file AuthEventsTrigger.cs con il codice seguente:
using System;
using System.Threading.Tasks;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Azure.WebJobs;
using Microsoft.Extensions.Logging;
using Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents.TokenIssuanceStart;
using Microsoft.Azure.WebJobs.Extensions.WebJobsAuthenticationEvents;
namespace AuthEventTrigger
{
public static class Function1
{
[FunctionName("onTokenIssuanceStart")]
public static WebJobsAuthenticationEventResponse Run(
// [WebJobsAuthenticationEventsTriggerAttribute] WebJobsTokenIssuanceStartRequest request, ILogger log)
// The WebJobsAuthenticationEventsTriggerAttribute attribute can be used to specify and audience app ID, authority URL and authorized party app id. This is an alternative route to setting up Authorization values instead of Environment variables or EzAuth
[WebJobsAuthenticationEventsTriggerAttribute(AudienceAppId = "Enter custom authentication extension app ID here",
AuthorityUrl = "Enter authority URI here",
AuthorizedPartyAppId = "Enter the Authorized Party App Id here")]WebJobsTokenIssuanceStartRequest request, ILogger log)
{
try
{
// Checks if the request is successful and did the token validation pass
if (request.RequestStatus == RequestStatusType.Successful)
{
// Fetches information about the user from external data store
// Add new claims to the token's response
request.Response.Actions.Add(new WebJobsProvideClaimsForToken(
new WebjobsAuthenticationEventsTokenClaim("dateOfBirth", "01/01/2000"),
new WebjobsAuthenticationEventsTokenClaim("customRoles", "Writer", "Editor"),
new WebjobsAuthenticationEventsTokenClaim("apiVersion", "1.0.0"),
new WebjobsAuthenticationEventsTokenClaim("correlationId", request.Data.AuthenticationContext.CorrelationId.ToString())
));
}
else
{
// If the request fails, such as in token validation, output the failed request status, such as in token validation or response validation.
log.LogInformation(request.StatusMessage);
}
return await request.Completed();
}
catch (Exception ex)
{
return await request.Failed(ex);
}
}
}
}
Suggerimento
Per scopi di sviluppo e test locali, aprire local.settings.json e aggiungere il AzureWebJobsStorage valore e AzureWebJobsSecretStorageType come illustrato nel frammento di codice seguente:
{
"IsEncrypted": false,
"Values": {
"AzureWebJobsStorage": "",
"AzureWebJobsSecretStorageType": "files",
"FUNCTIONS_WORKER_RUNTIME": "dotnet"
}
}
Compilare ed eseguire il progetto
- Nel menu in alto selezionare Esegui>debug start o premere F5 per eseguire la funzione.
- Nel terminale copiare l'URL della funzione visualizzato. Questa operazione può essere usata durante la configurazione di un'estensione di autenticazione personalizzata.
Distribuire la funzione e pubblicare in Azure
La funzione deve essere distribuita in Azure usando l'IDE. Verificare di aver eseguito correttamente l'accesso all'account Azure in modo che la funzione possa essere pubblicata.
- Selezionare l'icona dell'estensione di Azure . In Risorse selezionare l'icona + Crea una risorsa.
- Selezionare Crea app per le funzioni in Azure. Usare le impostazioni seguenti per configurare l'app per le funzioni.
- Assegnare all'app per le funzioni un nome, ad esempio AuthEventsTriggerNuGet, e premere INVIO.
- Selezionare lo stack di runtime in-process di .NET 6 (LTS).
- Selezionare una posizione per l'app per le funzioni, ad esempio Stati Uniti orientali.
- Attendere alcuni minuti che l'app per le funzioni venga distribuita e visualizzata nella portale di Azure.
Configurare le variabili di ambiente per la funzione di Azure (facoltativo)
È possibile configurare le variabili di ambiente per il Funzioni di Azure invece di usare l'attributo AuthenticationEventsTrigger per implementare l'autenticazione e l'autorizzazione del servizio app Azure predefinite. Queste variabili di ambiente possono essere hardcoded nell'attributo o configurate nel portale di Azure, ma non entrambe.
Configurare le variabili di ambiente nel codice
Modificare le AuthenticationEventsTriggerAuthorityUrlproprietà , AudienceAppId e AuthorizedPartyAppId (facoltative), come illustrato nel frammento di codice seguente.
[FunctionName("onTokenIssuanceStart")]
public async static Task<AuthenticationEventResponse> Run(
[AuthenticationEventsTrigger(
AudienceAppId = "Enter custom authentication extension app ID here",
AuthorityUrl = "Enter authority URI here", // The .well-known/openid-configuration endpoint is appended to the AuthorityUrl in the SDK
AuthorizedPartyAppId = "Enter the Authorized Party App Id here")] TokenIssuanceStartRequest request, ILogger log)
Configurare le variabili di ambiente nel portale di Azure
Accedere al portale di Azure come almeno un Amministrazione istrator dell'applicazione o un Amministrazione istrator di autenticazione.
Passare all'app per le funzioni creata e in Impostazioni selezionare Configurazione.
In Impostazioni applicazione selezionare Nuova impostazione applicazione e aggiungere le variabili di ambiente seguenti e i valori associati.
Nome Valore AuthenticationEvents__AudienceAppId ID app dell'estensione per l'autenticazione personalizzata AuthenticationEvents__AuthorityUrl • Tenant della forza lavoro https://login.microsoftonline.com/<tenantID>
• tenant esternohttps://<mydomain>.ciamlogin.comAuthenticationEvents__AuthorizedPartyAppId 99045fe1-7639-4a75-9d4a-577b6ca3810fSelezionare Salva per salvare le impostazioni dell'applicazione.
Suggerimento
La variabile di ambiente AuthenticationEvents__AuthorizedPartyAppId è facoltativa e può essere usata a scopo di sviluppo. Non è strettamente necessario per questo scenario.