Converter aplicativo de locatário único em multilocatário no Microsoft Entra ID

  • Artigo

Se você oferecer um aplicativo SaaS (Software as a Service) para muitas organizações, poderá configurar seu aplicativo para aceitar entradas de qualquer locatário do Microsoft Entra convertendo-o em multilocatário. Os usuários em qualquer locatário do Microsoft Entra poderão entrar em seu aplicativo depois de consentirem em usar sua conta com seu aplicativo.

Para aplicativos existentes com seu próprio sistema de conta (ou outros logins de outros provedores de nuvem), você deve adicionar código de login via OAuth2, OpenID Connect ou SAML e colocar um botão "Entrar com a Microsoft" em seu aplicativo.

Neste guia de instruções, você realizará as quatro etapas necessárias para converter um aplicativo de locatário único em um aplicativo multilocatário Microsoft Entra:

  1. Atualize seu registro de aplicativo para ser multilocatário
  2. Atualize seu código para enviar solicitações ao ponto de /common extremidade
  3. Atualize seu código para lidar com vários valores de emissor
  4. Compreender o consentimento do usuário e do administrador e fazer as alterações de código apropriadas

Se você quiser tentar usar um de nossos exemplos, consulte Criar um aplicativo Web SaaS multilocatário que chama o Microsoft Graph usando o Microsoft Entra ID e o OpenID Connect

Pré-requisitos

Atualizar o registro para ser multilocatário

Por padrão, os registros de aplicativo Web/API no Microsoft Entra ID são de locatário único após a criação. Para tornar o registo multiinquilino, inicie sessão no centro de administração do Microsoft Entra e selecione o registo da aplicação que pretende atualizar. Com o registro do aplicativo aberto, selecione o painel Autenticação e navegue até a seção Tipos de conta suportados. Altere a configuração para Contas em qualquer diretório organizacional.

Quando um aplicativo de locatário único é criado no centro de administração do Microsoft Entra, um dos itens listados na página Visão geral é o URI da ID do aplicativo. Esta é uma das maneiras pelas quais um aplicativo é identificado em mensagens de protocolo e pode ser adicionado a qualquer momento. O URI da ID do Aplicativo para aplicativos de locatário único pode ser globalmente exclusivo dentro desse locatário. Por outro lado, para aplicativos multilocatário, ele deve ser globalmente exclusivo em todos os locatários, o que garante que o Microsoft Entra ID possa encontrar o aplicativo em todos os locatários.

Por exemplo, se o nome do seu locatário fosse contoso.onmicrosoft.com um URI de ID de Aplicativo válido, seria https://contoso.onmicrosoft.com/myapp. Se o URI da ID do aplicativo não seguir esse padrão, a configuração de um aplicativo como multilocatário falhará.

Atualize seu código para enviar solicitações para /common

Com um aplicativo multilocatário, o aplicativo não pode dizer imediatamente de qual locatário o usuário é, portanto, as solicitações não podem ser enviadas para o ponto de extremidade de um locatário. Em vez disso, as solicitações são enviadas para um ponto de extremidade comum (https://login.microsoftonline.com/common) que atende a todos os locatários do Microsoft Entra, atuando como um hub central que lida com solicitações.

Abra seu aplicativo no IDE, edite seu código e altere o valor do ID do locatário para /common. Este ponto de extremidade não é um locatário ou um emissor em si. Quando a plataforma de identidade da Microsoft recebe uma solicitação no /common ponto de extremidade, ela entra no usuário, descobrindo assim de qual locatário o usuário é. Este ponto de extremidade funciona com todos os protocolos de autenticação suportados pelo ID do Microsoft Entra (OpenID Connect, OAuth 2.0, SAML 2.0, WS-Federation).

Em seguida, a resposta de início de sessão à aplicação contém um token que representa o utilizador. O valor do emissor no token informa a um aplicativo de qual locatário o usuário é. Quando uma resposta retorna do /common ponto de extremidade, o valor do emissor no token corresponde ao locatário do usuário.

Nota

Existem, na realidade, 2 autoridades para aplicações multilocatário:

  • https://login.microsoftonline.com/common para aplicativos que processam contas em qualquer diretório organizacional (qualquer diretório do Microsoft Entra) e contas pessoais da Microsoft (por exemplo, Skype, XBox).
  • https://login.microsoftonline.com/organizations para aplicativos que processam contas em qualquer diretório organizacional (qualquer diretório do Microsoft Entra):

As explicações neste documento usam common. Mas você pode substituí-lo por organizations se seu aplicativo não oferecer suporte a contas pessoais da Microsoft.

Atualize seu código para lidar com vários valores de emissor

Aplicativos Web e APIs da Web recebem e validam tokens da plataforma de identidade da Microsoft. Os aplicativos cliente nativos não validam tokens de acesso e devem tratá-los como opacos. Em vez disso, eles solicitam e recebem tokens da plataforma de identidade da Microsoft e o fazem para enviá-los para APIs, onde são validados.

Os aplicativos multilocatários devem executar mais verificações ao validar um token. Um aplicativo multilocatário é configurado para consumir metadados de chaves ou /common URLs de /organizations chaves. O aplicativo deve validar se a issuer propriedade nos metadados publicados corresponde à iss declaração no token, além da verificação usual de que a iss declaração no token contém a declaração de ID do locatário (tid). Para obter mais informações, consulte Validar tokens.

Para um usuário entrar em um aplicativo no Microsoft Entra ID, o aplicativo deve ser representado no locatário do usuário. Isso permite que a organização faça coisas como aplicar políticas exclusivas quando os usuários de seu locatário entrarem no aplicativo. Para um aplicativo de locatário único, pode-se usar o registro por meio do centro de administração do Microsoft Entra.

Para um aplicativo multilocatário, o registro inicial para o aplicativo reside no locatário do Microsoft Entra usado pelo desenvolvedor. Quando um usuário de um locatário diferente entra no aplicativo pela primeira vez, o ID do Microsoft Entra solicita que ele concorde com as permissões solicitadas pelo aplicativo. Se eles consentirem, uma representação do aplicativo chamada entidade de serviço será criada no locatário do usuário e o login poderá continuar. Uma delegação também é criada no diretório que registra o consentimento do usuário para o aplicativo. Para obter detalhes sobre os objetos Application e ServicePrincipal do aplicativo e como eles se relacionam entre si, consulte Objetos de aplicativo e objetos de entidade de serviço.

Diagrama que ilustra o consentimento de um usuário para um aplicativo de camada única.

Essa experiência de consentimento é afetada pelas permissões solicitadas pelo aplicativo. A plataforma de identidade da Microsoft suporta dois tipos de permissões;

  • Delegado: essa permissão concede a um aplicativo a capacidade de agir como um usuário conectado para um subconjunto das coisas que o usuário pode fazer. Por exemplo, você pode conceder a um aplicativo a permissão delegada para ler o calendário do usuário conectado.
  • Somente aplicativo: essa permissão é concedida diretamente à identidade do aplicativo. Por exemplo, você pode conceder a um aplicativo a permissão somente aplicativo para ler a lista de usuários em um locatário, independentemente de quem está conectado ao aplicativo.

Algumas permissões podem ser consentidas por um usuário comum, enquanto outras exigem o consentimento de um administrador de locatário.

Para saber mais sobre o consentimento de usuário e administrador, consulte Configurar o fluxo de trabalho de consentimento de administrador.

As permissões somente de aplicativo sempre exigem o consentimento de um administrador de locatário. Se o seu aplicativo solicitar uma permissão somente para o aplicativo e um usuário tentar entrar no aplicativo, uma mensagem de erro será exibida informando que o usuário não pode consentir.

Algumas permissões delegadas também requerem o consentimento de um administrador de locatário. Por exemplo, a capacidade de gravar novamente no Microsoft Entra ID como o usuário conectado requer o consentimento de um administrador de locatário. Como as permissões somente para aplicativos, se um usuário comum tentar entrar em um aplicativo que solicita uma permissão delegada que requer o consentimento do administrador, o aplicativo receberá um erro. Se uma permissão requer consentimento do administrador é determinado pelo desenvolvedor que publicou o recurso e pode ser encontrado na documentação do recurso. A documentação de permissões para a API do Microsoft Graph indica quais permissões exigem o consentimento do administrador.

Se seu aplicativo usa permissões que exigem o consentimento do administrador, considere adicionar um botão ou link onde o administrador possa iniciar a ação. A solicitação que seu aplicativo envia para essa ação é a usual solicitação de autorização OAuth2/OpenID Connect que também inclui o prompt=consent parâmetro query string. Depois que o administrador consentir e a entidade de serviço for criada no locatário do cliente, as solicitações de entrada subsequentes não precisarão do prompt=consent parâmetro. Como o administrador decidiu que as permissões solicitadas são aceitáveis, nenhum outro usuário no locatário será solicitado a dar o seu consentimento a partir desse ponto.

Um administrador de locatário pode desabilitar a capacidade de usuários comuns consentirem com aplicativos. Se esse recurso estiver desativado, o consentimento do administrador será sempre necessário para que o aplicativo seja usado no locatário. Pode testar a sua aplicação com o consentimento do utilizador final desativado, no centro de administração do Microsoft Entra. Em Consentimento e permissões de aplicativos>corporativos, marque a opção Não permitir consentimento do usuário.

O prompt=consent parâmetro também pode ser usado por aplicativos que solicitam permissões que não exigem consentimento do administrador. Um exemplo de quando isso seria usado é se o aplicativo requer uma experiência em que o administrador do locatário "se inscreve" uma vez e nenhum outro usuário é solicitado a dar consentimento a partir desse ponto.

Se um aplicativo exigir o consentimento do administrador e um administrador entrar sem que o prompt=consent parâmetro seja enviado, quando o administrador consentir com êxito com o aplicativo, ele será aplicado apenas para sua conta de usuário. Os utilizadores regulares continuarão a não conseguir iniciar sessão ou consentir a aplicação. Esse recurso é útil se você quiser dar ao administrador do locatário a capacidade de explorar seu aplicativo antes de permitir o acesso de outros usuários.

Seu aplicativo pode ter várias camadas, com cada uma representada por seu próprio registro no Microsoft Entra ID. Por exemplo, um aplicativo nativo que chama uma API da Web ou um aplicativo da Web que chama uma API da Web. Em ambos os casos, o cliente (aplicativo nativo ou aplicativo Web) solicita permissões para chamar o recurso (API da Web). Para que o cliente seja consentido com êxito no locatário de um cliente, todos os recursos para os quais ele solicita permissões já devem existir no locatário do cliente. Se essa condição não for atendida, a ID do Microsoft Entra retornará um erro informando que o recurso deve ser adicionado primeiro.

Várias camadas em um único locatário

Isso pode ser um problema se seu aplicativo lógico consistir em dois ou mais registros de aplicativo, por exemplo, um cliente e um recurso separados. Como você coloca o recurso no locatário externo primeiro? O Microsoft Entra ID cobre esse caso, permitindo que o cliente e o recurso sejam consentidos em uma única etapa. O usuário vê a soma total das permissões solicitadas pelo cliente e pelo recurso na página de consentimento. Para habilitar esse comportamento, o registro do aplicativo do recurso deve incluir a ID do aplicativo do cliente como um knownClientApplications em seu manifesto do aplicativo. Por exemplo:

"knownClientApplications": ["12ab34cd-56ef-78gh-90ij11kl12mn"]

Isso é demonstrado em um exemplo de aplicativo multilocatário. O diagrama a seguir fornece uma visão geral do consentimento para um aplicativo de várias camadas registrado em um único locatário.

Diagrama que ilustra o consentimento para o aplicativo cliente conhecido de várias camadas.

Várias camadas em vários locatários

Um caso semelhante acontece se as diferentes camadas de um aplicativo estiverem registradas em locatários diferentes. Por exemplo, considere o caso da criação de um aplicativo cliente nativo que chama a API do Exchange Online. Para desenvolver o aplicativo nativo e, posteriormente, para que o aplicativo nativo seja executado no locatário de um cliente, a entidade de serviço do Exchange Online deve estar presente. Nesse caso, o desenvolvedor e o cliente devem comprar o Exchange Online para que a entidade de serviço seja criada em seus locatários.

Se for uma API criada por uma organização diferente da Microsoft, o desenvolvedor da API precisará fornecer uma maneira para que seus clientes consintam o aplicativo nos locatários de seus clientes. O design recomendado é que o desenvolvedor terceirizado crie a API de modo que ela também possa funcionar como um cliente da Web para implementar a inscrição. Para tal:

  1. Siga as seções anteriores para garantir que a API implemente os requisitos de registro/código do aplicativo multilocatário.
  2. Além de expor os escopos/funções da API, verifique se o registro inclui a permissão "Entrar e ler perfil de usuário" (fornecida por padrão).
  3. Implemente uma página de entrada/inscrição no cliente da Web e siga as diretrizes de consentimento do administrador.
  4. Depois que o usuário consente com o aplicativo, a entidade de serviço e os links de delegação de consentimento são criados em seu locatário e o aplicativo nativo pode obter tokens para a API.

O diagrama a seguir fornece uma visão geral do consentimento para um aplicativo de várias camadas registrado em diferentes locatários.

Diagrama que ilustra o consentimento para aplicativos multicamadas de várias partes.

Os usuários e administradores podem revogar o consentimento para seu aplicativo a qualquer momento:

  • Os usuários revogam o acesso a aplicativos individuais removendo-os da lista de Aplicativos do Painel de Acesso.
  • Os administradores revogam o acesso a aplicativos removendo-os usando a seção Aplicativos corporativos do centro de administração do Microsoft Entra. Selecione o aplicativo e navegue até a guia Permissões para revogar o acesso.

Se um administrador consentir com um aplicativo para todos os usuários em um locatário, os usuários não poderão revogar o acesso individualmente. Somente o administrador pode revogar o acesso e somente para todo o aplicativo.

Aplicativos multilocatários e tokens de acesso em cache

Os aplicativos multilocatários também podem obter tokens de acesso para chamar APIs protegidas pelo Microsoft Entra ID. Um erro comum ao usar a Microsoft Authentication Library (MSAL) com um aplicativo multilocatário é solicitar inicialmente um token para um usuário usando /common, receber uma resposta e, em seguida, solicitar um token subsequente para esse mesmo usuário também usando /common. Como a resposta do Microsoft Entra ID vem de um locatário, não /commondo , o MSAL armazena em cache o token como sendo do locatário. A chamada subsequente para /common obter um token de acesso para o usuário perde a entrada de cache e o usuário é solicitado a entrar novamente. Para evitar perder o cache, certifique-se de que as chamadas subsequentes para um usuário já conectado sejam feitas para o ponto de extremidade do locatário.

Consulte também