Criar uma API REST para um evento de início de emissão de token no Azure Functions

Este artigo descreve como criar uma API REST com um evento de início de emissão de token usando o Azure Functions no portal do Azure. Você cria um aplicativo Azure Function e uma função de gatilho HTTP que pode retornar declarações extras para seu token.

Pré-requisitos

• Uma compreensão básica dos conceitos abordados em Visão geral das extensões de autenticação personalizadas.
• Uma assinatura do Azure com a capacidade de criar o Azure Functions. Se você não tiver uma conta existente do Azure, inscreva-se para uma avaliação gratuita ou use os benefícios da Assinatura do Visual Studio ao criar uma conta.
• Um locatário do Microsoft Entra ID. Você pode usar um cliente ou locatário da força de trabalho para este guia de instruções.

Este artigo descreve como criar uma API REST para um evento de início de emissão de token usando a biblioteca NuGet Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents e configurá-la para autenticação. Você criará uma função de gatilho HTTP no Visual Studio ou no Visual Studio Code, a configurará para autenticação e a implantará no portal do Azure, onde poderá ser acessada por meio do Azure Functions.

Pré-requisitos

• Uma compreensão básica dos conceitos abordados em Visão geral das extensões de autenticação personalizadas.
• Uma assinatura do Azure com a capacidade de criar o Azure Functions. Se você não tiver uma conta existente do Azure, inscreva-se para uma avaliação gratuita ou use os benefícios da Assinatura do Visual Studio ao criar uma conta.
• Um locatário do Microsoft Entra ID. Você pode usar um cliente ou locatário da força de trabalho para este guia de instruções.
• Um dos seguintes IDEs e configurações:
  • Visual Studio com carga de trabalho de Desenvolvimento do Azure para Visual Studio configurada.
  • Visual Studio Code, com a extensão Azure Functions habilitada.

Criar o aplicativo Azure Function

No portal do Azure, crie um aplicativo Azure Function e seu recurso associado, antes de continuar a criar a função de gatilho HTTP.

1. Entre no portal do Azure como pelo menos um Administrador de Aplicativo e Administrador de Autenticação.

2. A partir do menu do portal do Azure ou a partir da Home page, selecione Criar um recurso.

3. Procure e selecione Função App e selecione Criar.

4. Na página Criar Aplicativo de Função, selecione Consumo e, em seguida, Selecionar.

5. Na página Criar Aplicativo de Função (Consumo), na guia Noções básicas, crie um aplicativo de função usando as configurações especificadas na tabela a seguir:

   Definição	Valor sugerido	Description
   Subscrição	a sua subscrição	A assinatura sob a qual o novo aplicativo de função será criado.
   Grupo de Recursos	myResourceGroup	Selecione o grupo de recursos existente ou o nome do novo no qual você criará seu aplicativo de função.
   Nome da Aplicação de Funções	Nome globalmente exclusivo	Um nome que identifica o novo aplicativo de função. Os carateres válidos são a-z (não sensível a maiúsculas e minúsculas), 0-9 e -.
   Implantar código ou imagem de contêiner	Código	Opção para publicar ficheiros de código ou um contentor de Docker. Para este tutorial, selecione Código.
   Pilha de runtime	.NET	A sua linguagem de programação preferida. Para este tutorial, selecione .NET.
   Versão	8 (LTS) Em processo	Versão do tempo de execução do .NET. Em processo significa que você pode criar e modificar funções no portal, o que é recomendado para este guia
   Região	Região preferida	Selecione uma região perto de você ou perto de outros serviços que suas funções possam acessar.
   Sistema operativo	Windows	O sistema operacional é pré-selecionado para você com base na seleção da pilha de tempo de execução.

   

6. Selecione Rever + criar para rever as seleções de configuração da aplicação e, em seguida, selecione Criar. A implantação leva alguns minutos.

7. Depois de implantado, selecione Ir para o recurso para exibir seu novo aplicativo de função.

Criar uma função de gatilho HTTP

Depois que o aplicativo Azure Function for criado, crie uma função de gatilho HTTP dentro do aplicativo. O gatilho HTTP permite invocar uma função com uma solicitação HTTP e é referenciado pela extensão de autenticação personalizada do Microsoft Entra.

1. Na página Visão geral do seu aplicativo de função, selecione o painel Funções e selecione Criar função em Criar no portal do Azure.
2. Na janela Criar função, selecione o tipo de função de gatilho HTTP e selecione Avançar.
3. Em Detalhes do modelo, insira CustomAuthenticationExtensionsAPI para a propriedade Function name Function e selecione Function como o nível de autorização.
4. Selecione Criar.

Editar a função

O código lê o objeto JSON de entrada e o Microsoft Entra ID envia o objeto JSON para sua API. Neste exemplo, ele lê o valor de ID de correlação. Em seguida, o código retorna uma coleção de declarações personalizadas, incluindo o original CorrelationId, o ApiVersion da sua Função do Azure, a DateOfBirth e CustomRoles que é retornado para o Microsoft Entra ID.

1. No menu, em Desenvolvedor, selecione Código + Teste.

2. Substitua o código inteiro pelo seguinte trecho e selecione Salvar.

   #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. No menu superior, selecione Obter URL da função e copie o valor da URL . Este URL de função pode ser usado ao configurar uma extensão de autenticação personalizada.

Criar e criar o aplicativo Azure Function

Nesta etapa, você cria uma API de função de gatilho HTTP usando seu IDE, instala os pacotes NuGet necessários e copia o código de exemplo. Você cria o projeto e executa a função para extrair a URL da função local.

Criar a aplicação

Para criar um aplicativo Azure Function, siga estas etapas:

Instale pacotes NuGet e crie o projeto

Depois de criar o projeto, você precisará instalar os pacotes NuGet necessários e criar o projeto.

Adicionar o código de exemplo

A função API é a fonte de declarações extras para o seu token. Para os fins deste artigo, estamos codificando os valores para o aplicativo de exemplo. Na produção, você pode buscar informações sobre o usuário no armazenamento de dados externo. Consulte a classe WebJobsAuthenticationEventsContext para propriedades existentes.

No arquivo AuthEventsTrigger.cs , substitua todo o conteúdo do arquivo pelo seguinte código:

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);
            }
        }
    }
}

Construir e executar o projeto localmente

O projeto foi criado e o código de exemplo foi adicionado. Usando seu IDE, precisamos construir e executar o projeto localmente para extrair a URL da função local.

Execute a função localmente (recomendado)

É uma boa ideia testar a função localmente antes de implantá-la no Azure. Podemos usar um corpo JSON fictício que imita a solicitação que o Microsoft Entra ID envia para sua API REST. Use sua ferramenta de teste de API preferida para chamar a função diretamente.

1. No IDE, abra local.settings.json e substitua o código pelo seguinte JSON. Podemos definir "AuthenticationEvents__BypassTokenValidation" para true fins de testes locais.

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

2. Usando sua ferramenta de teste de API preferida, crie uma nova solicitação HTTP e defina o método HTTP como POST.

3. Use o seguinte corpo JSON que imita a solicitação que o ID do Microsoft Entra envia para sua 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. Selecione Enviar e você deve receber uma resposta JSON semelhante à seguinte:

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

Implantar a função e publicar no Azure

A função precisa ser implantada no Azure usando nosso IDE. Verifique se você está conectado corretamente à sua conta do Azure para que a função possa ser publicada.

Configurar a autenticação para sua Função do Azure

Há três maneiras de configurar a autenticação para sua Função do Azure:

• Configurar a autenticação no portal do Azure usando variáveis de ambiente (recomendado)
• Configure a autenticação em seu código usando WebJobsAuthenticationEventsTriggerAttribute
• Autenticação e autorização do Serviço de Aplicativo do Azure

Por padrão, o código foi configurado para autenticação no portal do Azure usando variáveis de ambiente. Use as guias abaixo para selecionar seu método preferido de implementação de variáveis de ambiente ou, alternativamente, consulte a autenticação e autorização internas do Serviço de Aplicativo do Azure. Para configurar variáveis de ambiente, use os seguintes valores:

    [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)