Compartilhar via

Configurar seu aplicativo do Serviço de Aplicativo ou do Azure Functions para usar o logon do Microsoft Entra

  • Artigo

Observação

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

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

Para obter mais detalhes, consulte Nome do Host Padrão Exclusivo para o Recurso Serviço de Aplicativo.

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

Este artigo mostra como configurar a autenticação para o Serviço de Aplicativo do Azure ou o Azure Functions de modo que seu aplicativo conecte os usuários com a Plataforma de Identidade da Microsoft (Microsoft Entra) como o provedor de autenticação.

Escolher um locatário para o aplicativo e os usuários

Antes que o aplicativo possa conectar usuários, primeiro você precisará registrá-lo em uma força de trabalho ou locatário externo. Caso esteja disponibilizando o aplicativo para funcionários ou convidados comerciais, registre o aplicativo em um locatário da força de trabalho. Se o aplicativo for para consumidores e clientes comerciais, registre-o em um locatário externo.

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

  2. No menu à esquerda do aplicativo, selecione Autenticação e escolha Adicionar provedor de identidade.

  3. Na página Adicionar um provedor de identidade, selecione Microsoft como o Provedor de identidade para conectar identidades da Microsoft e do Microsoft Entra.

  4. Para o Tipo locatário, selecione a configuração da Força de Trabalho (locatário atual) para funcionários e convidados comerciais ou selecione Configuração externa para consumidores e clientes corporativos.

Escolha o registro do aplicativo

O recurso autenticação do Serviço de Aplicativo pode criar automaticamente um registro de aplicativo para você ou é possível 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ê poderá 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 o uso de 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ê quer 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 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 esta opção, a menos que você precise criar um registro de aplicativo separadamente. Você poderá personalizar o registro do aplicativo no Microsoft Entra depois que ele for criado.

Observação

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

Insira o Nome do novo registro do aplicativo.

Selecione o tipo de conta com suporte:

  • Locatário atual – Locatário único. Contas somente neste diretório organizacional. Todas as contas de usuários e convidados no diretório podem usar seu aplicativo ou API. Use essa opção se o público-alvo for interno à sua organização.
  • Qualquer diretório do Microsoft Entra – Multilocatário. Contas em qualquer diretório organizacional. Todos os usuários com uma conta corporativa ou de estudante da Microsoft podem usar o aplicativo ou a API. Isso inclui as escolas e as empresas que usam o Office 365. Use essa opção se sua audiência alvo incluir clientes empresariais ou educacionais e para habilitar multilocação.
  • Qualquer diretório do Microsoft Entra e contas pessoais da Microsoft. Contas em qualquer diretório organizacional e contas pessoais da Microsoft (por exemplo, Skype, Xbox). Todos os usuários com uma conta Microsoft corporativa, de estudante ou pessoal podem usar o aplicativo ou a API. Isso inclui escolas e empresas que usam o Office 365, bem como contas pessoais que são usadas para entrar em serviços como o Xbox e o Skype. Use essa opção para direcionar o conjunto mais amplo de identidades da Microsoft e habilitar a multilocação.
  • Somente contas pessoais da Microsoft. Contas pessoais usadas para entrar em serviços como Xbox e Skype. Use essa opção para direcionar o conjunto mais amplo de identidades da Microsoft.

Você poderá alterar o nome do registro ou os tipos de conta com suporte posteriormente, se desejar.

Um segredo do cliente é criado como uma configuração de aplicativo com slot autoadesiva denominada MICROSOFT_PROVIDER_AUTHENTICATION_SECRET. Você poderá atualizar essa configuração posteriormente para usar referências do Key Vault se quiser gerenciar o segredo no Azure Key Vault.

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

Qualquer um:

  • 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 comprovar sua identidade ao solicitar um token. Esse valor é salvo na configuração do aplicativo como uma configuração de aplicativo com slot autoadesiva denominada 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ícita do OAuth 2.0, o que não é recomendado.
    • URL do emissor, que assume o formulário <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://sts.windows.net" como seu ponto de extremidade de autenticação.

Caso precise criar manualmente um registro de aplicativo em um locatário da força de trabalho, siga o início rápido do registro de um aplicativo. Conforme você passa pelo processo de registro, observe a ID do aplicativo (cliente) e os valores de segredo do cliente.

Durante o processo de registro, na seção URIs de Redirecionamento, selecione Web para plataforma e tipo <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 tokens sejam solicitados para conceder o acesso. Ele é usado como um prefixo para os escopos que você cria.

    Para um aplicativo de locatário único, é possível usar o valor padrão que está no formato api://<application-client-id>. Você também pode especificar um URI mais acessí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 formatos aceitos para URIs de ID do Aplicativo, confira a referência de práticas recomendadas de registros de aplicativo.

  2. Selecione Adicionar um escopo.

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

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

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

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

Configurar as verificações adicionais

Configure as verificações adicionais, que determina quais solicitações têm permissão para acessar o aplicativo. Você poderá personalizar 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 o Requisito de aplicativo cliente, escolha se deseja:

  • Permitir solicitações somente deste próprio aplicativo
  • Permitir solicitações de aplicativos cliente específicos
  • Permitir solicitações de qualquer aplicativo (não recomendado)

Para o requisito de identidade, escolha se deseja:

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

Para requisitos de locatário, escolha se deseja:

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

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

Definir configurações de autenticação

Essas opções determinam como o aplicativo responde a solicitações não autenticadas e como as seleções padrão redirecionarão todas as solicitações para conectar esse novo provedor. Você pode alterar e 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 saber mais sobre essas opções, confira Fluxo de autenticação.

Para restringir o acesso, decida se deseja:

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

Para solicitações não autenticadas

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

Selecione Repositório de tokens (recomendado). O repositório de tokens coleta, armazena e atualiza tokens para o aplicativo. Você poderá desabilitar isso mais tarde se o aplicativo não precisar de tokens ou se precisar otimizar o desempenho.

Adicionar o provedor de identidade

Caso selecionou a configuração da força de trabalho, poderá selecionar Avançar: Permissões e adicionar as permissões do Microsoft Graph necessárias para o aplicativo. Eles serão adicionados ao registro do aplicativo, mas você também poderá alterá-los mais tarde. Caso 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 de Autenticação. A partir daí, você pode editar ou excluir essa configuração de provedor.

Para obter um exemplo de como configurar o logon do Microsoft Entra para um aplicativo Web que acessa o Armazenamento do Azure e o Microsoft Graph, confira este tutorial.

Autorizar solicitações

Por padrão, a Autenticação do Serviço de Aplicativo somente trata da autenticação, determinando se o chamador é quem ele diz ser. A autorização, determinando se o chamador deve ter acesso a algum recurso, é uma etapa extra além da autenticação. Você pode aprender mais sobre estes conceitos a partir de noções básicas de autorização na plataforma de identidade da Microsoft.

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

Dica

Os aplicativos multi-locatários devem validar a ID do emissor e do locatário da solicitação como parte deste processo para garantir que os valores sejam permitidos. Quando a Autenticação do Serviço de Aplicativo é configurada para um cenário multi-locatá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 em se a organização se inscreveu para o serviço, por exemplo. Consulte as Diretrizes de multi-locatário na plataforma de identidade da Microsoft.

Realizar validações a partir do código de aplicativo

Ao realizar verificações de autorização no código do aplicativo, você poderá 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 Base64 com as declarações invocadas sobre o chamador. Por padrão, estas declarações passam por um mapeamento de declarações, de modo que os nomes das declarações nem sempre correspondem ao que você veria no token. Por exemplo, a declaração tid é mapeada 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 x-ms-token-aad-access-token injetado.

Usar uma política de autorização integrada

O registro de aplicativo criado autentica as solicitações recebidas para seu locatário do Microsoft Entra. Por padrão, ele também permite que qualquer pessoa dentro do locatário tenha acesse ao 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. Entretanto, para cenários comuns, a plataforma de identidade da Microsoft fornece verificações integradas 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 de API, a configuração do provedor de identidade do Microsoft Entra tem uma seção validation que pode incluir um objeto defaultAuthorizationPolicy como na seguinte estrutura:

{
    "validation": {
        "defaultAuthorizationPolicy": {
            "allowedApplications": [],
            "allowedPrincipals": {
                "identities": []
            }
        }
    }
}
Propriedade Descrição
defaultAuthorizationPolicy Uma série de requisitos que precisam ser atendidos para acessar o aplicativo. O acesso é concedido com base em um AND lógico sobre cada uma de suas propriedades configuradas dele. Quando allowedApplications e allowedPrincipals estão configurados, a solicitação de entrada precisa atender aos dois requisitos para ser aceita.
allowedApplications Uma lista de permitidos de IDs de cliente de cadeia de caracteres do aplicativo que representam o recurso do cliente que está chamando o aplicativo. Quando essa propriedade é configurada como uma matriz não vazia, somente os tokens obtidos por um aplicativo especificado na lista são aceitos.

Essa política avalia a declaração appid ou azp do token de entrada, que precisa ser um token de acesso. Consulte a referência de declarações da plataforma de identidade da Microsoft.
allowedPrincipals Uma série de verificações que determinam se a entidade de segurança representada pela solicitação de entrada pode acessar o aplicativo. A satisfação de allowedPrincipals é baseada em um OR lógico aplicado sobre as propriedades configuradas dele.
identities (em allowedPrincipals) Uma lista de permitidos 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 requisito allowedPrincipals pode ser atendido se o usuário ou aplicativo representado pela solicitação é especificado na lista. Há um limite total de 500 caracteres na lista de públicos permitidos.

Essa política avalia a declaração oid 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 através de uma configuração de aplicativo, independentemente da versão da API que está sendo usada. A configuração do aplicativo WEBSITE_AUTH_AAD_ALLOWED_TENANTS pode ser configurada com uma lista separada por vírgulas de até 10 IDs de locatário (por exemplo, "aaaabbbb-0000-cccc-1111-dddd2222eeee") para exigir que o token de entrada seja de um dos locatários especificados, como especificado pela declaração tid. A configuração do aplicativo WEBSITE_AUTH_AAD_REQUIRE_CLIENT_SERVICE_PRINCIPAL pode ser configurada para "true" ou "1" para exigir que o token de entrada inclua uma declaração oid. Esta configuração é ignorada e tratada como true se allowedPrincipals.identities tiver sido configurado (uma vez que a declaração oid é verificada em relação a esta lista de identidades fornecida).

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

Configurar aplicativos do cliente para acessar o Serviço de Aplicativo

Nas seções anteriores, você registrou seu Serviço de Aplicativo ou Função do Azure para autenticar os 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 por seu Serviço de Aplicativo em nome dos usuários ou deles próprios, como em uma arquitetura de N camadas. Se você quiser apenas autenticar usuários, não será necessário concluir as etapas desta seção.

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 área de navegação à esquerda, selecione Registros de aplicativo>Novo registro.

  3. Na página Registrar um aplicativo, insira um Nome para o registro do seu aplicativo.

  4. Em URI de redirecionamento, selecione Cliente público (móvel e área de trabalho) e digite a URL <app-url>/.auth/login/aad/callback. Por exemplo, https://contoso.azurewebsites.net/.auth/login/aad/callback.

  5. Selecione Registrar.

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

    Observação

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

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

  8. Selecione o registro de aplicativo que você criou anteriormente para seu aplicativo do Serviço de Aplicativo. Se o registro do aplicativo não aparecer, verifique se você adicionou o escopo user_impersonation no registro do aplicativo.

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

Você já 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 de 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ções em nome do próprio aplicativo cliente (não em nome de um usuário). Esse cenário é útil para aplicativos daemon não interativos que executam tarefas sem um usuário conectado. Ele usa a concessão das credenciais de cliente padrão do OAuth 2.0.

  1. No menu do portal, selecione Microsoft Entra.
  2. Na área de navegação à esquerda, selecione Registros de aplicativo>Novo registro.
  3. Na página Registrar um aplicativo, insira um Nome para o registro do seu aplicativo.
  4. Em um aplicativo daemon, você não precisa de um URI de redirecionamento para que possa mantê-lo vazio.
  5. Selecione Registrar.
  6. Depois que o registro do aplicativo for criado, copie o valor da ID do aplicativo (cliente) .
  7. Na navegação à esquerda, selecione Certificados e segredos>Segredos do cliente>Novo segredo do cliente.
  8. Insira uma descrição, uma expiração, e selecione Adicionar.
  9. No campo Valor, copiar o valor do segredo do cliente. Ele não será mostrado novamente quando você navegar para fora desta página.

Agora você pode solicitar um token de acesso usando a ID e o segredo do cliente, definindo o parâmetro resource como o URI da ID do aplicativo de destino. O token de acesso resultante pode então 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 no seu locatário do Microsoft Entra solicite um token de acesso e faça a autenticação no aplicativo de destino. Se você também quiser impor autorização para permitir apenas determinados aplicativos cliente, deverá executar algumas configurações extras.

  1. Defina uma função de aplicativo no manifesto do registro do aplicativo que representa o Serviço de Aplicativo ou o aplicativo de Funções que você deseja proteger.
  2. No registro do aplicativo representando o cliente que precisa ser autorizado, selecione Permissões da API>Adicionar uma permissão>Minhas APIs.
  3. Selecione o registro de aplicativo que você criou anteriormente. Se você não vir o registro do aplicativo, verifique se adicionou uma Função de Aplicativo.
  4. Em Permissões de aplicativo, selecione a Função de Aplicativo que você criou anteriormente e, em seguida, selecione Adicionar permissões.
  5. Selecione Conceder consentimento de administração para autorizar o aplicativo cliente a solicitar a permissão.
  6. Semelhante ao cenário anterior (antes de qualquer função ter sido adicionada), agora você pode solicitar um token de acesso para o mesmo resource de destino, e o token de acesso incluirá uma declaração de roles contendo as Funções de Aplicativo autorizadas para o aplicativo cliente.
  7. Dentro do Serviço de Aplicativo de destino ou do código do Aplicativo de Funções, você pode agora validar que as funções esperadas estão presentes no token (isto não é realizado pela autenticação do Serviço de Aplicativo). Para mais informações, consulte Acessar declarações de usuário.

Você já configurou um aplicativo cliente daemon que pode acessar seu aplicativo do Serviço de Aplicativo usando uma identidade própria.

Práticas recomendadas

Independentemente da configuração usada para definir a autenticação, as seguintes melhores práticas manterem seu locatário e seus aplicativos mais seguros:

  • Configure cada aplicativo do Serviço de Aplicativo com seu próprio registro no Microsoft Entra.
  • Dê a cada aplicativo do Serviço de Aplicativo suas próprias permissões e consentimento.
  • Evite o compartilhamento de permissão entre ambientes usando registros de aplicativo separados para slots de implantação separados. Essa prática pode ajudar a evitar problemas que afetam o aplicativo de produção durante o teste do novo código.

Migre 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á programado para ser totalmente desativado. Por exemplo, o código do seu aplicativo pode ter chamado o Azure AD Graph para verificar a associação de grupo como parte de um filtro de autorização em um pipeline de middleware. Os aplicativos devem migrar para o Microsoft Graph seguindo as diretrizes fornecidas pelo Microsoft Entra como parte do processo de substituição do Azure AD Graph. Ao seguir essas instruções, talvez seja necessário fazer algumas alterações em sua configuração de autenticação do Serviço de Aplicativo. Depois de adicionar as permissões do Microsoft Graph ao registro do seu aplicativo, você poderá:

  1. Atualizar o URL do emissor para incluir o sufixo "/v2.0", caso ainda não o tenha feito.

  2. Remover as solicitações de permissões do Azure AD Graph de sua configuração de logon. 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 matriz additionalLoginParams.
    • Se você estiver usando a API V2 (/authsettingsV2), isso estará na matriz loginParameters.

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

    Também seria necessário atualizar a configuração para solicitar as novas permissões do Microsoft Graph que você definiu 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 de logon scope=openid profile email https://graph.microsoft.com/.default.

Com essas alterações, quando a Autenticação do Serviço de Aplicativo tenta fazer logon, 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 aplicativo também precisaria ser atualizado, de acordo com as diretrizes fornecidas pelo Microsoft Entra.

Próximas etapas