Partilhar via

Acionador de Eventos de Autenticação para Funções do Azure biblioteca de cliente para Node

  • Artigo

O Acionador de Eventos de Autenticação para Funções do Azure processa todo o processamento de back-end (por exemplo, a validação do esquema de token/json) para pedidos Http recebidos para eventos de Autenticação. Além disso, fornece ao programador um modelo de objeto com uma versão forte para trabalhar, o que significa que o programador não precisa de ter conhecimento prévio do pedido e dos payloads de json de resposta.

Esta arquitetura de projeto fornece as seguintes funcionalidades:

  • Validação de tokens para proteger a chamada à API
  • Modelo de objeto, escrita e intellisense de IDE
  • Validação de entrada e saída dos esquemas de pedido e resposta da API
  • Controlo de versões
  • Não precisa de código automático.

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 chama a extensão personalizada, envia um Authorization cabeçalho com um Bearer {token}. Este token representará uma autenticação serviço a serviço na qual:

  • O "recurso", também conhecido como audiência, é a aplicação que regista para representar a sua API. Isto é representado pela aud afirmação no token.
  • O "cliente" é uma aplicação da Microsoft que representa o serviço de eventos de autenticação Azure AD. Tem um appId valor de 99045fe1-7639-4a75-9d4a-577b6ca3810f. Isto é representado por:
    • A azp afirmação no token se a propriedade da aplicação accessTokenAcceptedVersion estiver definida como 2.
    • A appid afirmação no token se a propriedade da aplicação de accessTokenAcceptedVersion recurso estiver definida como 1 ou null.

Existem três abordagens para lidar com o token. Pode personalizar o comportamento com as definições da aplicação , conforme mostrado abaixo ou através do ficheiro local.settings.json em ambientes locais.

Validar tokens com a integração de autenticação Funções do Azure Azure AD

Ao executar a sua função na produção, é altamente recomendado utilizar a integração de autenticação Funções do Azure Azure AD para validar tokens de entrada.

  1. Aceda ao separador "Autenticação" na Aplicação de Funções
  2. Clique em "Adicionar fornecedor de identidade"
  3. Selecione "Microsoft" como fornecedor de identidade
  4. Selecione "Indique os detalhes de um registo de aplicação existente"
  5. Introduza o Application ID da aplicação que representa a sua API no Azure AD

O emissor e a audiência permitida dependem da propriedade da sua aplicação accessTokenAcceptedVersion (pode ser encontrado no "Manifesto" da aplicação).

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

Se a 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 asidentificadorUri). It should be in the format ofapi://{azureFunctionAppNameaccessTokenAcceptedVersion}.azurewebsites.net/{resourceApiAppId}orapi://{FunctionAppFullyQualifiedDomainName}/{resourceApiAppId}' se estiver a utilizar um nome de domínio personalizado.

Por predefinição, o acionador de eventos de Autenticação validará que a integração de autenticação da Função do Azure está configurada e verificará se o cliente no token está definido como 99045fe1-7639-4a75-9d4a-577b6ca3810f (através das azp afirmações ou appid no token).

Se quiser testar a API em relação a outro cliente que não esteja Azure AD serviço de eventos de autenticação, como utilizar o Postman, pode configurar uma definição de aplicação opcional:

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

Fazer com que o acionador valide o token

Em ambientes locais ou ambientes que não estão alojados no serviço de Funções do Azure, o acionador pode fazer a validação do token. Defina as seguintes definições de aplicação:

  • AuthenticationEvents__TenantId - o seu ID de inquilino
  • AuthenticationEvents__AudienceAppId - o mesmo valor que "Audiência permitida" na opção 1.
  • AuthenticationEvents__CustomCallerAppId (opcional) – o guid do cliente pretendido. Se não for fornecido, 99045fe1-7639-4a75-9d4a-577b6ca3810f é assumido.

Um ficheiro de exemplo local.settings.json :

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

Sem validação de tokens

Se quiser não autenticar o token durante o desenvolvimento local, defina a seguinte definição de aplicação:

  • AuthenticationEvents__BypassTokenValidation - o valor de true fará com que o acionador não verifique a validação do token.

Início Rápido

  • Visual Studio Code
    • Inicie o Visual Studio Code.
    • Executar o comando func init . --worker-runtime node de terminal através da paleta de comandos
    • Executar o comando func new de terminal através da paleta de comandos
    • Siga as instruções de criação do projeto
    • Executar o comando npm install @azure/functions-authentication-events de terminal através da paleta de comandos
    • Executar o comando npm install de terminal através da paleta de comandos
    • Executar o comando npm run-script build de terminal através da paleta de comandos
  • Para fins de desenvolvimento, mude a validação de tokens para teste:
  • Adicione a AuthenticationEvents__BypassTokenValidation chave de aplicação à secção "Valores" no ficheiro local.settings.json e defina o valor como verdadeiro. Se não tiver um ficheiro local.settings.json no seu ambiente local, crie um na raiz da Aplicação de Funções.
{
  "IsEncrypted": false,
  "Values": {
    "AzureWebJobsStorage": "UseDevelopmentStorage=true",
    "FUNCTIONS_WORKER_RUNTIME": "node",
    "AuthenticationEvents__BypassTokenValidation": true
  }
}
  • Assim que o projeto for carregado, pode executar o código de exemplo e deverá ver a aplicação do programador das funções do Azure a carregar o ponto final.

Conceitos-chave

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

Documentação

  • Uma função foi publicada, há uma boa leitura sobre o registo e as métricas que podem ser encontradas aqui

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

  • Assim que esta ação mudar para a pré-visualização, exceto se não houver alterações interruptivas e será tão simples como remover a origem nuget que aponta para a pré-visualização privada.

Exemplos

Para Testar o Aumento de Tokens, faça o seguinte.

  • Abra o projeto que foi criado no passo anterior. (Início Rápido)
  • Execute a Aplicação. func host start
  • Assim que a aplicação do programador das funções do Azure for iniciada, copie o URL de escuta que é apresentado com a aplicação.
  • Nota: todas as funções de Autenticação estão listadas, caso tenhamos um serviço de escuta de função registado chamado "OnTokenIssuanceStart"
  • O ponto final da função será, em seguida, uma combinação do URL e da função de escuta, por exemplo: "http://localhost:7071/runtime/webhooks/AuthenticationEvents?code=(YOUR_CODE)& function=OnTokenIssuanceStart"
  • Publique o seguinte payload com algo como o Postman ou o Fiddler.
  • Pode encontrar os passos para utilizar o Postman (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"
            }
        }
    }
}
  • Deverá ver esta resposta:
{
    "data": {
        "@odata.type": "microsoft.graph.onTokenIssuanceStartResponseData",
        "actions": [
            {
                "@odata.type": "ProvideClaimsForToken",
                "claims": [
                    {
                        "DateOfBirth": "01/01/2000"
                    },
                    {
                        "CustomRoles": [
                            "Writer",
                            "Editor"
                        ]
                    }
                ]
            }
        ]
    }
}

Resolução de problemas

  • Visual Studio Code
    • Se estiver a ser executado no Visual Studio Code, receberá um erro na linha do Emulador de Armazenamento do Azure local indisponível, pode iniciar o emulador manualmente.! (Nota: o emulador do Armazenamento do Azure foi preterido e a substituição sugerida é Azurite)
    • Se estiver a utilizar o Visual Studio Code no Mac, utilize o Azurite
    • Se vir o seguinte erro no Windows (é um erro) ao tentar executar o projeto criado.
    • Isto pode ser resolvido ao executar este comando no PowerShell Set-ExecutionPolicy -ExecutionPolicy Unrestricted -Scope LocalMachine . Pode encontrar mais informações aqui e aqui

Passos seguintes

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

Publicar

  • Siga as instruções aqui para criar e publicar a sua Aplicação Azure. </azure/azure-functions/functions-develop-vs?tabs=in-process#publish-to-azure>
  • Para determinar o ponto final de publicação publicado, combinar o ponto final da função do Azure que criou, encaminhar para o serviço de escuta e o código do serviço de escuta, pode encontrar o código de escuta ao navegar para a sua aplicação de função do Azure, selecionar "Chaves de Aplicação" e copiar o valor de AuthenticationEvents_extension.
  • Por exemplo: "https://azureautheventstriggerdemo.azurewebsites.net/runtime/webhooks/AuthenticationEvents?code=(AuthenticationEvents_extension_key)& function=OnTokenIssuanceStart"
  • Certifique-se de que o ambiente de produção tem as definições de aplicação corretas para a autenticação de tokens.
  • Mais uma vez, pode testar a função publicada ao publicar o payload acima no novo ponto final.

Contribuir

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

Agradecemos todas as contribuições e sugestões para este projeto. A maioria das contribuições requerem que celebre um Contrato de Licença de Contribuição (CLA) no qual se declare que tem o direito de conceder e que, na verdade, concede-nos os direitos para utilizar a sua contribuição. Para mais detalhes, visite https://cla.microsoft.com.

Quando submete um pedido Pull, um bot do CLA determina automaticamente se tem de fornecer um CLA e decorar o PR de forma adequada (por exemplo, etiqueta, comentário). Só tem de seguir as instruções fornecidas pelo bot. Só terá de o fazer uma vez em todos os repositórios com o nosso CLA.

Este projeto adotou o Microsoft Open Source Code of Conduct (Código de Conduta do Microsoft Open Source). Para obter mais informações, consulte as FAQ do Código de Conduta ou contacte opencode@microsoft.com com quaisquer perguntas ou comentários adicionais.