Por que atualizar para plataforma de identidade da Microsoft (v2.0)?

Artigo
11/09/2022

Ao desenvolver um aplicativo, é importante conhecer as diferenças entre os pontos de extremidade da plataforma de identidade da Microsoft (v2.0) e do Azure Active Directory (v1.0). Este artigo aborda as principais diferenças entre os pontos de extremidade e algumas limitações da plataforma de identidade da Microsoft.

Quem pode entrar com endpoints v1.0 e v2.0

O ponto de extremidade v1.0 permite que apenas contas do trabalho e da escola entrem no seu aplicativo (Azure AD)
O ponto de extremidade da plataforma de identidade da Microsoft permite que contas corporativas e de estudante do ID do Microsoft Entra e contas pessoais da Microsoft (MSA), como hotmail.com, outlook.com e msn.com, entrem.
Ambos os pontos de extremidade também aceitam entradas de usuários convidados de um diretório do Microsoft Entra para aplicativos configurados como locatário único ou para aplicativos multilocatário configurados para apontar para o ponto de extremidade (https://login.microsoftonline.com/{TenantId_or_Name}) específico do locatário.

O ponto de extremidade da plataforma de identidade da Microsoft permite criar aplicativos que aceitam entradas de contas Microsoft pessoais e contas corporativas e de estudante. Isso lhe dá a capacidade de escrever seu aplicativo completamente independente de conta. Por exemplo, se seu aplicativo chamar o Microsoft Graph, alguns recursos e dados adicionais estarão disponíveis para contas de trabalho, como seus sites do SharePoint ou dados do Diretório. Mas, para muitas ações, como a leitura de um e-mail de um usuário, o mesmo código pode acessar o e-mail para contas pessoais e de trabalho e escola.

Para o ponto de extremidade de plataforma de identidade da Microsoft, você pode usar Biblioteca de Autenticação da Microsoft (MSAL) para obter acesso aos mundos do consumidor, educacional e empresarial. O ponto de extremidade do Azure AD v1.0 aceita logins apenas de contas do trabalho e da escola.

Os aplicativos que usam o endpoint do Azure AD v1.0 precisam especificar suas permissões necessárias do OAuth 2.0 antecipadamente, por exemplo:

Exemplo mostrando a interface do usuário do registro de permissões

As permissões definidas diretamente no registro do aplicativo são static. Embora as permissões estáticas do aplicativo definidas no portal do Azure mantivessem o código simples e agradável, ele apresenta alguns problemas para os desenvolvedores:

O aplicativo precisa solicitar todas as permissões que precisaria no primeiro login do usuário. Isso pode resultar em uma lista longa de permissões, o que desencorajava os usuários finais a aprovarem o acesso do aplicativo na entrada inicial.
O aplicativo precisa conhecer todos os recursos que jamais acessaria antes do tempo. Era difícil criar aplicativos que pudessem acessar um número arbitrário de recursos.

Com o ponto de extremidade de plataforma de identidade da Microsoft, você pode ignorar as permissões estáticas definidas nas informações de registro de aplicativo nas permissões do portal do Azure e solicitação incrementalmente em vez disso, o que significa solicitando conjunto mínimo de permissões com antecedência e aumentando ao longo do tempo conforme o cliente usa os recursos de aplicativo adicionais. Para fazer isso, você pode especificar os escopos que seu aplicativo precisa, incluindo os novos escopos no parâmetro scope ao solicitar um token de acesso, sem a necessidade de pré-defini-los nas informações de registro do aplicativo. Se o usuário ainda não tiver consentido em novos escopos adicionados à solicitação, ele será solicitado a consentir apenas com as novas permissões. Para obter mais informações, consulte permissões, autorização e escopos.

Permitir que um aplicativo solicite permissões dinamicamente por meio do parâmetro scope fornece aos desenvolvedores controle total sobre a experiência do usuário. Você também pode optar por carregar sua experiência de consentimento e solicitar todas as permissões em uma solicitação inicial de autorização. Ou, se seu aplicativo precisar de um grande número de permissões, você pode reunir essas permissões do usuário de forma incremental, à medida que ele tentar usar determinados recursos do seu aplicativo ao longo do tempo.

Consentimento do administrador realizado em nome de uma organização ainda exige as permissões estáticas registradas para o aplicativo, portanto, você deve definir essas permissões para aplicativos no portal de registro do aplicativo se precisar de um administrador para dar consentimento em nome de toda a organização. Isso reduz os ciclos exigidos pelo administrador da organização para configurar o aplicativo.

Escopos, não recursos

Para aplicativos que usam o endpoint v1.0, um aplicativo pode se comportar como um recurso ou um destinatário de tokens. Um recurso pode definir um número de escopos ou oAuth2Permissions que ele entende, permitindo que os aplicativos cliente solicitem tokens a esse recurso de um determinado conjunto de escopos. Considere a API do Microsoft Graph do como um exemplo de um recurso:

Identificador de recurso, ou AppID URI: https://graph.microsoft.com/
Escopos, ou oAuth2Permissions: Directory.Read, Directory.Writee assim por diante.

Isso se aplica ao ponto de extremidade da plataforma de identidade da Microsoft. Um aplicativo ainda pode se comportar como recurso, definir escopos e ser identificado por um URI. Aplicativos cliente ainda podem solicitar acesso a esses escopos. No entanto, a maneira como um cliente solicita essas permissões foi alterada.

Para o ponto de extremidade v1.0, uma solicitação de autorização do OAuth 2.0 para o Azure AD pode ter parecido com:

GET https://login.microsoftonline.com/common/oauth2/authorize?
client_id=2d4d11a2-f814-46a7-890a-274a72a7309e
&resource=https://graph.microsoft.com/
...

Aqui, o parâmetro recurso indicava o recurso para o qual o aplicativo cliente estava solicitando a autorização. O Microsoft Azure Active Directory computava as permissões exigidas pelo aplicativo com base na configuração estática no Portal do Azure e emitia os tokens de acordo.

Para aplicativos que usam o ponto de extremidade de plataforma de identidade da Microsoft, a mesma solicitação de autorização do OAuth 2.0 é semelhante a:

GET https://login.microsoftonline.com/common/oauth2/v2.0/authorize?
client_id=2d4d11a2-f814-46a7-890a-274a72a7309e
&scope=https://graph.microsoft.com/directory.read%20https://graph.microsoft.com/directory.write
...

Aqui, parâmetro escopo indica para qual recurso e permissões o aplicativo está solicitando autorização. O recurso desejado ainda está presente na solicitação; ele simplesmente está englobado em cada um dos valores do parâmetro de escopo. Usar o parâmetro de escopo dessa maneira permite que o ponto de extremidade de plataforma de identidade da Microsoft esteja em conformidade com a especificação OAuth 2.0 e esteja alinhado mais estreitamente com práticas comuns do setor. Ele também permite que os aplicativos façam o consentimento incremental, solicitando permissões somente quando o aplicativo os exige, em oposição à frente.

Escopos conhecidos

Acesso offline

Os aplicativos que usam o ponto de extremidade de plataforma de identidade da Microsoft podem exigir o uso de uma nova permissão conhecida para aplicativos – o escopo offline_access. Todos os aplicativos terão que solicitar essa permissão se precisarem acessar recursos em nome de um usuário por um longo período de tempo, mesmo quando o usuário pode não estiver usando o aplicativo de maneira ativa. O escopo offline_access aparecerá para o usuário em diálogos de consentimento como Acesse seus dados a qualquer momento, com os quais o usuário deve concordar. Solicitar a permissão offline_access permitirá que seu aplicativo Web receba refresh_tokens do OAuth 2.0 do ponto de extremidade da plataforma de identidade da Microsoft. Os tokens de atualização são de longa duração e podem ser trocados por novos tokens de acesso do OAuth 2.0 por longos períodos de acesso.

Se o aplicativo não solicitar o escopo offline_access, ele não receberá tokens de atualização. Isso significa que, quando você resgatar um código de autorização no fluxo do código de autorização do OAuth 2.0, receberá apenas um token de acesso do ponto de extremidade /token. Esse token de acesso permanecerá válido por um curto período de tempo (geralmente uma hora), mas acabará expirando. Nesse momento, seu aplicativo precisará redirecionar o usuário de volta ao ponto de extremidade /authorize para recuperar um novo código de autorização. Durante esse redirecionamento, o usuário pode ou não precisar digitar suas credenciais novamente ou consentir de novo as permissões, dependendo do tipo do aplicativo.

Para saber mais sobre o OAuth 2.0, refresh_tokens e access_tokens, confira a referência do protocolo da plataforma de identidade da Microsoft.

OpenID, perfil e email

Historicamente, o fluxo de entrada mais básico do OpenID Connect com a plataforma de identidade da Microsoft fornecia muitas informações sobre o usuário no id_token resultante. As declarações em um id_token podem incluir o nome do usuário, nome de usuário preferido, endereço de email, ID do objeto e muito mais.

As informações que o escopo de openid permite que seu aplicativo acesse agora estão restritas. O escopo de openid apenas permitirá que seu aplicativo faça logon do usuário e receba um identificador específico do aplicativo para o usuário. Se você quiser obter dados pessoais sobre o usuário em seu aplicativo, seu aplicativo precisará solicitar permissões adicionais do usuário. Dois novos escopos email e profile – permitirão que você solicite permissões adicionais.

O escopo de email permite que seu aplicativo acesse o endereço de email principal do usuário por meio da declaração email no id_token, supondo que o usuário tem um endereço de email endereçável.
O escopo profile permite que seu aplicativo acesse todas as outras informações básicas sobre o usuário, como seu nome, nome de usuário preferido, ID do objeto etc., no id_token.

Esse escopo permite que você codifique seu aplicativo com uma divulgação mínima. Você só pode solicitar ao usuário o conjunto de informações de que seu aplicativo precisa para fazer seu trabalho. Para obter mais informações sobre esses escopos, confira a referência de escopo da plataforma de identidade da Microsoft.

Declarações de token

O ponto de extremidade da plataforma de identidade da Microsoft emite um conjunto menor de declarações em seus tokens por padrão para manter conteúdos pequenos. Se você tiver aplicativos e serviços com uma dependência de uma declaração específica em um token v1.0 que não é mais fornecido por padrão em um token da plataforma de identidade da Microsoft, considere usar o recurso de declarações opcionais para incluir essa declaração.

Importante

Os tokens v1.0 e v2.0 podem ser emitidos pelos pontos de extremidade v1.0 e v2.0. Os id_tokens sempre correspondem ao ponto de extremidade do qual são solicitados e os tokens de acesso sempre correspondem ao formato esperado pela API Web que o cliente chamará usando esse token. Portanto, se o seu aplicativo usar o ponto de extremidade v2.0 para obter um token para chamar Microsoft Graph, que espera tokens de acesso de formato v1.0, seu aplicativo receberá um token no formato v1.0.

Limitações

Existem algumas restrições a serem observadas ao usar a plataforma de identidade da Microsoft.

Ao criar aplicativos que se integram à plataforma de identidade da Microsoft, você precisa decidir se os protocolos de ponto de extremidade e de autenticação da plataforma de identidade da Microsoft atendem às suas necessidades. O ponto de extremidade v1.0 e a plataforma ainda têm suporte total e, em alguns aspectos, é mais rico em recursos do que a plataforma de identidade da Microsoft. No entanto, a plataforma de identidade da Microsoft apresenta benefícios significativos para os desenvolvedores.

No momento, esta é uma recomendação simplificada para desenvolvedores:

Se você desejar ou precisar dar suporte a contas Microsoft pessoais em seu aplicativo ou você estiver escrevendo um novo aplicativo, use a plataforma de identidade da Microsoft. Mas antes de fazer isso, tenha certeza de que entende as limitações discutidas neste artigo.
Se você estiver migrando ou atualizando um aplicativo que se baseia em SAML, não poderá usar a plataforma de identidade da Microsoft. Em vez disso, confira o Guia do Azure AD v1.0.

O ponto de extremidade da plataforma de identidade da Microsoft evoluirá e eliminará as restrições listadas aqui, para que você precise usar apenas o ponto de extremidade plataforma de identidade da Microsoft. Enquanto isso, use este artigo para determinar se o ponto de extremidade da plataforma de identidade da Microsoft é adequado para você. Continuaremos a atualizar este artigo para refletir o estado atual do ponto de extremidade da plataforma de identidade da Microsoft. Verifique novamente para reavaliar seus requisitos em relação às funcionalidades da plataforma de identidade da Microsoft.

Restrições quanto a registros de aplicativos

Para cada aplicativo que você deseja integrar ao ponto de extremidade da plataforma de identidade da Microsoft, você pode criar um registro de aplicativo na nova experiência de Registros de aplicativo no portal do Azure. Os aplicativos de conta Microsoft existentes não são compatíveis com o portal, mas todos os aplicativos do Microsoft Entra são, independentemente de onde ou quando foram registrados.

Registros de aplicativo que dão suporte ao trabalho e contas de estudante e contas pessoais têm as seguintes condições:

Apenas dois segredos do aplicativo são permitidos por ID do Aplicativo.
Um aplicativo que não foi registrado em um locatário só pode ser gerenciado pela conta que o registrou. Ele não pode ser compartilhado com outros desenvolvedores. Esse é o caso para a maioria dos aplicativos que foram registrados usando uma conta pessoal da Microsoft no Portal de registro do aplicativo. Se você quiser compartilhar o registro do seu aplicativo com vários desenvolvedores, registre o aplicativo em um locatário usando a seção Registros de aplicativo do portal do Azure.
Existem várias restrições quanto ao formato do URL de redirecionamento permitido. Para mais informações sobre o URL de redirecionamento, consulte a próxima seção.

Restrições em URLs de redirecionamento

Para obter as informações mais atualizadas sobre restrições em URLs de redirecionamento para aplicativos registrados para a plataforma de identidade da Microsoft, confira Restrições e limitações de URL de resposta/URI de redirecionamento na documentação da plataforma de identidade da Microsoft.

Para saber como registrar um aplicativo para uso com a plataforma de identidade da Microsoft, confira Registrar um aplicativo usando a nova experiência de registros de aplicativo.

Restrição de bibliotecas e SDKs

No momento, o suporte à biblioteca para o ponto de extremidade da plataforma de identidade da Microsoft é limitado. Se você quiser usar o ponto de extremidade da plataforma de identidade da Microsoft em um aplicativo de produção, terá estas opções:

Caso esteja criando um aplicativo Web, você pode usar com segurança o middleware do servidor em disponibilidade geral para realizar a entrada e a validação de token. Isso inclui o middleware OWIN Open ID Connect para ASP.NET e o plug-in Passport do Node.js. Para amostras de código que usam o middleware da Microsoft, confira a seção Introdução à plataforma de identidade da Microsoft.
Se você estiver criando um aplicativo móvel ou de área de trabalho, poderá usar uma das MSAL (Bibliotecas de Autenticação da Microsoft). Essas bibliotecas estão em disponibilidade geral ou em uma versão prévia com suporte de produção, portanto, é seguro usá-las em aplicativos de produção. Leia mais sobre os termos da versão prévia e as bibliotecas disponíveis na referência de bibliotecas de autenticação.
Para outras plataformas não abrangidas pelas bibliotecas da Microsoft, é possível fazer a integração com o ponto de extremidade da plataforma de identidade da Microsoft enviando e recebendo diretamente mensagens de protocolo no código do aplicativo. Os protocolos OAuth e OpenID Connect foram explicitamente documentados para ajudar você a executar essa integração.
Por fim, você pode usar bibliotecas de software livre do OpenID Connect e do OAuth para fazer a integração com o ponto de extremidade da plataforma de identidade da Microsoft. O ponto de extremidade da plataforma de identidade da Microsoft deve ser compatível com muitas bibliotecas de protocolo de software livre sem alterações. A disponibilidade desses tipos de bibliotecas varia por idioma e plataforma. Os sites do Open ID Connect e do OAuth 2.0 mantêm uma lista das implementações populares. Para saber mais, confira Bibliotecas de autenticação e plataforma de identidade da Microsoft e para obter a lista de bibliotecas de cliente de software livre e exemplos testados com o ponto de extremidade da plataforma de identidade da Microsoft.
Para referência, o .well-known ponto de extremidade para o ponto de extremidade comum da plataforma de identidade da Microsoft é https://login.microsoftonline.com/common/v2.0/.well-known/openid-configuration. Substitua common pela ID do locatário para obter dados específicos para o locatário.

Alterações do protocolo

O ponto de extremidade da plataforma de identidade da Microsoft não dá suporte ao SAML ou Web Services Federation; ele dá suporte apenas ao OpenID Connect e OAuth 2.0. As alterações importantes para os protocolos OAuth 2.0 do ponto de extremidade v1.0 são:

A declaração email será retornada somente se uma declaração opcional estiver configurada ou scope=email tiver sido especificado na solicitação.
O parâmetro scope agora tem suporte em vez do resource parâmetro.
Muitas respostas foram modificadas para torná-lo mais compatível com a especificação do OAuth 2.0, por exemplo, retornando corretamente expires_in como um int em vez de uma cadeia de caracteres.

Para entender melhor o escopo da funcionalidade de protocolo com suporte no ponto de extremidade plataforma de identidade da Microsoft, leia a referência de protocolo do OpenID Connect e OAuth 2.0.

Uso de SAML

Se você tiver usado a ADAL (Biblioteca de Autenticação do Active Directory) em aplicativos Windows, poderá aproveitar a autenticação integrada do Windows, que usa a concessão de declaração SAML (Security Assertion Markup Language). Com essa concessão, os usuários de locatários federados do Microsoft Entra podem se autenticar silenciosamente com sua instância local do Active Directory sem inserir credenciais. Embora o SAML ainda seja um protocolo com suporte para uso com usuários corporativos, o ponto de extremidade v2.0 é usado apenas com aplicativos OAuth 2.0.

Próximas etapas

Saiba mais na documentação da plataforma de identidade da Microsoft.