Partilhar via

Configurar o Serviço de Aplicativo ou o aplicativo Azure Functions para usar a entrada do Microsoft Entra

  • Artigo

Nota

A partir de 1º de junho de 2024, todos os aplicativos do Serviço de Aplicativo recém-criados terão a opção de criar um nome de host padrão exclusivo com uma convenção de nomenclatura de <app-name>-<random-hash>.<region>..azurewebsites.net Os nomes dos aplicativos existentes não serão alterados.

Exemplo: myapp-ds27dh7271aah175.westus-01.azurewebsites.net

Para obter mais informações, consulte Nome de host padrão exclusivo para recurso do Serviço de Aplicativo.

Selecione outro provedor de autenticação para ir até ele.

Este artigo mostra como configurar a autenticação para o Serviço de Aplicativo do Azure ou o Azure Functions para que seu aplicativo entre em usuários com a plataforma de identidade da Microsoft (Microsoft Entra) como o provedor de autenticação.

Escolha um locatário para seu aplicativo e seus usuários

Antes que seu aplicativo possa entrar em usuários, você precisa primeiro registrá-lo em uma força de trabalho ou locatário externo. Se você estiver disponibilizando seu aplicativo para funcionários ou convidados de negócios, registre seu aplicativo em um locatário do mercado de trabalho. Se o seu aplicativo for para consumidores e clientes empresariais, registre-o em um locatário externo.

  1. Entre no portal do Azure e navegue até seu aplicativo.

  2. No menu esquerdo da sua aplicação, selecione Autenticação e, em seguida, selecione Adicionar fornecedor de identidade.

  3. Na página Adicionar um provedor de identidade, selecione Microsoft como o provedor de identidade para entrar nas identidades Microsoft e Microsoft Entra.

  4. Para Tipo de locatário, selecione Configuração da força de trabalho (locatário atual) para funcionários e convidados de negócios ou selecione Configuração externa para consumidores e clientes empresariais.

Escolha o registo da aplicação

O recurso Autenticação do Serviço de Aplicativo pode criar automaticamente um registro de aplicativo para você ou você pode usar um registro que você ou um administrador de diretório criou separadamente.

Crie um novo registro de aplicativo automaticamente, a menos que você precise criar um registro de aplicativo separadamente. Você pode personalizar o registro do aplicativo no centro de administração do Microsoft Entra mais tarde, se desejar.

As seguintes situações são os casos mais comuns para usar um registro de aplicativo existente:

  • Sua conta não tem permissões para criar registros de aplicativos em seu locatário do Microsoft Entra.
  • Você deseja usar um registro de aplicativo de um locatário do Microsoft Entra diferente daquele em que seu aplicativo está.
  • A opção de criar um novo registro não está disponível para nuvens governamentais.

Crie e use um novo registro de aplicativo ou use um registro existente criado separadamente.

Opção 1: Criar e usar um novo registro de aplicativo

Use essa opção, a menos que você precise criar um registro de aplicativo separadamente. Você pode personalizar o registro do aplicativo no Microsoft Entra depois que ele for criado.

Nota

A opção de criar um novo registro automaticamente não está disponível para nuvens governamentais. Em vez disso, defina um registro separadamente.

Introduza o Nome para o registo da nova aplicação.

Selecione o tipo de conta suportada:

  • Inquilino atual - Inquilino único. Contas somente neste diretório organizacional. Todas as contas de usuário e convidado em seu diretório podem usar seu aplicativo ou API. Utilize esta opção se o seu público-alvo for interno à sua organização.
  • Qualquer diretório Microsoft Entra - Multitenant. Contas em qualquer diretório organizacional. Todos os usuários com uma conta corporativa ou de estudante da Microsoft podem usar seu aplicativo ou API. Isso inclui escolas e empresas que usam o Office 365. Use esta opção se o seu público-alvo for clientes empresariais ou educacionais e para permitir a multilocação.
  • Qualquer diretório do Microsoft Entra ou contas pessoais da Microsoft. Contas em qualquer diretório organizacional e contas pessoais da Microsoft (por exemplo, Skype, Xbox). Todos os utilizadores com uma conta Microsoft profissional ou escolar ou pessoal podem utilizar a sua aplicação ou API. Inclui escolas e empresas que utilizam o Office 365, bem como contas pessoais que são utilizadas para iniciar sessão em serviços como a Xbox e o Skype. Use essa opção para direcionar o conjunto mais amplo de identidades da Microsoft e habilitar a multilocação.
  • Apenas contas pessoais da Microsoft. Contas pessoais que são utilizadas para iniciar sessão em serviços como a Xbox e o Skype. Use esta opção para direcionar o conjunto mais amplo de identidades da Microsoft.

Você pode alterar o nome do registro ou os tipos de conta suportados mais tarde, se desejar.

Um segredo do cliente é criado como uma configuração de aplicativo adesivo de slot chamada MICROSOFT_PROVIDER_AUTHENTICATION_SECRET. Você pode atualizar essa configuração posteriormente para usar referências do Cofre da Chave se desejar gerenciar o segredo no Cofre da Chave do Azure.

Opção 2: Usar um registro existente criado separadamente

Uma das seguintes opções:

  • Selecione Escolher um registro de aplicativo existente neste diretório e selecione um registro de aplicativo na lista suspensa.
  • Selecione Fornecer os detalhes de um registro de aplicativo existente e forneça:
    • ID do aplicativo (cliente).
    • Segredo do cliente (recomendado). Um valor secreto que o aplicativo usa para provar sua identidade ao solicitar um token. Esse valor é salvo na configuração do seu aplicativo como uma configuração de aplicativo com adesivo de slot chamada MICROSOFT_PROVIDER_AUTHENTICATION_SECRET. Se o segredo do cliente não estiver definido, as operações de entrada do serviço usarão o fluxo de concessão implícito do OAuth 2.0, o que não é recomendado* .
    • URL do emissor, que assume a forma <authentication-endpoint>/<tenant-id>/v2.0. Substitua <authentication-endpoint> pelo valor do ponto de extremidade de autenticação específico para o ambiente de nuvem. Por exemplo, um locatário da força de trabalho no Azure global usaria "https://login.microsoftonline.com" como seu ponto de extremidade de autenticação.

Se você precisar criar manualmente um registro de aplicativo em um locatário do workforce, siga o início rápido de registrar um aplicativo . Ao passar pelo processo de registro, certifique-se de anotar o ID do aplicativo (cliente) e os valores secretos do cliente.

Durante o processo de registro, na seção Redirecionar URIs , selecione Web para plataforma e digite <app-url>/.auth/login/aad/callback. Por exemplo, https://contoso.azurewebsites.net/.auth/login/aad/callback.

Após a criação, modifique o registro do aplicativo:

  1. Na navegação à esquerda, selecione Expor uma API>Adicionar>salvar. Esse valor identifica exclusivamente o aplicativo quando ele é usado como um recurso, permitindo que sejam solicitados tokens que concedem acesso. Ele é usado como um prefixo para escopos que você cria.

    Para um aplicativo de locatário único, você pode usar o valor padrão, que está no formato api://<application-client-id>. Você também pode especificar um URI mais legível, como https://contoso.com/api com base em um dos domínios verificados para seu locatário. Para um aplicativo multilocatário, você deve fornecer um URI personalizado. Para saber mais sobre os formatos aceitos para URIs de ID de aplicativo, consulte a referência de práticas recomendadas de registros de aplicativos.

  2. Selecione Adicionar âmbito.

    1. Em Nome do escopo, digite user_impersonation.
    2. Em Quem pode consentir, selecione Administradores e usuários se quiser permitir que os usuários consintam com esse escopo.
    3. Nas caixas de texto, insira o nome e a descrição do escopo de consentimento que você deseja que os usuários vejam na página de consentimento. Por exemplo, insira o nome> do aplicativo do Access<.
    4. Selecione Adicionar escopo.

  3. (Recomendado) Para criar um segredo do cliente:

    1. Na navegação à esquerda, selecione Certificados & segredos do>cliente Novo segredo do>cliente.
    2. Insira uma descrição e expiração e selecione Adicionar.
    3. No campo Valor, copie o valor secreto do cliente. Ele não será mostrado novamente quando você sair desta página.

  4. (Opcional) Para adicionar vários URLs de resposta, selecione Autenticação.

Configurar verificações adicionais

Configure verificações adicionais, que determinam quais solicitações têm permissão para acessar seu aplicativo. Você pode personalizar esse comportamento agora ou ajustar essas configurações posteriormente na tela principal de Autenticação , escolhendo Editar ao lado de Configurações de autenticação.

Para Requisito de aplicativo cliente, escolha se:

  • Permitir solicitações somente a partir deste aplicativo em si
  • Permitir solicitações de aplicativos cliente específicos
  • Permitir solicitações de qualquer aplicativo (Não recomendado)

Para Requisito de identidade, escolha se:

  • Permitir solicitações de qualquer identidade
  • Permitir solicitações de identidades específicas

Para Requisito de locatário, escolha se:

  • Permitir solicitações somente do locatário emissor
  • Permitir solicitações de locatários específicos
  • Usar restrições padrão com base no emissor

Seu aplicativo ainda pode precisar tomar decisões de autorização adicionais no código. Para obter mais informações, consulte Usar uma política de autorização interna.

Configurar definições de autenticação

Essas opções determinam como seu aplicativo responde a solicitações não autenticadas, e as seleções padrão redirecionarão todas as solicitações para entrar com esse novo provedor. Você pode alterar esse comportamento agora ou ajustar essas configurações posteriormente na tela principal Autenticação escolhendo Editar ao lado de Configurações de autenticação. Para saber mais sobre essas opções, consulte Fluxo de autenticação.

Em Restringir acesso, decida se:

  • Exigir autenticação
  • Permitir acesso não autenticado

Para pedidos não autenticados

  • Redirecionamento HTTP 302 encontrado: recomendado para sites
  • HTTP 401 Não autorizado: recomendado para APIs
  • HTTP 403 Proibido
  • HTTP 404 Não encontrado

Selecione Loja de tokens (recomendado). O repositório de tokens coleta, armazena e atualiza tokens para seu aplicativo. Você pode desativar isso mais tarde se seu aplicativo não precisar de tokens ou se você precisar otimizar o desempenho.

Adicionar o provedor de identidade

Se você selecionou a configuração da força de trabalho, poderá selecionar Avançar: Permissões e adicionar quaisquer permissões do Microsoft Graph necessárias para o aplicativo. Estes serão adicionados ao registo da aplicação, mas também pode alterá-los mais tarde. Se você selecionou a configuração externa, poderá adicionar permissões do Microsoft Graph posteriormente.

Selecione Adicionar.

Agora você está pronto para usar a plataforma de identidade da Microsoft para autenticação em seu aplicativo. O provedor será listado na tela Autenticação . A partir daí, você pode editar ou excluir essa configuração do provedor.

Para obter um exemplo de configuração do início de sessão do Microsoft Entra para uma aplicação Web que acede ao Armazenamento do Azure e ao Microsoft Graph, consulte este tutorial.

Autorizar pedidos

Por padrão, a Autenticação do Serviço de Aplicativo lida apenas com a autenticação, determinando se o chamador é quem diz ser. A autorização, que determina se esse chamador deve ter acesso a algum recurso, é uma etapa extra além da autenticação. Você pode aprender mais sobre esses conceitos em Noções básicas de autorização de plataforma de identidade da Microsoft.

Seu aplicativo pode tomar decisões de autorização no código. A Autenticação do Serviço de Aplicativo fornece algumas verificações internas, que podem ajudar, mas elas podem não ser suficientes, por si só, para cobrir as necessidades de autorização do seu aplicativo.

Gorjeta

Os aplicativos multilocatários devem validar a ID do emissor e do locatário da solicitação como parte desse processo para garantir que os valores sejam permitidos. Quando a Autenticação do Serviço de Aplicativo é configurada para um cenário multilocatário, ela não valida de qual locatário a solicitação vem. Um aplicativo pode precisar ser limitado a locatários específicos, com base no fato de a organização ter se inscrito no serviço, por exemplo. Consulte as diretrizes multilocatárias da plataforma de identidade da Microsoft.

Executar validações a partir do código do aplicativo

Ao executar verificações de autorização no código do aplicativo, você pode usar as informações de declarações que a Autenticação do Serviço de Aplicativo disponibiliza. O cabeçalho injetado x-ms-client-principal contém um objeto JSON codificado em Base64 com as declarações declaradas sobre o chamador. Por padrão, essas declarações passam por um mapeamento de declarações, portanto, os nomes das declarações nem sempre correspondem ao que você veria no token. Por exemplo, a declaração é mapeada tid para http://schemas.microsoft.com/identity/claims/tenantid em vez disso.

Você também pode trabalhar diretamente com o token de acesso subjacente a partir do cabeçalho injetado x-ms-token-aad-access-token .

Usar uma política de autorização interna

O registro do aplicativo criado autentica as solicitações de entrada para seu locatário do Microsoft Entra. Por padrão, ele também permite que qualquer pessoa dentro do locatário acesse o aplicativo, o que é bom para muitos aplicativos. No entanto, alguns aplicativos precisam restringir ainda mais o acesso tomando decisões de autorização. O código do aplicativo geralmente é o melhor lugar para lidar com a lógica de autorização personalizada. No entanto, para cenários comuns, a plataforma de identidade da Microsoft fornece verificações internas que você pode usar para limitar o acesso.

Esta seção mostra como habilitar verificações internas usando a API V2 de autenticação do Serviço de Aplicativo. Atualmente, a única maneira de configurar essas verificações internas é por meio de modelos do Azure Resource Manager ou da API REST.

Dentro do objeto API, a configuração do provedor de identidade Microsoft Entra tem uma validation seção que pode incluir um defaultAuthorizationPolicy objeto como na seguinte estrutura:

{
    "validation": {
        "defaultAuthorizationPolicy": {
            "allowedApplications": [],
            "allowedPrincipals": {
                "identities": []
            }
        }
    }
}
Property Description
defaultAuthorizationPolicy Um agrupamento de requisitos que devem ser atendidos para acessar o aplicativo. O acesso é concedido com base em uma lógica AND sobre cada uma de suas propriedades configuradas. Quando allowedApplications e allowedPrincipals estão configurados, a solicitação de entrada deve satisfazer ambos os requisitos para ser aceita.
allowedApplications Uma lista permitida de IDs de cliente de aplicativo de cadeia de caracteres que representam o recurso de cliente que está chamando o aplicativo. Quando essa propriedade é configurada como uma matriz não vazia, somente tokens obtidos por um aplicativo especificado na lista serão aceitos.

Esta política avalia a appid ou azp declaração do token de entrada, que deve ser um token de acesso. Consulte a referência de declarações da plataforma de identidade da Microsoft.
allowedPrincipals Um agrupamento de verificações que determina se a entidade representada pela solicitação de entrada pode acessar o aplicativo. A satisfação de é baseada em uma lógica OR sobre suas propriedades configuradasallowedPrincipals.
identities (em allowedPrincipals) Uma lista permitida de IDs de objeto de cadeia de caracteres que representam usuários ou aplicativos que têm acesso. Quando essa propriedade é configurada como uma matriz não vazia, o allowedPrincipals requisito pode ser satisfeito se o usuário ou aplicativo representado pela solicitação for especificado na lista. Há um limite de 500 caracteres no total em toda a lista de identidades.

Esta política avalia a oid declaração do token de entrada. Consulte a referência de declarações da plataforma de identidade da Microsoft.

Além disso, algumas verificações podem ser configuradas por meio de uma configuração de aplicativo, independentemente da versão da API que está sendo usada. A WEBSITE_AUTH_AAD_ALLOWED_TENANTS configuração do aplicativo pode ser configurada com uma lista separada por vírgulas de até 10 IDs de locatário (por exemplo, "559a2f9c-c6f2-4d31-b8d6-5ad1a13f8330,5693f64a-3ad5-4be7-b846-e9d1141bcebc") para exigir que o token de entrada seja de um dos locatários especificados, conforme especificado pela tid declaração. A WEBSITE_AUTH_AAD_REQUIRE_CLIENT_SERVICE_PRINCIPAL configuração do aplicativo pode ser configurada como "true" ou "1" para exigir que o token de entrada inclua uma oid declaração. Essa configuração é ignorada e tratada como verdadeira se allowedPrincipals.identities tiver sido configurada (uma vez que a declaração é verificada oid em relação a essa lista de identidades fornecida).

As solicitações que falharem nessas verificações internas recebem uma resposta HTTP 403 Forbidden .

Configurar aplicativos cliente para acessar seu Serviço de Aplicativo

Nas seções anteriores, você registrou seu Serviço de Aplicativo ou Função do Azure para autenticar usuários. Esta seção explica como registrar clientes nativos ou aplicativos daemon no Microsoft Entra para que eles possam solicitar acesso às APIs expostas pelo seu Serviço de Aplicativo em nome dos usuários ou de si mesmos, como em uma arquitetura de N camadas. Concluir as etapas nesta seção não é necessário se você deseja apenas autenticar usuários.

Aplicativo cliente nativo

Você pode registrar clientes nativos para solicitar acesso às APIs do aplicativo do Serviço de Aplicativo em nome de um usuário conectado.

  1. No menu do portal, selecione Microsoft Entra.

  2. Na navegação à esquerda, selecione Registos de>aplicações Novo registo.

  3. Na página Registar uma aplicação, introduza um Nome para o registo da sua aplicação.

  4. Em Redirecionar URI, selecione Cliente público (mobile & desktop) e digite a URL <app-url>/.auth/login/aad/callback. Por exemplo, https://contoso.azurewebsites.net/.auth/login/aad/callback.

  5. Selecione Registar.

  6. Depois que o registro do aplicativo for criado, copie o valor da ID do aplicativo (cliente).

    Nota

    Para um aplicativo da Microsoft Store, use o SID do pacote como o URI.

  7. Na navegação à esquerda, selecione Permissões>de API Adicionar uma permissão>Minhas APIs.

  8. Selecione o registro do aplicativo que você criou anteriormente para seu aplicativo do Serviço de Aplicativo. Se não vir o registo da aplicação, certifique-se de que adicionou o âmbito user_impersonation no registo da aplicação.

  9. Em Permissões delegadas, selecione user_impersonation e, em seguida, selecione Adicionar permissões.

Agora você configurou um aplicativo cliente nativo que pode solicitar acesso ao seu aplicativo do Serviço de Aplicativo em nome de um usuário.

Aplicativo cliente Daemon (chamadas serviço-a-serviço)

Em uma arquitetura de N camadas, seu aplicativo cliente pode adquirir um token para chamar um Serviço de Aplicativo ou aplicativo de Função em nome do próprio aplicativo cliente (não em nome de um usuário). Este cenário é útil para aplicativos daemon não interativos que executam tarefas sem um usuário conectado. Ele usa a concessão de credenciais de cliente OAuth 2.0 padrão.

  1. No menu do portal, selecione Microsoft Entra.
  2. Na navegação à esquerda, selecione Registos de>aplicações Novo registo.
  3. Na página Registar uma aplicação, introduza um Nome para o registo da sua aplicação.
  4. Para um aplicativo daemon, você não precisa de um URI de redirecionamento para poder mantê-lo vazio.
  5. Selecione Registar.
  6. Depois que o registro do aplicativo for criado, copie o valor da ID do aplicativo (cliente).
  7. Na navegação à esquerda, selecione Certificados & segredos do>cliente Novo segredo do>cliente.
  8. Insira uma descrição e expiração e selecione Adicionar.
  9. No campo Valor, copie o valor secreto do cliente. Ele não será mostrado novamente quando você sair desta página.

Agora você pode solicitar um token de acesso usando a ID do cliente e o segredo do cliente definindo o resource parâmetro como o URI da ID do aplicativo de destino. O token de acesso resultante pode ser apresentado ao aplicativo de destino usando o cabeçalho de Autorização OAuth 2.0 padrão, e a autenticação do Serviço de Aplicativo validará e usará o token como de costume para indicar agora que o chamador (um aplicativo, neste caso, não um usuário) está autenticado.

No momento, isso permite que qualquer aplicativo cliente em seu locatário do Microsoft Entra solicite um token de acesso e se autentique no aplicativo de destino. Se você também quiser impor a autorização para permitir apenas determinados aplicativos cliente, deverá executar alguma configuração extra.

  1. Defina uma Função de Aplicativo no manifesto do registro do aplicativo que representa o aplicativo Serviço de Aplicativo ou Função que você deseja proteger.
  2. No registro do aplicativo que representa o cliente que precisa ser autorizado, selecione Permissões>de API Adicionar uma permissão>Minhas APIs.
  3. Selecione o registro do aplicativo que você criou anteriormente. Se não vir o registo da aplicação, certifique-se de que adicionou uma Função de Aplicação.
  4. Em Permissões de aplicativo, selecione a Função de Aplicativo criada anteriormente e selecione Adicionar permissões.
  5. Certifique-se de selecionar Conceder consentimento de administrador para autorizar o aplicativo cliente a solicitar a permissão.
  6. Semelhante ao cenário anterior (antes de quaisquer funções serem adicionadas), agora você pode solicitar um token de acesso para o mesmo destino resourcee o token de acesso incluirá uma roles declaração contendo as Funções de Aplicativo que foram autorizadas para o aplicativo cliente.
  7. No código do aplicativo Serviço de Aplicativo ou Função de destino, agora você pode validar se as funções esperadas estão presentes no token (isso não é executado pela autenticação do Serviço de Aplicativo). Para obter mais informações, consulte Acessar declarações de usuário.

Agora você configurou um aplicativo cliente daemon que pode acessar seu aplicativo do Serviço de Aplicativo usando sua própria identidade.

Melhores práticas

Independentemente da configuração usada para configurar a autenticação, as seguintes práticas recomendadas mantêm seu locatário e aplicativos mais seguros:

  • Configure cada aplicativo do Serviço de Aplicativo com seu próprio registro de aplicativo no Microsoft Entra.
  • Atribua a cada aplicação do Serviço de Aplicações as suas próprias permissões e consentimento.
  • Evite a partilha de permissões entre ambientes através de registos de aplicações separados para blocos de implementação separados. Quando estiver a testar um novo código, esta prática pode ajudar a evitar problemas na aplicação de produção.

Migrar para o Microsoft Graph

Alguns aplicativos mais antigos também podem ter sido configurados com uma dependência do Azure AD Graph preterido, que está agendado para a desativação total. Por exemplo, o código do seu aplicativo pode ter chamado o Azure AD Graph para verificar a associação ao grupo como parte de um filtro de autorização em um pipeline de middleware. Os aplicativos devem ser movidos para o Microsoft Graph seguindo as orientações fornecidas pelo Microsoft Entra como parte do processo de descontinuação do Azure AD Graph. Ao seguir essas instruções, talvez seja necessário fazer algumas alterações na configuração da autenticação do Serviço de Aplicativo. Depois de adicionar permissões do Microsoft Graph ao registro do aplicativo, você pode:

  1. Atualize o URL do Emissor para incluir o sufixo "/v2.0", caso ainda não o faça.

  2. Remova solicitações de permissões do Azure AD Graph de sua configuração de entrada. As propriedades a serem alteradas dependem da versão da API de gerenciamento que você está usando:

    • Se você estiver usando a API V1 (/authsettings), isso estará na additionalLoginParams matriz.
    • Se você estiver usando a API V2 (/authsettingsV2), isso estará na loginParameters matriz.

    Você precisaria remover qualquer referência a "https://graph.windows.net", por exemplo. Isso inclui o resource parâmetro (que não é suportado pelo ponto de extremidade "/v2.0") ou quaisquer escopos que você está solicitando especificamente que são do Azure AD Graph.

    Você também precisaria atualizar a configuração para solicitar as novas permissões do Microsoft Graph configuradas para o registro do aplicativo. Você pode usar o escopo .default para simplificar essa configuração em muitos casos. Para fazer isso, adicione um novo parâmetro scope=openid profile email https://graph.microsoft.com/.defaultde entrada .

Com essas alterações, quando a Autenticação do Serviço de Aplicativo tentar entrar, ela não solicitará mais permissões para o Azure AD Graph e, em vez disso, obterá um token para o Microsoft Graph. Qualquer uso desse token do código do seu aplicativo também precisaria ser atualizado, de acordo com as orientações fornecidas pelo Microsoft Entra.

Passos seguintes