Partilhar via

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

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 entrada via OAuth2, OpenID Connect ou SAML (Security Assertion Markup Language) e colocar um botão "Entrar com a Microsoft" em seu aplicativo.

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

  1. Atualize o registo da sua aplicação para ser multi-inquilino
  2. Atualize o seu código para enviar solicitações ao /common endpoint
  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 registos de aplicações Web/API no Microsoft Entra ID são de locatário único quando criados. 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 uma aplicação de inquilino único é criada no centro de administração do Microsoft Entra, um dos itens listados na página Visão Geral é o URI da ID da Aplicação. 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 aplicações multilocatário, ele deve ser globalmente único em todos os locatários, garantindo que o ID do Microsoft Entra possa localizar 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 de aplicativo não seguir este padrão, a configuração de um aplicativo como multitenant não terá sucesso.

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

Com uma aplicação multilocatária, a aplicação não consegue determinar imediatamente a que locatário pertence o utilizador, portanto, as solicitações não podem ser enviadas ao endereço de endpoint 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. Para aplicativos SAML, isso pode ser configurado no arquivo XML do provedor de identidade. Este endpoint não é, por si só, um locatário ou um emissor. Quando a plataforma de identidade da Microsoft recebe uma solicitação no /common ponto de extremidade, autentica o utilizador, descobrindo a que locatário o utilizador pertence. Este endpoint funciona com todos os protocolos de autenticação suportados pelo Microsoft Entra ID (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 uma aplicação a que tenant o utilizador pertence. Quando uma resposta retorna do endpoint /common, o valor do emissor no token corresponde ao inquilino 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 (como 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.

As aplicações multilocatárias devem realizar mais verificações ao validar um token. Uma aplicação multilocatária é configurada para consumir metadados de chaves de /organizations ou URLs de chaves de /common. 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 utilizador fazer login numa aplicação no Microsoft Entra ID, a aplicação deve ser representada no inquilino do utilizador. A organização tem permissão para fazer coisas como aplicar políticas exclusivas quando os usuários de seu locatário entram no aplicativo. Para uma aplicação de locatário único, pode-se utilizar o registo através 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, então uma representação da aplicação chamada service principal é criada no locatário do usuário, e o login pode 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 do aplicativo e os objetos do principal de serviço, e como eles se inter-relacionam, consulte Objetos de aplicativo e objetos de principal de serviço.

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

As permissões solicitadas pelo aplicativo afetam a experiência de consentimento. 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.

Os utilizadores regulares podem consentir algumas permissões, enquanto outras requerem o consentimento de um administrador de inquilino.

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 do administrador do inquilino. 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 escrever novamente no Microsoft Entra ID como o utilizador autenticado requer o consentimento de um administrador do inquilino. 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. O desenvolvedor que publicou o recurso determina se uma permissão requer o consentimento do administrador e você pode encontrar essas informações 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 o seu aplicativo envia para esta ação é a solicitação de autorização habitual de OAuth2/OpenID Connect que também inclui o parâmetro cadeia de consulta prompt=consent. Depois que o administrador consente e a entidade de serviço é criada no locatário do cliente, as solicitações de entrada subsequentes não precisam do prompt=consent parâmetro. Como o administrador aprovou as permissões solicitadas, nenhum outro usuário no locatário será solicitado a dar consentimento.

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 caso de uso é 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 uma aplicação exigir o consentimento de administrador e um administrador entrar sem que o parâmetro prompt=consent seja enviado, quando o administrador consentir com êxito com a aplicação, ele aplicar-se-á apenas à sua conta de utilizador. Os utilizadores regulares não poderão iniciar sessão ou consentir na 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

Se seu aplicativo lógico consistir em dois ou mais registros de aplicativo, por exemplo, um cliente e um recurso separados, você poderá encontrar alguns problemas. Por exemplo, 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 ativar este comportamento, o registo de aplicação do recurso deve incluir a ID da aplicação do cliente como um knownClientApplications no seu manifesto da aplicação. Por exemplo:

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

Você pode consultar o exemplo de aplicativo multilocatário para obter uma demonstração. 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 um aplicativo cliente de várias camadas conhecido.

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. Aqui, o desenvolvedor e o cliente devem comprar o Exchange Online para que a principal de serviço seja criada nos seus inquilinos.

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. É possível;

  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 aceder a 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 inquilino, e não de /common, o MSAL armazena em cache o token como sendo do inquilino. 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 a cache, certifique-se de que as chamadas subsequentes para um utilizador já conectado sejam feitas para o endpoint do locatário.

Consulte também