Partilhar via


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

Nota

A partir de 1º de junho de 2024, os aplicativos do Serviço de Aplicativo recém-criados poderão gerar um nome de host padrão exclusivo que use a convenção <app-name>-<random-hash>.<region>.azurewebsites.netde nomenclatura. Os nomes de aplicativos existentes permanecem inalterados. Por 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 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 de Definições> 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. Em Escolha 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 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 cria 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.

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

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.

  1. Selecione Criar novo registro de aplicativo.

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

  3. 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. Estas contas incluem escolas e empresas que utilizam 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. Se quiser gerenciar o segredo no Cofre da Chave do Azure, você pode atualizar essa configuração posteriormente para usar as referências do Cofre da Chave.

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

Selecione uma das seguintes opções:

  • 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 (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ícita 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://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, consulte Registrar um aplicativo com a plataforma de identidade da Microsoft. 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, o que permite que tokens sejam solicitados para conceder acesso. O valor é 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 obter mais informações sobre formatos aceitos para URIs de ID de aplicativo, consulte Práticas recomendadas de segurança para propriedades de aplicativo no Microsoft Entra ID.

  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. Insira o nome do escopo de consentimento. Insira uma descrição 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. Depois de sair desta página, ela não aparece novamente.
  4. (Opcional) Para adicionar vários URLs de resposta, selecione Autenticação.

Configurar verificações adicionais

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 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 outras decisões de autorização 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. As seleções padrão redirecionam 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 obter mais informaçõ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 desabilitar esse comportamento 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. Essas permissões são adicionadas ao registro do aplicativo, mas você também pode alterá-las 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 está 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 Adicionar autenticação de aplicação à sua aplicação Web.

Autorizar pedidos

Por padrão, a Autenticação do Serviço de Aplicativo lida apenas com a autenticação. Determina se o autor da chamada é quem diz ser. A autorização, que determina se esse chamador deve ter acesso a algum recurso, é um passo além da autenticação. Para obter mais informações, consulte Noções básicas de autorização.

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

Gorjeta

Os aplicativos multilocatários devem validar o emissor e o ID 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 no serviço, por exemplo. Consulte Atualizar seu código para lidar com vários valores de emissor.

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

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. Essa abordagem é boa 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. 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 é usando modelos do Azure Resource Manager ou a 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 grupo 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 chama o aplicativo. Quando essa propriedade é configurada como uma matriz não vazia, somente tokens obtidos por um aplicativo especificado na lista são aceitos.

Esta política avalia a appid ou azp declaração do token de entrada, que deve ser um token de acesso. Consulte Declarações de carga útil.
allowedPrincipals Um grupo de verificações que determinam 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 representa 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 Declarações de carga útil.

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, aaaabbbb-0000-cccc-1111-dddd2222eeee.

Essa configuração pode 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 para true ou 1 para exigir que o token de entrada inclua uma oid declaração. Se allowedPrincipals.identities tiver sido configurada, essa configuração será ignorada e tratada como verdadeira porque 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. Eles podem solicitar acesso às APIs expostas pelo seu Serviço de Aplicativo em nome dos usuários ou deles mesmos, como em uma arquitetura de N camadas. Se você quiser apenas autenticar usuários, as etapas nesta seção não sã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 Gerir>registos de aplicações e, em seguida, selecione 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/nativo (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 Gerenciar>permissões de API. Em seguida, selecione 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 adiciona o âmbito user_impersonation no registo da aplicação.

  9. Em Permissões delegadas, selecione user_impersonation e, em seguida, selecione 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 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. Para obter mais informações, consulte Plataforma de identidade da Microsoft e o fluxo de credenciais do cliente OAuth 2.0.

  1. No menu do portal do Azure, selecione Microsoft Entra ID.
  2. Na navegação à esquerda, selecione Gerenciar>registros de>aplicativos Novo registro.
  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 Gerenciar>certificados & segredos. Em seguida, selecione 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. Depois de sair desta página, ela não aparece 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 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. A autenticação do Serviço de Aplicativo valida e usa o token como de costume para indicar agora que o chamador está autenticado. Neste 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, você deve executar a configuração extra.

  1. Defina uma Função de Aplicativo no manifesto do registro do aplicativo que representa o Aplicativo de 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 que você criou anteriormente. Em seguida, selecione Adicionar permissões.

  5. Certifique-se de selecionar Conceder consentimento de administrador 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 resourcee o token de acesso inclui uma roles declaração contendo as Funções de Aplicativo que foram autorizadas para o aplicativo cliente.

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. A autenticação do Serviço de Aplicativo não executa essa validação. Para obter 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 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 o compartilhamento de permissões entre ambientes. Use registros de aplicativos separados para slots de implantaçã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 podem ser 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 chamar 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. Para obter mais informações, consulte 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 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), essa configuração estará na additionalLoginParams matriz.
    • Se você estiver usando a API V2 (/authsettingsV2), essa configuração estará na loginParameters matriz.

    Você precisa remover qualquer referência a https://graph.windows.net, por exemplo. Essa alteração inclui o resource parâmetro, que não é suportado /v2.0 pelo ponto de extremidade, ou quaisquer escopos solicitados 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 scope=openid profile email https://graph.microsoft.com/.defaultde entrada .

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, ele recebe um token para o Microsoft Graph. Qualquer uso desse token do código do seu aplicativo também precisa ser atualizado, conforme descrito em Migrar seus aplicativos do Azure AD Graph para o Microsoft Graph.

Passos seguintes