Gatilho de eventos de autenticação para Azure Functions biblioteca de clientes para Nó

  • Artigo

O Gatilho de Evento de Autenticação para Azure Functions manipula todo o processamento de back-end (por exemplo, validação de esquema de token/json) para solicitações Http de entrada para eventos de autenticação. E fornece ao desenvolvedor um modelo de objeto fortemente tipado e com versão para trabalhar, o que significa que o desenvolvedor não precisa ter nenhum conhecimento prévio das cargas json de solicitação e resposta.

Esta estrutura de projeto fornece os seguintes recursos:

  • Validação de token para proteger a chamada à API
  • Modelo de objeto, digitação e intellisense de IDE
  • Validação de entrada e saída dos esquemas de solicitação e resposta da API
  • Controle de versão
  • Não há necessidade de código clichê.

Introdução

instalar o pacote npm

npm install @azure/functions-authentication-events

Pré-requisitos

Autenticar o Cliente

Quando Azure AD serviço de eventos de autenticação chamar sua extensão personalizada, ele enviará um Authorization cabeçalho com um Bearer {token}. Esse token representará um serviço para a autenticação de serviço no qual:

  • O 'recurso', também conhecido como público-alvo, é o aplicativo que você registra para representar sua API. Isso é representado pela declaração aud no token.
  • O 'cliente' é um aplicativo da Microsoft que representa o serviço de eventos de autenticação Azure AD. Ele tem um appId valor de 99045fe1-7639-4a75-9d4a-577b6ca3810f. Isso é representado por:
    • A azp declaração no token se a propriedade do aplicativo accessTokenAcceptedVersion estiver definida como 2.
    • A appid declaração no token se a propriedade do aplicativo de accessTokenAcceptedVersion recurso estiver definida 1 como ou null.

Há três abordagens para lidar com o token. Você pode personalizar o comportamento usando as configurações do aplicativo , conforme mostrado abaixo ou por meio do arquivo local.settings.json em ambientes locais.

Validar tokens usando Azure Functions Azure AD integração de autenticação

Ao executar sua função em produção, é altamente recomendável usar a integração de autenticação Azure Functions Azure AD para validar tokens de entrada.

  1. Vá para a guia "Autenticação" no aplicativo de funções
  2. Clique em "Adicionar provedor de identidade"
  3. Selecione "Microsoft" como o provedor de identidade
  4. Selecione "Fornecer os detalhes de um registro de aplicativo existente"
  5. Insira o Application ID do aplicativo que representa sua API no Azure AD

O emissor e o público permitido dependem da accessTokenAcceptedVersion propriedade do aplicativo (pode ser encontrado no "Manifesto" do aplicativo).

Se a accessTokenAcceptedVersion propriedade estiver definida 2como : 6. Defina a Issuer URL to "https://login.microsoftonline.com/{tenantId}/v2.0" 7. Set an 'Allowed Audience' to the Application ID (appId')

Se a accessTokenAcceptedVersion propriedade estiver definida como 1 ou null: 6. Defina o Issuer URL to "https://sts.windows.net/{tenantId}/" 7. Set an 'Allowed Audience' to the Application ID URI (also known asidentifierUri). It should be in the format ofapi://{azureFunctionAppName}.azurewebsites.net/{resourceApiAppId}orapi://{FunctionAppFullyQualifiedDomainName}/{resourceApiAppId}' se estiver usando um nome de domínio personalizado.

Por padrão, o gatilho de evento de autenticação validará se a integração de autenticação do Azure Function está configurada e marcar que o cliente no token esteja definido 99045fe1-7639-4a75-9d4a-577b6ca3810f como (por meio das azp declarações ou appid no token).

Se você quiser testar sua API em relação a algum outro cliente que não esteja Azure AD serviço de eventos de autenticação, como usar o Postman, poderá definir uma configuração de aplicativo opcional:

  • AuthenticationEvents__CustomCallerAppId - o guid do cliente desejado. Se não for fornecido, 99045fe1-7639-4a75-9d4a-577b6ca3810f será assumido.

Fazer com que o gatilho valide o token

Em ambientes locais ou ambientes que não estão hospedados no serviço do Azure Function, o gatilho pode fazer a validação do token. Defina as seguintes configurações de aplicativo:

  • AuthenticationEvents__TenantId - sua ID de locatário
  • AuthenticationEvents__AudienceAppId - o mesmo valor que "Público permitido" na opção 1.
  • AuthenticationEvents__CustomCallerAppId (opcional) – o guid do cliente desejado. Se não for fornecido, 99045fe1-7639-4a75-9d4a-577b6ca3810f será assumido.

Um arquivo local.settings.json de exemplo:

{
  "IsEncrypted": false,
  "Values": {
    "AzureWebJobsStorage": "UseDevelopmentStorage=true",
    "FUNCTIONS_WORKER_RUNTIME": "dotnet",
    "AuthenticationEvents__TenantId": "8615397b-****-****-****-********06c8",
    "AuthenticationEvents__AudienceAppId": "api://46f98993-****-****-****-********0038",
    "AuthenticationEvents__CustomCallerAppId": "46f98993-****-****-****-********0038"
  }
}

Nenhuma validação de token

Se você quiser não autenticar o token durante o desenvolvimento local, defina a seguinte configuração de aplicativo:

  • AuthenticationEvents__BypassTokenValidation – o valor de true fará com que o gatilho não marcar para uma validação do token.

Início Rápido

  • Visual Studio Code
    • Iniciar o Visual Studio Code
    • Executar o comando func init . --worker-runtime node do terminal por meio da paleta de comandos
    • Executar o comando func new do terminal por meio da paleta de comandos
    • Siga os prompts de criação do projeto
    • Executar o comando npm install @azure/functions-authentication-events do terminal por meio da paleta de comandos
    • Executar o comando npm install do terminal por meio da paleta de comandos
    • Executar o comando npm run-script build do terminal por meio da paleta de comandos
  • Para fins de desenvolvimento, a validação de token para teste:
  • Adicione a chave de aplicativo AuthenticationEvents__BypassTokenValidation à seção "Valores" no arquivo local.settings.json e defina seu valor como true. Se você não tiver um arquivo local.settings.json em seu ambiente local, crie um na raiz do aplicativo de funções.
{
  "IsEncrypted": false,
  "Values": {
    "AzureWebJobsStorage": "UseDevelopmentStorage=true",
    "FUNCTIONS_WORKER_RUNTIME": "node",
    "AuthenticationEvents__BypassTokenValidation": true
  }
}
  • Depois que o projeto for carregado, você poderá executar o código de exemplo e verá o aplicativo do desenvolvedor do Azure Functions carregar seu ponto de extremidade.

Principais conceitos

Os principais conceitos do SDK do .NET do Azure podem ser encontrados aqui

Documentação

  • Uma das funções que a função foi publicada, há uma boa leitura sobre registro em log e métricas que podem ser encontradas aqui

  • Para obter a Documentação da API, consulte o (Link TBD)

  • Depois que isso passar para a versão prévia, não haverá alterações interruptivas e será tão simples quanto remover a origem do nuget que aponta para a visualização privada.

Exemplos

Para testar o aumento do token, faça o seguinte.

  • Abra o projeto que foi criado na etapa anterior. (Início Rápido)
  • Execute o Aplicativo. func host start
  • Depois que o aplicativo do desenvolvedor de funções do Azure for iniciado, copie a URL de escuta exibida com o aplicativo iniciado.
  • Observação: todas as funções de autenticação estão listadas, caso tenhamos um ouvinte de função registrado chamado "OnTokenIssuanceStart"
  • O ponto de extremidade da função será então uma combinação da url de escuta e da função, por exemplo: "http://localhost:7071/runtime/webhooks/AuthenticationEvents?code=(YOUR_CODE)& function=OnTokenIssuanceStart"
  • Poste o conteúdo a seguir usando algo como Postman ou Fiddler.
  • Etapas para usar o Postman podem ser encontradas (Link TBD)
{
    "type": "microsoft.graph.authenticationEvent.tokenIssuanceStart",
    "source": "/tenants/00000001-0000-0ff1-ce00-000000000000/applications/ef9e995c-efdb-4e76-97a9-8cdfc6e06afc",
    "data": {
        "@odata.type": "microsoft.graph.onTokenIssuanceStartCalloutData",
        "tenantId": "00000001-0000-0ff1-ce00-000000000000",
        "authenticationEventListenerId": "f2390d57-9664-4dde-b625-f0115925e1e2",
        "customAuthenticationExtensionId": "9cc1c1ed-5f04-4fdf-85c0-94a7c6ea819c",
        "authenticationContext": {
            "correlationId": "f4bd1870-b774-4fa5-ba78-e08ac6be14c0",
            "client": {
                "ip": "127.0.0.1",
                "locale": "en-us",
                "market": "en-us"
            },
            "protocol": "OAUTH2.0",
            "clientServicePrincipal": {
                "id": "eedfddb9-304e-4d62-aa83-24700a0bcf0e",
                "appId": "ef9e995c-efdb-4e76-97a9-8cdfc6e06afc",
                "appDisplayName": "",
                "displayName": "Test application"
            },
            "resourceServicePrincipal": {
                "id": "eedfddb9-304e-4d62-aa83-24700a0bcf0e",
                "appId": "ef9e995c-efdb-4e76-97a9-8cdfc6e06afc",
                "appDisplayName": "",
                "displayName": "Test application"
            },
            "user": {
                "companyName": "Evo Sts Test",
                "country": "",
                "id": "69d24544-c420-4721-a4bf-106f2378d9f6",
                "mail": "testadmin@evostsoneboxtest.com",
                "onPremisesSamAccountName": "testadmin",
                "onPremisesSecurityIdentifier": "testadmin",
                "preferredDataLocation": "",
                "userPrincipalName": "testadmin@evostsoneboxtest.com"
            }
        }
    }
}
  • Você deve ver esta resposta:
{
    "data": {
        "@odata.type": "microsoft.graph.onTokenIssuanceStartResponseData",
        "actions": [
            {
                "@odata.type": "ProvideClaimsForToken",
                "claims": [
                    {
                        "DateOfBirth": "01/01/2000"
                    },
                    {
                        "CustomRoles": [
                            "Writer",
                            "Editor"
                        ]
                    }
                ]
            }
        ]
    }
}

Solução de problemas

  • Visual Studio Code
    • Se estiver em execução no Visual Studio Code, você receberá um erro nos moldes do Emulador de Armazenamento do Azure local não estiver disponível, você poderá iniciar o emulador manualmente.! (Observação: o emulador do Armazenamento do Azure agora foi preterido e a substituição sugerida é Azurite)
    • Se estiver usando Visual Studio Code no Mac, use o Azurite
    • Se você vir o erro a seguir no Windows (é um bug) ao tentar executar o projeto criado.
    • Isso pode ser resolvido executando este comando no PowerShell Set-ExecutionPolicy -ExecutionPolicy Unrestricted -Scope LocalMachine mais informações sobre isso podem ser encontradas aqui e aqui

Próximas etapas

Para obter mais informações sobre o SDK do Azure, consulte este site

Publicação

  • Siga as instruções aqui para criar e publicar seu Aplicativo Azure. </azure/azure-functions/functions-develop-vs?tabs=in-process#publish-to-azure>
  • Para determinar o ponto de extremidade de postagem publicado, combine o ponto de extremidade de função do azure criado, encaminhe para o ouvinte e o código do ouvinte, o código de escuta pode ser encontrado navegando até o aplicativo de funções do azure, selecionando "Chaves de Aplicativo" e copiando o valor de AuthenticationEvents_extension.
  • Por exemplo: "https://azureautheventstriggerdemo.azurewebsites.net/runtime/webhooks/AuthenticationEvents?code=(AuthenticationEvents_extension_key)& function=OnTokenIssuanceStart"
  • Verifique se o ambiente de produção tem as configurações de aplicativo corretas para autenticação de token.
  • Mais uma vez, você pode testar a função publicada postando a carga acima no novo ponto de extremidade.

Participante

Para obter detalhes sobre como contribuir para esse repositório, consulte o guia de contribuição.

Este projeto aceita contribuições e sugestões. A maioria das contribuições exige que você concorde com um CLA (Contrato de Licença do Colaborador) declarando que você tem o direito de nos conceder, e de fato concede, os direitos de usar sua contribuição. Para obter detalhes, visite https://cla.microsoft.com.

Quando você envia uma solicitação de pull, um bot do CLA determina automaticamente se você precisa fornecer um CLA e preencher a PR corretamente (por exemplo, rótulo, comentário). Basta seguir as instruções fornecidas pelo bot. Você só precisará fazer isso uma vez em todos os repositórios usando nosso CLA.

Este projeto adotou o Código de Conduta de Software Livre da Microsoft. Para obter mais informações, confira as Perguntas frequentes sobre o Código de Conduta ou contate opencode@microsoft.com para enviar outras perguntas ou comentários.