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

  • Artigo

Se você oferecer um aplicativo de software como serviço (SaaS) 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 após o consentimento para usar sua conta com o aplicativo.

Para os aplicativos existentes com um sistema de contas próprio (ou outras entradas de outros provedores de nuvem), adicione o código de entrada por meio do OAuth2, do OpenID Connect ou do SAML e coloque um botão "Entrar com a Microsoft" no seu aplicativo.

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

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

Se você quiser tentar usar um de nossos exemplos, confira 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 API/aplicativo Web no Azure AD são de locatário único durante a criação. Para tornar o registro multilocatário, faça logon no centro de administração do Microsoft Entra e selecione o registro de aplicativo que você deseja atualizar. Com o registro do aplicativo aberto, selecione o painel Autenticação e navegue até a seção Tipos de conta com suporte. Altere a configuração para Contas de 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 de visão geral é o URI da ID do Aplicativo. Essa é uma das maneiras pelas quais um aplicativo é identificado nas mensagens de protocolo e pode ser adicionada a qualquer momento. O URI da ID do Aplicativo para aplicativos de locatário único pode ser globalmente exclusivo no 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 for contoso.onmicrosoft.com, um URI da ID do Aplicativo válido será 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á.

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

Com um aplicativo multilocatário, o aplicativo não pode informar imediatamente de qual locatário o usuário provém, 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 serve em todos os locatários do Microsoft Entra, atuando como um hub central que lida com solicitações.

Abra seu aplicativo no IDE e edite seu código e altere o valor da ID do locatário para /common. Esse 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 ponto de extremidade /common, ela realiza a entrada do usuário e, como consequência, descobre de qual locatário o usuário é proveniente. Esse ponto de extremidade funciona com todos os protocolos de autenticação compatíveis com o Azure AD (OpenID Connect, OAuth 2.0, SAML 2.0 e Web Services Federation).

Em seguida, a resposta de conexão para o aplicativo conterá um token que representa o usuário. O valor do emissor no token diz a um aplicativo de qual locatário o usuário é. Quando uma resposta é retornada do ponto de extremidade /common, o valor do emissor no token corresponde ao locatário do usuário.

Observação

Há, na realidade, 2 autoridades para aplicativos multilocatário:

  • https://login.microsoftonline.com/common para contas de processamento de aplicativos 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 contas de processamento de aplicativos 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 o aplicativo não for compatível com contas pessoais da Microsoft.

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

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

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

Para um usuário entrar em um aplicativo no Azure AD, o aplicativo deve estar representado no locatário do usuário. Isso permite que a organização realize ações como aplicar políticas exclusivas quando usuários de seu locatário entrarem no aplicativo. Para um aplicativo de locatário único, é possível usar o registro por meio do centro de administração do Microsoft Entra.

Para um aplicativo multilocatário, o registro inicial do 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 Azure AD solicita que ele consinta com as permissões solicitadas pelo aplicativo. Se ele fornecer o consentimento, uma representação do aplicativo chamada uma entidade de serviço será criada no locatário do usuário e o processo de conexão 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, veja Objetos de aplicativo e objetos principais 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 dá suporte a dois tipos de permissões;

  • Delegada: essa permissão concede a um aplicativo a capacidade de atuar 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 permissão somente do aplicativo a um aplicativo para ler a lista de usuários em um locatário, independentemente de quem estiver conectado ao aplicativo.

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

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

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

Algumas permissões delegadas também exigem o consentimento do administrador de locatários. Por exemplo, a capacidade de gravar no Azure AD como o usuário conectado requer o consentimento de um administrador de locatários. Semelhante às permissões somente do aplicativo, se um usuário comum tenta entrar em um aplicativo que solicita uma permissão delegada que exige o consentimento do administrador, o aplicativo recebe um erro. Uma permissão exigir ou não o consentimento do administrador é determinado pelo desenvolvedor que publicou o recurso e pode ser encontrado na documentação do recurso. A documentação das permissões para a API do Microsoft Graph indica quais permissões exigem consentimento do administrador.

Se o aplicativo usar permissões que exigem o consentimento do administrador, considere a adição de um botão ou um link em que o administrador pode iniciar a ação. A solicitação que seu aplicativo envia para essa ação é uma solicitação de autorização do OAuth2/OpenID Connect normal, que também inclui o parâmetro de cadeia de caracteres de consulta prompt=consent. Depois que o administrador fornecer o consentimento e a entidade de serviço for criada no locatário do cliente, as solicitações de conexão posteriores não precisarão do parâmetro prompt=consent. Uma vez que o administrador tiver decidido que as permissões solicitadas forem aceitáveis, não será solicitado o consentimento de nenhum outro usuário no locatário daquele ponto em diante.

Um administrador de locatários pode desabilitar a capacidade dos usuários regulares consentirem aplicativos. Se essa funcionalidade estiver desabilitada, o consentimento do administrador sempre será necessário para o aplicativo a ser usado no locatário. Você pode testar seu aplicativo com o consentimento do usuário final desabilitado, no centro de administração do Microsoft Entra. Em Aplicativos empresariais>Consentimento e permissões, marque a opção Não permitir consentimento do usuário.

O parâmetro prompt=consent também pode ser usado por aplicativos que solicitam permissões que não necessitam do consentimento do administrador. Um exemplo de como isso seria usado é quando o aplicativo exige uma experiência na qual o administrador de locatários “se inscreve” uma vez e não é solicitado o consentimento de nenhum outro usuário desse momento em diante.

Se um aplicativo exigir o consentimento do administrador e um administrador fizer logon, mas o parâmetro prompt=consent não for enviado, o administrador fornecerá consentimento ao aplicativo somente para a conta de usuário dele. Os usuários normais ainda não poderão entrar ou dar consentimento ao aplicativo. Esse recurso é útil se você quiser conceder ao administrador de locatários 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 Web ou um aplicativo Web que chama uma API Web. Em ambos os casos, o cliente (aplicativo nativo ou aplicativo Web) solicita permissões para chamar o recurso (API Web). Para o cliente ter o consentimento com êxito em um locatário do cliente, todos os recursos aos quais ele solicita permissões já devem existir no locatário do cliente. Se essa condição não for atendida, o Azure AD retornará um erro de que o recurso deve ser adicionado primeiro.

Várias camadas em um único locatário

Isso poderá 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 primeiro no locatário externo? O Azure AD abrange neste caso permitindo que o cliente e o recurso recebam o consentimento 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 permitir esse comportamento, o registro do aplicativo do recurso deve incluir a ID do aplicativo do cliente como um knownClientApplications no 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 de consentimento para um aplicativo de várias camadas registrado em um único locatário.

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

Várias camadas em vários locatários

Um caso semelhante acontecerá se as diferentes camadas de um aplicativo forem 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 e posteriormente para o aplicativo nativo ser 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 adquirir 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 que não seja a Microsoft, o desenvolvedor da API precisa fornecer uma maneira para seus clientes fornecerem consentimento para o aplicativo nos locatários de seus clientes. O design recomendado é que o desenvolvedor de terceiros crie a API, de forma que ele também possa funcionar como um cliente Web para implementar a inscrição. Para fazer isso:

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

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

Diagrama que ilustra o consentimento ao aplicativo de vários fornecedores e de várias camadas.

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 aos aplicativos removendo-os usando a seção Aplicativos empresariais 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 fornecer o consentimento a um aplicativo para todos os usuários de um locatário, os usuários não poderão revogar o acesso individualmente. Somente o administrador pode revogar o acesso e somente para o aplicativo inteiro.

Aplicativos multilocatário e tokens de acesso de cache

Aplicativos multilocatário também podem obter tokens de acesso para chamar APIs protegidas pelo Microsoft Entra ID. Um erro comum ao usar a Biblioteca de Autenticação da Microsoft (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 Azure AD vem de um locatário, não de /common, a MSAL armazena em cache o token como sendo do locatário. A chamada seguinte a /common para obter um token de acesso para o usuário perde a entrada do cache, e o usuário é solicitado a se conectar novamente. Para evitar a perda de cache, certifique-se de que as chamadas subsequentes para um usuário já conectado sejam feitas para o ponto de extremidade do locatário.

Confira também