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

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 um locatário de força de trabalho ou um 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 acesse seu aplicativo do Serviço de Aplicativo ou aplicativo do Functions.

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 valor do provedor de identidade para fazer login nas identidades Microsoft e 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
   • Configuração externa para consumidores e clientes corporativos

Escolha o registro do aplicativo

O recurso de 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 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 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ê quer usar um registro de aplicativo de um locatário do Microsoft Entra diferente daquele no qual seu aplicativo está contido. Esse é sempre o caso se você selecionou a configuração externa quando escolheu um locatário.
• A opção de criar um registro não está disponível para nuvens governamentais.

Configurar as verificações adicionais

As verificações adicionais 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 página de Autenticação principal selecionando Editar ao lado das configurações de Autenticação.

Para o Requisito de aplicativo cliente, escolha se deseja:

• Permitir solicitações somente desse 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:

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

Para requisitos de locatário, escolha se deseja:

• Permita apenas solicitações do mesmo locatário do registro do aplicativo.
• Permitir solicitações de locatários específicos.
• Use restrições padrão com base no inquilino do registro do aplicativo.

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 mais adiante neste artigo.

Defina as configurações de autenticação

As configurações de autenticação determinam como seu aplicativo responde a solicitações não autenticadas. As seleções padrão redirecionam todas as solicitações para entrar com esse novo provedor. Você pode personalizar esse comportamento agora ou ajustar essas configurações posteriormente na página de Autenticação principal selecionando Editar ao lado das 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 acesso não autenticado.

Para solicitações não autenticadas, escolha opções de erro:

• HTTP 302 Found redirect: recomendado para sites
• HTTP 401 Unauthorized: recomendado para APIs
• HTTP 403 Forbidden
• HTTP 404 Not found

Selecione Repositório de tokens (recomendado). O repositório de tokens coleta, armazena e atualiza tokens para o aplicativo. Você poderá desabilitar esse comportamento mais tarde se o aplicativo não precisar de tokens ou se 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 as permissões do Microsoft Graph de que o aplicativo precisa. 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 página 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 internas, o que pode ajudar, mas elas por si só podem não ser suficientes para atender às necessidades de autorização do seu aplicativo. As seções a seguir abrangem esses recursos.

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 validation seção que pode incluir um defaultAuthorizationPolicy objeto, conforme mostrado na seguinte estrutura:

{
    "validation": {
        "defaultAuthorizationPolicy": {
            "allowedApplications": [],
            "allowedPrincipals": {
                "identities": []
            }
        }
    }
}

Além disso, você pode configurar algumas verificações por meio de uma configuração de aplicativo, independentemente da versão da API que você está usando. Você pode definir a configuração do WEBSITE_AUTH_AAD_ALLOWED_TENANTS aplicativo 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.

Você pode definir a configuração do aplicativo WEBSITE_AUTH_AAD_REQUIRE_CLIENT_SERVICE_PRINCIPAL como true ou 1 para exigir que o token de entrada inclua uma declaração oid. Se você tiver configurado allowedPrincipals.identities, essa configuração será ignorada e tratada como verdadeira porque a oid declaração é verificada em relação a essa lista de identidades fornecida.

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

Usar uma identidade gerenciada em vez de um segredo (versão prévia)

Em vez de configurar um segredo do cliente para o registro do aplicativo, você pode configurar um aplicativo para confiar em uma identidade gerenciada. Usar uma identidade em vez de um segredo significa que você não precisa gerenciar um segredo. Você não tem eventos de expiração secretos para lidar e não tem o mesmo nível de risco associado a possivelmente divulgar ou vazar esse segredo.

A identidade permite que você crie uma credencial de identidade federada, que pode ser usada em vez de um segredo do cliente como uma declaração de cliente. Essa abordagem está disponível apenas para configurações de força de trabalho. O recurso de autenticação integrado atualmente dá suporte a credenciais de identidade federadas como uma prévia.

Você pode usar as etapas nesta seção para configurar seu recurso do Serviço de Aplicativo ou do Azure Functions para usar esse padrão. As etapas aqui pressupõem que você já configurou um registro de aplicativo usando um dos métodos com suporte e que você já tem um segredo definido.

1. Crie um recurso de identidade gerenciado atribuído pelo usuário de acordo com estas instruções.

2. Atribua essa identidade ao seu serviço de aplicativo ou ao recurso do Azure Functions.

   Importante

   A identidade gerenciada atribuída pelo usuário que você cria só deve ser atribuída ao Serviço de Aplicativo ou ao aplicativo do Azure Functions por meio desse registro. Se você atribuir a identidade a outro recurso, você está dando a esse recurso acesso desnecessário ao registro do aplicativo.

3. Anote os valores da ID do objeto e da ID do cliente da identidade gerenciada. Você precisará da ID do objeto para criar uma credencial de identidade federada na próxima etapa. Você usará a ID do cliente da identidade gerenciada em uma etapa posterior.

4. Siga as instruções da ID do Microsoft Entra para configurar uma credencial de identidade federada em um aplicativo existente. Essas instruções também incluem seções para atualizar o código do aplicativo, que você pode ignorar.

5. Adicionar uma nova configuração de aplicativo chamada OVERRIDE_USE_MI_FIC_ASSERTION_CLIENTID. Defina o valor da ID do Cliente da identidade gerenciada que você obteve em uma etapa anterior. Não use a ID do cliente do registro do aplicativo. Marque essa configuração de aplicativo como de slot fixo.

6. Nas configurações de autenticação internas para o recurso de aplicativo, defina o nome da configuração do segredo do cliente como OVERRIDE_USE_MI_FIC_ASSERTION_CLIENTID.

   Para fazer essa alteração usando o portal do Azure:

   1. Volte para o serviço de aplicativo ou o recurso do Azure Functions e selecione a guia Autenticação .
   2. Na seção Provedor de identidade , para a entrada da Microsoft , selecione o ícone na coluna Editar .
   3. Na caixa de diálogo Editar provedor de identidade, abra a lista suspensa para o Nome da configuração do segredo do cliente e selecione OVERRIDE_USE_MI_FIC_ASSERTION_CLIENTID.
   4. Clique em Salvar.

   Para fazer essa alteração usando a API REST:

   • Defina a propriedade clientSecretSettingName como OVERRIDE_USE_MI_FIC_ASSERTION_CLIENTID. Você pode encontrar essa propriedade em properties>identityProviders>azureActiveDirectory>registration.

7. Verifique se o aplicativo funciona conforme o esperado. Você deve ser capaz de realizar com sucesso um novo login.

Quando estiver satisfeito com o comportamento usando uma identidade gerenciada, remova o segredo existente:

1. Verifique se o código do aplicativo não depende da configuração do aplicativo. Se isso acontecer, siga as instruções para atualizar o código do aplicativo para solicitar um token de acesso.

2. Remova a configuração do aplicativo que anteriormente mantinha seu segredo. O nome dessa configuração de aplicativo é o valor de nome da configuração do segredo do cliente anterior, antes de defini-lo como OVERRIDE_USE_MI_FIC_ASSERTION_CLIENTID.

3. Entre no Centro de administração do Microsoft Entra usando o locatário que contém o registro do aplicativo. Vá para o registro do aplicativo novamente.

4. Em Certificados &segredos, selecione segredos do cliente e remova o segredo do cliente.

Seu aplicativo agora está configurado para usar a autenticação da ID do Microsoft Entra sem segredos.

Configurar aplicativos cliente para acessar o Serviço de Aplicativo

Em seções anteriores, você registrou seu Serviço de Aplicativo ou aplicativo do Azure Functions para autenticar usuários. As seções a seguir explicam como registrar clientes nativos ou aplicativos daemon no Microsoft Entra. Esses clientes ou aplicativos 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 nas seções a seguir 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 do Azure, selecione a ID do Microsoft Entra.

2. No painel esquerdo, selecione Gerenciar>registros de aplicativo. Em seguida, selecione Novo registro.

3. No painel Registrar um aplicativo , para Nome, insira um nome para o registro do aplicativo.

4. No URI de Redirecionamento, selecione Cliente público/nativo (móvel &desktop) e insira a URL de redirecionamento. Por exemplo, digite 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. No painel esquerdo, selecione Gerenciar>permissões de API. Em seguida, selecione Adicionar uma permissão>Minhas APIs.

8. Selecione o registro de aplicativo criado 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 nele.

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

Agora você configurou um aplicativo cliente nativo que pode solicitar acesso ao 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 um aplicativo do Azure Functions 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 de 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 menu do portal do Azure, selecione a ID do Microsoft Entra.

2. No painel esquerdo, selecione Gerenciar>registros de aplicativo. Em seguida, selecione Novo registro.

3. No painel Registrar um aplicativo , para Nome, insira um nome para o registro do aplicativo.

4. Para um aplicativo daemon, você não precisa de um URI de redirecionamento, portanto, você pode manter a caixa de URI de redirecionamento vazia.

5. Selecione Registrar.

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

7. No painel esquerdo, selecione Gerenciar>Certificados > segredos. Em seguida, selecione Segredos>Novo segredo do cliente.

8. Insira uma descrição e expiração e selecione Adicionar.

9. No campo Valor, copiar o valor do segredo do cliente. Depois que você se afastar 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 resource parâmetro como o valor URI de ID do aplicativo de destino. O token de acesso resultante pode ser apresentado ao aplicativo de destino por meio do cabeçalho de Autorização OAuth 2.0 padrão. A autenticação do Serviço de Aplicativo valida e usa o token para 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 a autorização para permitir apenas determinados aplicativos cliente, deverá executar uma configuração extra.

1. Defina uma função de aplicativo no manifesto do registro do aplicativo que representa o Serviço de Aplicativo ou o aplicativo do Azure Functions que você deseja 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 você 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 do administrador para autorizar o aplicativo cliente a solicitar a permissão.

   Semelhante ao cenário anterior (antes de adicionar qualquer função), agora você pode solicitar um token de acesso para o mesmo recurso de destino. O token de acesso inclui uma roles declaração que contém as funções de aplicativo que foram autorizadas para o aplicativo cliente.

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

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

Práticas recomendadas

Independentemente da configuração que você usa 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 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. Quando você está testando um novo código, essa prática pode ajudar a evitar que problemas afetem o aplicativo de produção.

Migrar para o Microsoft Graph

Alguns aplicativos mais antigos podem ser configurados com uma dependência do Azure AD Graph, que está obsoleto e programado para a retirada completa. 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á:

• Atualize o valor da URL do Emissor para incluir o /v2.0 sufixo se ainda não o fizer.

• Remova as solicitações de permissões do Azure AD Graph da 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), 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 resource parâmetro, que o /v2.0 endpoint não dá suporte. Ele também inclui todos os escopos que você solicita especificamente que são do Azure AD Graph.

  Você também precisa atualizar a configuração para solicitar as novas permissões do Microsoft Graph que você configurou para o registro do aplicativo. Em muitos casos, você pode usar o escopo padrão para simplificar essa configuração. Para fazer isso, adicione um novo parâmetro de entrada: 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 solicita mais permissões para o Azure AD Graph. Em vez disso, 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.

Conteúdo relacionado

• Autenticação e autorização no Serviço de Aplicativo do Azure e no Azure Functions
• Tutorial: Autenticar e autorizar usuários de ponta a ponta no Serviço de Aplicativo do Azure

• Início Rápido: Adicionar autenticação de aplicativo ao aplicativo Web em execução no Serviço de Aplicativo do Azure