Criar uma API REST com um evento de início de emissão de token para o Azure Functions (versão prévia)

Artigo
04/12/2024

Este artigo descreve como criar uma API REST com um evento de início de emissão de token usando a biblioteca NuGet Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents. Você cria uma função de gatilho HTTP no Visual Studio e a implanta 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 Azure Functions. Se você não tiver uma conta existente do Azure, inscreva-se para uma avaliação gratuita ou use seus benefícios da Assinatura do Visual Studio ao criar uma conta.
Um locatário do Microsoft Entra ID. Você pode usar um locatário do cliente ou de força de trabalho para este guia de instruções.
O Visual Studio com a carga de trabalho de Desenvolvimento do Azure para Visual Studio configurada.

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 Azure Functions. Se você não tiver uma conta existente do Azure, inscreva-se para uma avaliação gratuita ou use seus benefícios da Assinatura do Visual Studio ao criar uma conta.
Um locatário do Microsoft Entra ID. Você pode usar um locatário do cliente ou de força de trabalho para este guia de instruções.
Visual Studio Code, com a extensão do Azure Functions habilitada.

Criar e compilar o aplicativo de funções do Azure

Nesta etapa, você criará uma API de função de gatilho HTTP usando o Visual Studio, instalará os pacotes NuGet necessários e copiará no código de exemplo. Você criará o projeto e executará a função localmente para extrair a URL da função.

Criar o aplicativo de funções do Azure

Para criar um aplicativo de funções do Azure, siga estas etapas:

Abra o Visual Studio e selecione Criar um projeto.
Pesquise e selecione Azure Functions e selecione Próximo.
Dê um nome ao projeto, como AuthEventsTrigger. É uma boa ideia combinar o nome da solução com o nome do projeto.
Selecione um local para o projeto. Selecione Avançar.
Selecione NET 6.0 (suporte a longo prazo) como a estrutura de destino.
Selecione Gatilho HTTP como o tipo de Função e defina o Nível de autorização como Função. Selecione Criar.

Instalar pacotes Do NuGet e compilar o projeto

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

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

Adicione o código de amostra

A API de função é a origem de declarações extras para o token. Para fins deste artigo, estamos codificando os valores para o aplicativo de amostra. Em produção, efetue fetch de informações sobre o usuário do armazenamento de dados externo.

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

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

Dica

Para fins de desenvolvimento e teste locais, abra local.settings.json e adicione o valor AzureWebJobsStorage e AzureWebJobsSecretStorageType, conforme mostrado no seguinte snippet::

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

Compilar e executar o projeto

O projeto foi criado e o código de exemplo foi adicionado. Agora, compilaremos e executaremos o projeto para extrair a URL da função.

Navegue até Compilar no menu superior e selecione Compilar solução.
Pressione F5 ou selecione AuthEventsTrigger no menu superior para executar a função.
Copie a 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.

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.

No Gerenciador de Soluções, clique com o botão direito do mouse no projeto e selecione Publicar.
Em Destino, selecione Azure e Próximo.
Selecione Aplicativo de Funções do Azure (Windows) para o Destino específico, selecione Aplicativo de Funções do Azure (Windows) e, em seguida, selecione Próximo.
Na Instância do Function, use a lista suspensa Nome da assinatura para selecionar a assinatura na qual o novo aplicativo de funções será criado.
Selecione onde você deseja publicar o novo aplicativo de funções e selecione Criar Novo.

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

Configuração	Valor sugerido	Description
Nome	Nome globalmente exclusivo	Um nome que identifique o novo aplicativo de funções. Os caracteres válidos são `a-z` (não diferencia maiúsculas de minúsculas), `0-9` e `-`.
Assinatura	Sua assinatura	A assinatura na qual este novo aplicativo de funções será criado.
Grupo de Recursos	myResourceGroup	Selecione um grupo de recursos existente ou nomeie um novo no qual você criará seu aplicativo de funções.
Tipo de plano	Consumo (sem servidor)	Plano de hospedagem que define como os recursos são alocados para seu aplicativo de funções.
Localidade	Região preferencial	Selecione uma região perto de você ou perto de outros serviços que suas funções podem acessar.
Armazenamento do Azure	Sua conta de armazenamento	Uma conta de armazenamento do Azure é requerida pelo runtime do Functions. Selecione Novo para configurar uma conta de armazenamento para uso geral.
Application Insights	Default	Um recurso do Azure Monitor. Isso é selecionado automaticamente. Selecione aquele que você deseja usar ou configure um novo.

Aguarde alguns instantes para que seu aplicativo de funções seja implantado. Depois que a janela for fechada, selecione Concluir.
Um novo painel Publicar será aberto. Na parte superior, selecione Publicar. Aguarde alguns minutos para que seu aplicativo de funções seja implantado e apareça no portal do Azure.

Configurar variáveis de ambiente para sua Função do Azure (opcional)

Você pode configurar variáveis de ambiente para o Azure Functions em vez de usar o atributo AuthenticationEventsTrigger para implementar Autenticação e autorização do serviço de aplicativos do Azure App internas. Essas variáveis de ambiente podem ser codificadas no atributo ou configuradas no portal do Azure, mas não em ambos.

Configurar variáveis de ambiente em seu código

Modifique o AuthenticationEventsTrigger, inclua as propriedades AuthorityUrl, AudienceAppId e AuthorizedPartyAppId (opcional), conforme mostrado no snippet abaixo.

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

Configurar variáveis de ambiente no portal do Azure

Entre no portal do Microsoft Azure como, no mínimo, Administrador de Aplicativos ou Administrador de Autenticação.
Navegue até o aplicativo de funções que você criou e, em Configurações, selecione Configuração.

Em Configurações de aplicativo, selecione Nova configuração de aplicativo e adicione as variáveis de ambiente e os valores associados a seguir.

Nome	Valor
AuthenticationEvents__AudienceAppId	ID do aplicativo de extensão de autenticação personalizada
AuthenticationEvents__AuthorityUrl	• Locatário da força de trabalho `https://login.microsoftonline.com/<tenantID>` • locatário externo `https://<mydomain>.ciamlogin.com`
AuthenticationEvents__AuthorizedPartyAppId	`99045fe1-7639-4a75-9d4a-577b6ca3810f`

Selecione Salvar para salvar as configurações do aplicativo.

Dica

A variável de ambiente AuthenticationEvents__AuthorizedPartyAppId é opcional e pode ser usada para fins de desenvolvimento. Não é estritamente necessário para esse cenário.

Criar e compilar o aplicativo de funções do Azure

Nesta etapa, você criará uma API de função de gatilho HTTP usando o Visual Studio Code, instalará os pacotes NuGet necessários e copiará no código de exemplo. Você compilará o projeto e executará a função localmente para extrair a URL da função.

Criar o aplicativo de funções do Azure

Para criar um aplicativo de funções do Azure, siga estas etapas:

Abra o Visual Studio Code.
Selecione o ícone Nova Pasta na janela Explorer e crie uma nova pasta para seu projeto, por exemplo, AuthEventsTrigger.
Selecione o ícone de extensão do Azure no lado esquerdo da tela. Entre em sua conta do Azure se ainda não tiver feito isso.
Na barra Workspace, selecione o ícone do Azure Functions>Criar Novo Projeto.
Na barra superior, selecione o local para criar o projeto.
Selecione C# como a linguagem e .NET 6.0 LTS como o tempo de execução do .NET.
Selecione gatilho HTTP como o modelo.
Forneça um nome para o projeto, como AuthEventsTrigger.
Aceite Company.Function como o namespace, com AccessRights definido como Function.

Instalar pacotes Do NuGet e compilar o projeto

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

Abra o Terminal no Visual Studio Code e navegue até a pasta do projeto.
Insira o comando a seguir no console para instalar o pacote NuGet Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents.
```
dotnet add package Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents --prerelease
```

Adicione o código de amostra

Substitua todo o conteúdo do arquivo AuthEventsTrigger.cs pelo seguinte código:

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

Dica

Para fins de desenvolvimento e teste locais, abra local.settings.json e adicione o valor AzureWebJobsStorage e AzureWebJobsSecretStorageType, conforme mostrado no seguinte snippet::

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

Compilar e executar o projeto

No menu superior, selecione Executar>Iniciar depuração ou pressione F5 para executar a função.
No terminal, copie a URL da função exibida. Isso pode ser usado ao configurar uma extensão de autenticação personalizada.

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.

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

Configurar variáveis de ambiente para sua Função do Azure (opcional)

Configurar variáveis de ambiente em seu código

Modifique o AuthenticationEventsTrigger, inclua as propriedades AuthorityUrl, AudienceAppId e AuthorizedPartyAppId (opcional), conforme mostrado no snippet abaixo.

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

Configurar variáveis de ambiente no portal do Azure

Entre no portal do Microsoft Azure como, no mínimo, Administrador de Aplicativos ou Administrador de Autenticação.
Navegue até o aplicativo de funções que você criou e, em Configurações, selecione Configuração.

Em Configurações de aplicativo, selecione Nova configuração de aplicativo e adicione as variáveis de ambiente e os valores associados a seguir.

Nome	Valor
AuthenticationEvents__AudienceAppId	ID do aplicativo de extensão de autenticação personalizada
AuthenticationEvents__AuthorityUrl	• Locatário da força de trabalho `https://login.microsoftonline.com/<tenantID>` • locatário externo `https://<mydomain>.ciamlogin.com`
AuthenticationEvents__AuthorizedPartyAppId	`99045fe1-7639-4a75-9d4a-577b6ca3810f`

Selecione Salvar para salvar as configurações do aplicativo.

Dica

A variável de ambiente AuthenticationEvents__AuthorizedPartyAppId é opcional e pode ser usada para fins de desenvolvimento. Não é estritamente necessário para esse cenário.

Próxima etapa

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

Share via

Criar uma API REST com um evento de início de emissão de token para o Azure Functions (versão prévia)

Pré-requisitos

Pré-requisitos

Criar e compilar o aplicativo de funções do Azure

Criar o aplicativo de funções do Azure

Instalar pacotes Do NuGet e compilar o projeto

Adicione o código de amostra

Compilar e executar o projeto

Implantar a função e publicar no Azure

Configurar variáveis de ambiente para sua Função do Azure (opcional)

Configurar variáveis de ambiente em seu código

Configurar variáveis de ambiente no portal do Azure

Criar e compilar o aplicativo de funções do Azure

Criar o aplicativo de funções do Azure

Instalar pacotes Do NuGet e compilar o projeto

Adicione o código de amostra

Compilar e executar o projeto

Implantar a função e publicar no Azure

Configurar variáveis de ambiente para sua Função do Azure (opcional)

Configurar variáveis de ambiente em seu código

Configurar variáveis de ambiente no portal do Azure

Próxima etapa

Recursos adicionais