Creare un'API REST per un evento di avvio del rilascio di token in Funzioni di Azure

Questo articolo descrive come creare un'API REST con un evento di avvio del rilascio di token usando Funzioni di Azure nella portale di Azure. Si crea un'app per le funzioni di Azure e una funzione trigger HTTP che può restituire attestazioni aggiuntive per il token.

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.

Questo articolo descrive come creare un'API REST per un evento di avvio del rilascio di token usando la libreria NuGet Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents e impostarla per l'autenticazione. Si creerà una funzione trigger HTTP in Visual Studio o Visual Studio Code, la si configurerà per l'autenticazione e la si distribuirà nel portale di Azure, in 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.
• Una delle configurazioni e gli IDE seguenti:
  • Visual Studio con il carico di lavoro Sviluppo di Azure per Visual Studio configurato.
  • Visual Studio Code, con l'estensione Funzioni di Azure abilitata.

Creare l'app per le funzioni di Azure

Nella portale di Azure creare un'app per le funzioni di Azure e la risorsa associata prima di continuare a creare la funzione trigger HTTP.

1. Accedere al portale di Azure almeno come amministratore dell'applicazione e amministratore dell'autenticazione.

2. Nel menu del portale di Azure o dalla pagina Home selezionare Crea una risorsa.

3. Cercare e selezionare App per le funzioni e selezionare Crea.

4. Nella pagina Informazioni di base creare un'app per le funzioni usando le impostazioni specificate nella tabella seguente:

   Impostazione	Valore suggerito	Descrizione
   Abbonamento	Sottoscrizione in uso	Sottoscrizione in cui verrà creata la nuova app per le funzioni.
   Gruppo di risorse	myResourceGroup	Selezionare e esistente un gruppo di risorse o assegnare un nome al nuovo gruppo di risorse in cui si creerà l'app per le funzioni.
   Nome dell'app per le funzioni	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-9 e -.
   Distribuire codice o immagine del contenitore	Codice	Opzione per la pubblicazione di file di codice o di un contenitore Docker. Per questa esercitazione selezionare Codice.
   Stack di runtime	.NET	Il linguaggio di programmazione preferito. Per questa esercitazione selezionare .NET.
   Versione	6 (LTS) in-process	Versione del runtime .NET. In-process indica che è possibile creare e modificare funzioni nel portale, consigliato per questa guida
   Area	Area preferita	Selezionare un'area vicina a sé o vicina ad altri servizi a cui le funzioni possono accedere.
   Sistema operativo	Windows	Il sistema operativo è pre-selezionato in base alla selezione dello stack di runtime.
   Tipo di piano	Consumo (serverless)	Piano di hosting che definisce come vengono allocate le risorse all'app per le funzioni.

5. Selezionare Rivedi e crea per esaminare le selezioni di configurazione dell'app e quindi selezionare Crea. La distribuzione richiede alcuni minuti.

6. Dopo la distribuzione, selezionare Vai alla risorsa per visualizzare la nuova app per le funzioni.

Creare una funzione trigger HTTP

Dopo aver creato l'app per le funzioni di Azure, creare una funzione trigger HTTP all'interno dell'app. Il trigger HTTP consente di richiamare una funzione con una richiesta HTTP e fa riferimento all'estensione di autenticazione personalizzata Di Microsoft Entra.

1. Nella pagina Panoramica dell'app per le funzioni selezionare il riquadro Funzioni e selezionare Crea funzione in Crea in portale di Azure.
2. Nella finestra Crea funzione lasciare la proprietà Ambiente di sviluppo come Sviluppo nel portale. In Modello selezionare Trigger HTTP.
3. In Dettagli modello immettere CustomAuthenticationExtensionsAPI per la proprietà Nuova funzione.
4. Per Livello di autorizzazione selezionare Funzione.
5. Seleziona Crea.

Modificare la funzione

Il codice legge l'oggetto JSON in ingresso e l'ID Microsoft Entra invia l'oggetto JSON all'API. In questo esempio legge il valore dell'ID di correlazione. Il codice restituisce quindi una raccolta di attestazioni personalizzate, tra cui l'originale CorrelationId, della ApiVersion funzione di Azure, un DateOfBirth oggetto e CustomRoles restituito all'ID Microsoft Entra.

1. Dal menu, in Sviluppo, selezionare Codice e test.

2. Sostituire l'intero codice con il frammento di codice seguente, quindi selezionare Salva.

   #r "Newtonsoft.Json"
   using System.Net;
   using Microsoft.AspNetCore.Mvc;
   using Microsoft.Extensions.Primitives;
   using Newtonsoft.Json;
   public static async Task<IActionResult> Run(HttpRequest req, ILogger log)
   {
       log.LogInformation("C# HTTP trigger function processed a request.");
       string requestBody = await new StreamReader(req.Body).ReadToEndAsync();
       dynamic data = JsonConvert.DeserializeObject(requestBody);
   
       // Read the correlation ID from the Microsoft Entra request    
       string correlationId = data?.data.authenticationContext.correlationId;
   
       // Claims to return to Microsoft Entra
       ResponseContent r = new ResponseContent();
       r.data.actions[0].claims.CorrelationId = correlationId;
       r.data.actions[0].claims.ApiVersion = "1.0.0";
       r.data.actions[0].claims.DateOfBirth = "01/01/2000";
       r.data.actions[0].claims.CustomRoles.Add("Writer");
       r.data.actions[0].claims.CustomRoles.Add("Editor");
       return new OkObjectResult(r);
   }
   public class ResponseContent{
       [JsonProperty("data")]
       public Data data { get; set; }
       public ResponseContent()
       {
           data = new Data();
       }
   }
   public class Data{
       [JsonProperty("@odata.type")]
       public string odatatype { get; set; }
       public List<Action> actions { get; set; }
       public Data()
       {
           odatatype = "microsoft.graph.onTokenIssuanceStartResponseData";
           actions = new List<Action>();
           actions.Add(new Action());
       }
   }
   public class Action{
       [JsonProperty("@odata.type")]
       public string odatatype { get; set; }
       public Claims claims { get; set; }
       public Action()
       {
           odatatype = "microsoft.graph.tokenIssuanceStart.provideClaimsForToken";
           claims = new Claims();
       }
   }
   public class Claims{
       [JsonProperty(NullValueHandling = NullValueHandling.Ignore)]
       public string CorrelationId { get; set; }
       [JsonProperty(NullValueHandling = NullValueHandling.Ignore)]
       public string DateOfBirth { get; set; }
       public string ApiVersion { get; set; }
       public List<string> CustomRoles { get; set; }
       public Claims()
       {
           CustomRoles = new List<string>();
       }
   }
   

3. Nel menu in alto selezionare Recupera URL funzione e copiare il valore dell'URL. Questo URL di funzione può essere usato durante la configurazione di un'estensione di autenticazione personalizzata.

Creare e compilare l'app per le funzioni di Azure

In questo passaggio si crea un'API della funzione trigger HTTP usando l'IDE, si installano i pacchetti NuGet necessari e si copiano nel codice di esempio. Compilare il progetto ed eseguire la funzione per estrarre l'URL della funzione locale.

Creare l'applicazione

Per creare un'app per le funzioni di Azure, seguire questa procedura:

Installare pacchetti NuGet e compilare il progetto

Dopo aver creato il progetto, è necessario installare i pacchetti NuGet necessari e compilare il progetto.

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 è possibile recuperare informazioni sull'utente dall'archivio dati esterno.

Nel file AuthEventsTrigger.cs sostituire l'intero contenuto del file con il codice seguente:

using System;
using Microsoft.Azure.WebJobs;
using Microsoft.Extensions.Logging;
using Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents.TokenIssuanceStart;
using Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents;

namespace AuthEventsTrigger
{
    public static class AuthEventsTrigger
    {
        [FunctionName("onTokenIssuanceStart")]
        public static WebJobsAuthenticationEventResponse Run(
            [WebJobsAuthenticationEventsTrigger] WebJobsTokenIssuanceStartRequest request, ILogger log)
        {
            try
            {
                // Checks if the request is successful and did the token validation pass
                if (request.RequestStatus == WebJobsAuthenticationEventsRequestStatusType.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 request.Completed();
            }
            catch (Exception ex) 
            { 
                return request.Failed(ex);
            }
        }
    }
}

Compilare ed eseguire il progetto in locale

Il progetto è stato creato ed è stato aggiunto il codice di esempio. Usando l'IDE, è necessario compilare ed eseguire il progetto in locale per estrarre l'URL della funzione locale.

Eseguire la funzione in locale (scelta consigliata)

È consigliabile testare la funzione in locale prima di distribuirla in Azure. È possibile usare un corpo JSON fittizio che imita la richiesta inviata da Microsoft Entra ID all'API REST. Usare lo strumento di test api preferito per chiamare direttamente la funzione.

1. Nell'IDE aprire local.settings.json e sostituire il codice con il codice JSON seguente. È possibile impostare su "AuthenticationEvents__BypassTokenValidation" true per scopi di test locali.

   {
     "IsEncrypted": false,
     "Values": {
       "AzureWebJobsStorage": "",
       "AzureWebJobsSecretStorageType": "files",
       "FUNCTIONS_WORKER_RUNTIME": "dotnet",
       "AuthenticationEvents__BypassTokenValidation" : true
     }
   }
   

2. Usando lo strumento di test api preferito, creare una nuova richiesta HTTP e impostare il metodo HTTP su POST.

3. Usare il corpo JSON seguente che imita la richiesta inviata da Microsoft Entra ID all'API REST.

   {
       "type": "microsoft.graph.authenticationEvent.tokenIssuanceStart",
       "source": "/tenants/aaaabbbb-0000-cccc-1111-dddd2222eeee/applications/00001111-aaaa-2222-bbbb-3333cccc4444",
       "data": {
           "@odata.type": "microsoft.graph.onTokenIssuanceStartCalloutData",
           "tenantId": "aaaabbbb-0000-cccc-1111-dddd2222eeee",
           "authenticationEventListenerId": "11112222-bbbb-3333-cccc-4444dddd5555",
           "customAuthenticationExtensionId": "22223333-cccc-4444-dddd-5555eeee6666",
           "authenticationContext": {
               "correlationId": "aaaa0000-bb11-2222-33cc-444444dddddd",
               "client": {
                   "ip": "127.0.0.1",
                   "locale": "en-us",
                   "market": "en-us"
               },
               "protocol": "OAUTH2.0",
               "clientServicePrincipal": {
                   "id": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
                   "appId": "00001111-aaaa-2222-bbbb-3333cccc4444",
                   "appDisplayName": "My Test application",
                   "displayName": "My Test application"
               },
               "resourceServicePrincipal": {
                   "id": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
                   "appId": "00001111-aaaa-2222-bbbb-3333cccc4444",
                   "appDisplayName": "My Test application",
                   "displayName": "My Test application"
               },
               "user": {
                   "companyName": "Casey Jensen",
                   "createdDateTime": "2023-08-16T00:00:00Z",
                   "displayName": "Casey Jensen",
                   "givenName": "Casey",
                   "id": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
                   "mail": "casey@contoso.com",
                   "onPremisesSamAccountName": "Casey Jensen",
                   "onPremisesSecurityIdentifier": "<Enter Security Identifier>",
                   "onPremisesUserPrincipalName": "Casey Jensen",
                   "preferredLanguage": "en-us",
                   "surname": "Jensen",
                   "userPrincipalName": "casey@contoso.com",
                   "userType": "Member"
               }
           }
       }
   }
   
   

4. Selezionare Invia e si dovrebbe ricevere una risposta JSON simile alla seguente:

   {
       "data": {
           "@odata.type": "microsoft.graph.onTokenIssuanceStartResponseData",
           "actions": [
               {
                   "@odata.type": "microsoft.graph.tokenIssuanceStart.provideClaimsForToken",
                   "claims": {
                       "customClaim1": "customClaimValue1",
                       "customClaim2": [
                           "customClaimString1",
                           "customClaimString2" 
                       ]
                   }
               }
   
           ]
       }
   }
   

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.

Configurare l'autenticazione per la funzione di Azure

Esistono tre modi per configurare l'autenticazione per la funzione di Azure:

• Configurare l'autenticazione nel portale di Azure usando le variabili di ambiente (scelta consigliata)
• Configurare l'autenticazione nel codice usando WebJobsAuthenticationEventsTriggerAttribute
• autenticazione e autorizzazione del servizio app Azure

Per impostazione predefinita, il codice è stato configurato per l'autenticazione nel portale di Azure usando le variabili di ambiente. Usare le schede seguenti per selezionare il metodo preferito per implementare le variabili di ambiente o, in alternativa, fare riferimento all'autenticazione e all'autorizzazione predefiniti del servizio app Azure. Per configurare le variabili di ambiente, usare i valori seguenti:

    [FunctionName("onTokenIssuanceStart")]
    public static WebJobsAuthenticationEventResponse Run(
        [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)