Integrar usuários externos aos aplicativos de linha de negócios usando o Microsoft Entra B2B

Os desenvolvedores de aplicativos podem usar o Microsoft Entra B2B para integrar e colaborar com usuários externos em aplicativos de linha de negócios (LOB). Semelhante ao botão Compartilhar em muitos aplicativos do Office 365, os desenvolvedores de aplicativos podem criar uma experiência de convite com um clique em qualquer aplicativo de linha de negócios integrado ao Microsoft Entra ID.

Os benefícios incluem:

• Integração simples e fácil do usuário e acesso aos aplicativos de linha de negócios com usuários capazes de obter acesso com algumas etapas.

• Permite que usuários externos tragam sua própria identidade e executem o logon único (SSO).

• Provisionamento automático de identidades externas para o Microsoft Entra ID.

• Aplique o Acesso Condicional do Microsoft Entra e as políticas de acesso entre locatários para aplicar políticas de autorização, como a exigência da autenticação multifator.

Fluxo de integração

Para integrar aplicativos de linha de negócios com o Microsoft Entra B2B, siga este padrão:

Etapa	Descrição
1.	O usuário final aciona o convite ao aplicativo de linha de negócios e fornece o endereço de email do usuário externo. O aplicativo verifica se o usuário já existe e, se não existir, prossegue para a etapa nº 2
2.	O aplicativo envia um POST para a API do Microsoft Graph em nome do usuário. Ele fornece a URL de redirecionamento e o email do usuário externo definido em Etapa nº 1.
3.	A API do Microsoft Graph provisiona o usuário convidado no Microsoft Entra ID.
4.	A API do Microsoft Graph retorna o status de sucesso/falha da chamada à API. Se for bem-sucedida, a resposta incluirá a ID do objeto do usuário do Microsoft Entra e o link do convite que é enviado para o email do usuário convidado. Opcionalmente, você pode suprimir o email da Microsoft e enviar seu próprio email personalizado.
5.	(Opcional) Se você deseja gravar mais atributos para o usuário convidado ou adicionar o usuário convidado a um grupo, o aplicativo faz uma chamada à API extra para a API do Microsoft Graph.
6.	(Opcional) A API do Microsoft Graph faz as atualizações desejadas no Microsoft Entra ID.
7.	(Opcional) A API do Microsoft Graph retorna o status de sucesso/falha para o aplicativo.
8.	O aplicativo provisiona o usuário em seu próprio banco de dados/diretório de usuário de back-end usando o atributo de ID de objeto do usuário como ID imutável.
9.	O aplicativo apresenta o status de sucesso/falha ao usuário final.

Se for necessária uma atribuição para acessar o aplicativo de linha de negócios, o Usuário Convidado também deverá ser atribuído ao aplicativo com uma função de aplicativo apropriada. Isso pode ser feito como outra chamada à API adicionando o convidado a um grupo (etapas #5-7) ou automatizando a associação de grupo com grupos dinâmicos do Microsoft Entra. O uso de grupos dinâmicos não exigiria outra chamada à API pelo aplicativo. No entanto, a associação ao grupo não seria atualizada tão rapidamente em comparação com a adição de um usuário a um grupo imediatamente após o convite do usuário.

Etapa 1: verificar se o usuário externo já existe

É possível que o usuário externo tenha sido previamente convidado e integrado. O aplicativo de linha de negócios deve verificar se o usuário já existe no diretório. Há muitas abordagens, no entanto, a mais simples envolve fazer uma chamada à API para a API do Microsoft Graph e apresentar as possíveis correspondências ao usuário convidado, para que ele possa escolher.

Por exemplo:

Application Permission: User.read.all

GET https://graph.microsoft.com/v1.0/users?$filter=othermails/any(id:id eq 'userEmail@contoso.com')  

Se você receber os detalhes de um usuário na resposta, então o usuário já existirá. Você deve apresentar os usuários retornados ao usuário convidado e permitir que eles escolham a qual usuário externo desejam conceder acesso. Você deve prosseguir com as chamadas à API apropriadas ou acionar outros processos para conceder a esse usuário acesso ao aplicativo, em vez de prosseguir com a etapa de convite.

Etapa 2: criar e enviar convite

Se o usuário externo ainda não existir no diretório, você poderá usar o Microsoft Entra B2B para convidar o usuário e integrá-lo ao seu locatário do Microsoft Entra. Como desenvolvedor de aplicativos, você precisa determinar o que incluir na solicitação de convite para a API do Microsoft Graph.

No mínimo, você precisa:

• Solicite que o usuário final forneça o endereço de email do usuário externo.

• Determinar o URL do convite. Esse URL é para onde o usuário convidado é redirecionado após autenticar e resgatar o convite B2B. O URL pode ser uma página inicial genérica do aplicativo ou determinada dinamicamente pelo aplicativo de linha de negócios com base em onde o usuário final acionou o convite.

Mais sinalizadores e atributos a serem considerados para inclusão na solicitação de convite:

• Nome de exibição do usuário convidado.
• Determine se deseja usar o email de convite padrão da Microsoft ou suprimir o email padrão para criar o seu próprio.

Depois que o aplicativo coletar as informações necessárias e determinar quaisquer outros sinalizadores ou informações a serem incluídas, o aplicativo deverá POSTAR a solicitação para o gerenciador de convites da API do Microsoft Graph. Verifique se o registro do aplicativo tem as permissões apropriadas no Microsoft Entra ID.

Por exemplo:

Delegated Permission: User.Invite.All

POST https://graph.microsoft.com/v1.0/invitations  
Content-type: application/json

{ 
"invitedUserDisplayName": "John Doe",  
"invitedUserEmailAddress": "john.doe@contoso.com",  
"sendInvitationMessage": true,  
"inviteRedirectUrl": "https://customapp.contoso.com"  
} 

Observação

Para exibir a lista completa de opções disponíveis para o corpo JSON do convite, confira o tipo de recurso de convite - Microsoft Graph v1.0.

Como alternativa, os desenvolvedores de aplicativos podem integrar usuários externos usando a inscrição de autoatendimento do Microsoft Entra ou os pacotes de acesso de gerenciamento de direitos. Você pode criar seu botão de convite em seu aplicativo de linha de negócios que aciona um email personalizado contendo um URL de inscrição de autoatendimento predefinido ou um URL de pacote de acesso. O usuário convidado, em seguida, faz o autoatendimento para integrar e acessar o aplicativo.

Etapa 3: gravar outros atributos no Microsoft Entra ID (opcional)

Importante

Conceder permissão a um aplicativo para atualizar usuários em seu diretório é uma ação altamente privilegiada. Você deve tomar medidas para proteger e monitorar seu aplicativo de linha de negócios se conceder ao aplicativo essas permissões altamente privilegiadas.

Sua organização ou o aplicativo de linha de negócios requerer o armazenamento de mais informações para uso futuro, como a emissão de declarações em tokens ou políticas de autorização granular. Seu aplicativo pode fazer outra chamada à API para atualizar o usuário externo depois que ele tiver sido convidado/criado no Microsoft Entra ID. Fazer isso requer que seu aplicativo tenha permissões extras de API e exigiria uma chamada extra para a API do Microsoft Graph.

Para atualizar o usuário, é necessário usar a ID do objeto do usuário convidado recém-criado recebido na resposta da chamada à API de convite. Esse é o valor da ID na resposta da API da verificação de existência ou do convite. Você pode gravar em qualquer atributo padrão ou atributos de extensão personalizados que possa ter criado.

Por exemplo:

Application Permission: User.ReadWrite.All

PATCH https://graph.microsoft.com/v1.0/users/<user's object ID> 
Content-type: application/json

{ 
"businessPhones": [ 
        "+1 234 567 8900" 
    ], 
"givenName": "John" 
"surname": "Doe", 
"extension_cf4ff515cbf947218d468c96f9dc9021_appRole": "external" 
} 

Para obter mais informações, confira Atualizar usuário - Microsoft Graph v1.0.

Etapa 4: atribuir o usuário convidado a um grupo

Observação

Se a atribuição de usuário não for necessária para acessar o aplicativo, você poderá ignorar esta etapa.

Se a atribuição de usuário for necessária no Microsoft Entra ID para acesso ao aplicativo ou atribuição de função, o usuário deverá ser atribuído ao aplicativo, caso contrário, ele não conseguirá obter acesso, independentemente da autenticação bem-sucedida. Para isso, você deve fazer outra chamada à API para adicionar o usuário externo convidado a um grupo específico. O grupo pode ser atribuído ao aplicativo e mapeado para uma função de aplicativo específica.

Por exemplo:

Permissões: atribua a função Atualizador de grupo ou uma função personalizada ao aplicativo empresarial e defina o escopo da atribuição de função apenas para os grupos que esse aplicativo deve atualizar. Ou atribua a permissão group.readwrite.all na API do Microsoft Graph.

POST https://graph.microsoft.com/v1.0/groups/<insert group id>/members/$ref 
Content-type: application/json

{ 
"@odata.id": "https://graph.microsoft.com/v1.0/directoryObjects/<insert user id>" 
} 

Para obter mais informações, confira Adicionar membros - Microsoft Graph v1.0.

Como alternativa, você pode usar os grupos dinâmicos do Microsoft Entra, que podem atribuir automaticamente usuários a grupos com base nos atributos do usuário. No entanto, se o acesso do usuário final for sensível ao tempo, essa não seria a abordagem recomendada, pois os grupos dinâmicos podem levar até 24 horas para serem preenchidos.

Se preferir usar grupos dinâmicos, você não precisará adicionar os usuários a um grupo explicitamente com outra chamada à API. Crie um grupo dinâmico que adiciona automaticamente o usuário como membro do grupo com base nos atributos disponíveis, como userType, email ou um atributo personalizado. Para obter mais informações, confira Criar ou editar um grupo dinâmico e obter status.

Etapa 5: provisionar o usuário convidado para o aplicativo

Depois que o usuário externo convidado for provisionado para o Microsoft Entra ID, a API do Microsoft Graph retornará uma resposta com as informações necessárias do usuário, como ID de objeto e email. Em seguida, o aplicativo de linha de negócios pode provisionar o usuário em seu próprio diretório/banco de dados. A implementação real desse provisionamento varia dependendo do tipo de aplicativo e do tipo de diretório interno que o aplicativo usa.

Com o usuário externo provisionado no Microsoft Entra ID e no aplicativo, o aplicativo de linha de negócios agora pode notificar o usuário final que iniciou o convite de que o processo foi bem-sucedido. O usuário convidado pode obter SSO com sua própria identidade sem que a organização convidada precise integrar e emitir credenciais extras. O Microsoft Entra ID pode impor políticas de autorização, como acesso condicional, autenticação multifator do Microsoft Entra e proteção de identidade baseada em risco.

Outras considerações

• Verifique se o tratamento de erro adequado é feito no aplicativo de linha de negócios. O aplicativo deve validar se cada chamada à API foi bem-sucedida. Se não houver êxito, tentativas adicionais ou a apresentação de mensagens de erro para o usuário final seriam apropriadas.

• Se precisar que o aplicativo de linha de negócios atualize os usuários externos depois que eles forem convidados, considere conceder uma função personalizada que permita que o aplicativo atualize apenas os usuários e atribua o escopo a uma unidade administrativa dinâmica. Por exemplo, você pode criar uma unidade administrativa dinâmica para conter todos os usuários onde o usertype = convidado. Depois que o usuário externo é integrado ao Microsoft Entra ID, leva um tempo para ser adicionado à unidade administrativa. Portanto, o aplicativo de linha de negócios precisa tentar atualizar o usuário depois de algum tempo e pode levar mais de uma tentativa se houver atrasos. Apesar desses atrasos, essa é a melhor abordagem disponível para permitir que o aplicativo de linha de negócios atualize usuários externos sem conceder permissão para atualizar qualquer usuário no diretório.