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.

Nota

A biblioteca NuGet Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents está atualmente em visualização. As etapas neste artigo estão sujeitas a alterações. Para implementação de disponibilidade geral da implementação de um evento de início de emissão de token, você pode fazer isso usando o portal do Azure.

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 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	6 (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.
   Tipo de plano	Consumo (Sem servidor)	O plano de alojamento que define a forma como os recursos são alocados à sua aplicação de funções.

5. 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.

6. 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, deixe a propriedade Ambiente de desenvolvimento como Desenvolver no portal. Em Modelo, selecione Gatilho HTTP.
3. Em Detalhes do modelo, insira CustomAuthenticationExtensionsAPI para a propriedade New Function .
4. Para o nível de autorização, selecione Função.
5. 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:

Visual Studio

1. Abra o Visual Studio e selecione Criar um novo projeto.
2. Procure e selecione Azure Functions e, em seguida, selecione Seguinte.
3. Dê um nome ao projeto, como AuthEventsTrigger. É uma boa ideia combinar o nome da solução com o nome do projeto.
4. Selecione um local para o projeto. Selecione Seguinte.
5. Selecione .NET 6.0 (Suporte de Longo Prazo) como a estrutura de destino.
6. Selecione Gatilho Http como o tipo de Função e esse nível de Autorização está definido como Função. Selecione Criar.
7. No Gerenciador de Soluções, renomeie o arquivo Function1.cs para AuthEventsTrigger.cs e aceite a sugestão de alteração de nome.

Visual Studio Code

1. Abra o Visual Studio Code.

2. Selecione o ícone Nova pasta na janela Explorer e crie uma nova pasta para seu projeto, por exemplo, AuthEventsTrigger.

3. Selecione o ícone da extensão do Azure no lado esquerdo da tela. Entre na sua conta do Azure, se ainda não o fez.

4. Na barra Espaço de trabalho, selecione o ícone >Criar novo projeto do Azure Functions.

   

5. Na barra superior, selecione o local para criar o projeto.

6. Selecione C# como a linguagem e .NET 6.0 LTS como o tempo de execução do .NET.

7. Selecione Gatilho HTTP como modelo.

8. Forneça um nome para o projeto, como AuthEventsTrigger.

9. Aceite Company.Function como o namespace, com AccessRights definido como Function.

Instale pacotes NuGet e crie o projeto

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

Visual Studio

1. No menu superior do Visual Studio, selecione Projeto e, em seguida, Gerenciar pacotes NuGet.
2. Selecione a guia Procurar e, em seguida, procure e selecione Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents no painel direito. Selecione Instalar.
3. Aplique e aceite as alterações nos pop-ups que aparecem.

Visual Studio Code

1. Abra o Terminal no Visual Studio Code e navegue até a pasta do projeto.

2. Insira o seguinte comando no console para instalar o pacote NuGet Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents.

   dotnet add package Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents
   

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.

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.

Visual Studio

1. Navegue até Build no menu superior e selecione Build Solution.
2. Pressione F5 ou selecione AuthEventsTrigger no menu superior para executar a função.
3. Copie o url da função do terminal que aparece ao executar a função. Isso pode ser usado ao configurar uma extensão de autenticação personalizada.

Visual Studio Code

1. No menu superior, selecione Executar>Iniciar Depuração ou pressione F5 para executar a função.
2. No terminal, copie o url da função que aparece. Isso pode ser usado ao configurar uma extensão de autenticação personalizada.

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.

Visual Studio

1. No Gerenciador de Soluções, clique com o botão direito do mouse no projeto e selecione Publicar.

2. Em Destino, selecione Azure e, em seguida, selecione Avançar.

3. Selecione Aplicativo de Função do Azure (Windows) para o Destino Específico, selecione Aplicativo de Função do Azure (Windows) e selecione Avançar.

4. Na instância Function, use a lista suspensa Nome da assinatura para selecionar a assinatura na qual o novo aplicativo de função será criado.

5. Selecione onde deseja publicar o novo aplicativo de função e selecione Criar novo.

6. Na página Aplicativo de função (Windows), use as configurações do aplicativo de função conforme especificado na tabela a seguir e selecione Criar.

   Definição	Valor sugerido	Description
   Nome	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 -.
   Subscrição	a sua subscrição	A assinatura sob a qual o novo aplicativo de função é criado.
   Grupo de Recursos	myResourceGroup	Selecione um grupo de recursos existente ou nomeie o novo no qual você criará seu aplicativo de função.
   Tipo de plano	Consumo (Sem servidor)	O plano de alojamento que define a forma como os recursos são alocados à sua aplicação de funções.
   Location	Região preferida	Selecione uma região perto de você ou perto de outros serviços que suas funções possam acessar.
   Armazenamento do Azure	A sua conta de armazenamento	O runtime das Funções precisa de uma conta de armazenamento do Azure. Selecione Novo para configurar uma conta de armazenamento de uso geral.
   Application Insights	Predefinição	Um recurso do Azure Monitor. Isso é selecionado automaticamente, selecione o que você deseja usar ou configure um novo.

7. Aguarde alguns instantes até que seu aplicativo de função seja implantado. Quando a janela fechar, selecione Concluir.

8. Um novo painel Publicar é aberto. Na parte superior, selecione Publicar. Aguarde alguns minutos para que seu aplicativo de função seja implantado e apareça no portal do Azure.

Visual Studio Code

1. Selecione o ícone de extensão do Azure . Em Recursos, selecione o + ícone Criar um recurso.
2. Selecione Criar aplicativo de função no Azure. Use as configurações a seguir para configurar seu aplicativo de função.
3. Dê um nome ao aplicativo de função, como AuthEventsTriggerNuGet, e pressione Enter.
4. Selecione a pilha de tempo de execução em processo do .NET 6 (LTS).
5. Selecione um local para o aplicativo de função, como East US.
6. Aguarde alguns minutos para que seu aplicativo de função seja implantado e apareça no portal do Azure.

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:

Nome	Valor
AuthenticationEvents__AudienceAppId	ID do aplicativo de extensão de autenticação personalizada que é configurado em Configurar um provedor de declarações personalizado para um evento de emissão de token
AuthenticationEvents__AuthorityUrl	• Inquilino da força de trabalho https://login.microsoftonline.com/<tenantID> • Inquilino externo https://<mydomain>.ciamlogin.com/<tenantID>
AuthenticationEvents__AuthorizedPartyAppId	99045fe1-7639-4a75-9d4a-577b6ca3810f ou outra parte autorizada

Configurar a autenticação no portal do Azure

Configurar a autenticação no portal do Azure usando variáveis de ambiente

1. Entre no portal do Azure como pelo menos um Administrador de Aplicativo ou Administrador de Autenticação.
2. Navegue até o aplicativo de função que você criou e, em Configurações, selecione Configuração.
3. Em Configurações do aplicativo, selecione Nova configuração do aplicativo e adicione as variáveis de ambiente da tabela e seus valores associados.
4. Selecione Salvar para salvar as configurações do aplicativo.

Configurar a autenticação no seu código

Configure a autenticação em seu código usando WebJobsAuthenticationEventsTriggerAttribute

1. Abra o arquivo AuthEventsTrigger.cs no IDE.
2. Modifique as WebJobsAuthenticationEventsTriggerAttribute propriedades include the AuthorityUrl, AudienceAppId and AuthorizedPartyAppId , conforme mostrado no trecho abaixo.

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

Próximo passo

Configurar um evento de emissão de token do provedor de declarações personalizado