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, os aplicativos do Serviço de Aplicativo recém-criados podem gerar um nome de host padrão exclusivo que usa a convenção de nomenclatura <app-name>-<random-hash>.<region>.azurewebsites.net. Os nomes de aplicativos existentes permanecem inalterados. Por exemplo:

myapp-ds27dh7271aah175.westus-01.azurewebsites.net

Para obter mais informações, confira Nome do host padrão exclusivo para o recurso do 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, 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 Configurações>Autenticação e escolha Adicionar o 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. Em Escolher um locatário para seu aplicativo e seus usuários, selecione Configuração da força de trabalho (locatário atual) para funcionários e convidados corporativos 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 cria 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.

Você pode criar e usar um novo registro de aplicativo (opção 1) ou usar um registro existente criado separadamente (opção 2).

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 de criá-lo.

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.

  1. Selecione Criar novo registro de aplicativo.

  2. Insira o Nome do novo registro do aplicativo.

  3. 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. Essas contas incluem escolas e 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. Se quiser gerenciar o segredo no Azure Key Vault, atualize essa configuração mais tarde para usar as referências do Key Vault.

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

Selecione:

  • Escolha um registro de aplicativo existente neste diretório e selecione um registro de aplicativo na lista suspensa.

  • Forneça os detalhes de um registro de aplicativo existente e forneça:

    • ID do aplicativo (do 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 usa 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.

Se você precisar criar manualmente um registro de aplicativo em um locatário da força de trabalho, confira Registrar um aplicativo com a plataforma de identidade da Microsoft. 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, o que permite que tokens sejam solicitados para conceder o acesso. O valor é 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 obter mais informações sobre os formatos aceitos para os URIs da ID do Aplicativo, confira as Melhores práticas de segurança para as propriedades de aplicativo no Microsoft Entra ID.

  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. Insira o nome do escopo de consentimento. Insira uma descrição que você quer 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. Depois que você navegar para longe dessa página, ela não aparecerá novamente.

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

Configurar as verificações adicionais

As verificações adicionais determinam quais solicitações têm permissão para acessar seu 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 outras decisões de autorização 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 responderá às solicitações não autenticadas. As seleções padrão redirecionam todas as solicitações para entrar com 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 obter mais informações, consulte 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ê pode desabilitar esse comportamento 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. Essas permissões são adicionadas ao registro do aplicativo, mas você também poderá alterá-las 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 está listado na tela Autenticação. A partir daí, você pode editar ou excluir essa configuração de provedor.

Para obter um exemplo de como configurar a entrada do Microsoft Entra para um aplicativo Web que acessa o Armazenamento do Azure e o Microsoft Graph, confira Adicionar a autenticação de aplicativo ao seu aplicativo Web.

Autorizar solicitações

Por padrão, a Autenticação do Serviço de Aplicativo manipula apenas a autenticação. Ela determina se o chamador é quem eles dizem que são. A autorização, determinando se o chamador deve ter acesso a algum recurso. É uma etapa além da autenticação. Para obter mais informações, confira Noções básicas de autorização.

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 por si só podem não ser suficientes para cobrir as necessidades de autorização de seu aplicativo.

Dica

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 em se a organização se inscreveu para o serviço, por exemplo. Confira Atualizar seu código para lidar com vários valores de emissor.

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. Para mais informações, confira Acessar as declarações de usuário no código do aplicativo.

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, essas declarações passam por um mapeamento de declarações, portanto, os nomes da declaração podem nem sempre corresponder 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 acesse o aplicativo. Essa abordagem é adequada para muitos aplicativos. 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 é usando os modelos do Azure Resource Manager ou a 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 Um grupo de requisitos que deve ser atendido 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 do aplicativo de cadeia de caracteres que representam o recurso do cliente que chama 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. Confira as Declarações de conteúdo.
allowedPrincipals Um grupo 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 da cadeia de caracteres que representam os 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. Confira as Declarações de conteúdo.

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 WEBSITE_AUTH_AAD_ALLOWED_TENANTS do aplicativo pode ser configurada com uma lista separada por vírgulas de até 10 IDs de locatário, por exemplo, aaaabbbb-0000-cccc-1111-dddd2222eeee.

Essa configuração pode exigir que o token de entrada seja de um dos locatários especificados, conforme especificado na declaração tid. A configuração do aplicativo WEBSITE_AUTH_AAD_REQUIRE_CLIENT_SERVICE_PRINCIPAL pode ser configurada como true ou 1 para exigir que o token de entrada inclua uma declaração oid. Se allowedPrincipals.identities tiver sido configurado, essa configuração será ignorada e tratada como verdadeira porque a declaração oid será verificada em relação a essa 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 os clientes nativos ou aplicativos daemon no Microsoft Entra. Eles podem solicitar acesso a APIs expostas pelo Serviço de Aplicativo em nome de usuários ou de si mesmos, como em uma arquitetura de N camadas. Se você quiser autenticar apenas os usuários, as etapas nesta seção não serão necessárias.

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 ID.

  2. Na navegação à esquerda, selecione Gerenciar>Registros de aplicativo e, em seguida, selecione 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/nativo (móvel e área de trabalho) e digite o 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 navegação à esquerda, selecione Gerenciar>permissões de API. Em seguida, selecione 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ê 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. Para saber mais, confira a plataforma de identidade da Microsoft e o fluxo de credenciais do cliente OAuth 2.0.

  1. No portal do Azure, selecione Microsoft Entra ID.
  2. Na navegação à esquerda, selecione Gerenciar>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 Gerenciar>Certificados e segredos. Em seguida, selecione Segredos>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. Depois que você navegar para longe dessa página, ela não aparecerá novamente.

Agora você pode solicitar um token de acesso usando a ID do cliente e o segredo do cliente. Defina o parâmetro resource como o URI da ID do aplicativo 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. A autenticação do Serviço de Aplicativo valida e usa o token como de costume para agora indicar que o chamador está autenticado. Nesse caso, o chamador é um aplicativo, não um usuário.

Essa abordagem 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 autorização para permitir apenas determinados aplicativos cliente, deverá executar 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ê quer proteger.

  2. No registro do aplicativo que representa 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 de 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. Em seguida, selecione Adicionar permissões.

  5. Selecione Conceder consentimento de administração para autorizar o aplicativo cliente a solicitar a permissão.

    Semelhante ao cenário anterior (antes de quaisquer funções serem adicionadas), agora você pode solicitar um token de acesso para o mesmo destino resource, e o token de acesso inclui uma roles declaração contendo as funções do aplicativo que foram autorizadas para o aplicativo cliente.

No código do Aplicativo de funções ou Serviço de Aplicativo de destino, agora você pode validar se as funções esperadas estão presentes no token. A autenticação do Serviço de Aplicativo não executa essa validação. Para mais informações, consulte Acessar declarações de usuário.

Você 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ões entre ambientes. Use os registros de aplicativo separados para os 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 podem ser 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 chamar 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 ser movidos para o Microsoft Graph. Para obter mais informações, confira Migrar seus aplicativos do Azure AD Graph para o Microsoft Graph.

Durante essa migração, talvez seja necessário fazer algumas alterações na configuração da 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), essa configuração estará na matriz additionalLoginParams.
    • Se você estiver usando a API V2 (/authsettingsV2), essa configuração estará na matriz loginParameters.

    Você precisa remover qualquer referência a https://graph.windows.net, por exemplo. Essa alteração inclui o parâmetro resource, que não é compatível com o ponto de extremidade /v2.0 ou os escopos que você solicitar especificamente que sejam do Azure AD Graph.

    Você também precisa 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 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 entrar, ela não solicitará mais permissões para o Azure AD Graph. Ela obterá um token para o Microsoft Graph. Qualquer uso desse token no código do seu aplicativo também precisa ser atualizado, conforme descrito em Migrar seus aplicativos do Azure AD Graph para o Microsoft Graph.

Próximas etapas