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

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

Quem pode iniciar sessão

• O ponto de extremidade v1.0 permite que apenas contas corporativas e de estudante entrem em seu aplicativo (Azure AD)
• O ponto de extremidade da plataforma de identidade da Microsoft permite que contas de trabalho e educacionais do Microsoft Entra ID e contas pessoais da Microsoft (MSA), como hotmail.com, outlook.com e msn.com, façam login.
• Ambos os endpoints também aceitam inícios de sessão de utilizadores convidados de um diretório da Microsoft Entra para aplicações configuradas como único inquilino ou para aplicações multi-inquilino configuradas para apontar para o endpoint específico do inquilino (https://login.microsoftonline.com/{TenantId_or_Name}).

O endpoint da plataforma de identidade da Microsoft permite escrever apps que aceitam inícios de sessão de contas pessoais da Microsoft, bem como contas de trabalho e de escola. Isso lhe dá a capacidade de escrever seu aplicativo completamente independente da conta. Por exemplo, se seu aplicativo chamar o Microsoft Graph, algumas funcionalidades e dados adicionais estarão disponíveis para contas de trabalho, como seus sites do SharePoint ou dados de diretório. Mas para muitas ações, como ler o e-mail de um usuário, o mesmo código pode acessar o e-mail para contas pessoais e de trabalho e de escola.

Para o endpoint da plataforma de identidade da Microsoft, pode-se usar a 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 entradas somente de contas corporativas e de estudante.

Consentimento incremental e dinâmico

Os aplicativos que usam o ponto de extremidade do Azure AD v1.0 precisam especificar suas permissões OAuth 2.0 necessárias com antecedência, por exemplo:

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

• O aplicativo precisa solicitar todas as permissões necessárias no primeiro login do usuário. Isso pode levar a uma longa lista de permissões que desencoraja os usuários finais de aprovar o acesso do aplicativo no login inicial.

• O aplicativo precisa saber todos os recursos que acessaria com antecedência. Era difícil criar aplicativos que pudessem acessar um número arbitrário de recursos.

Com o endpoint da plataforma de identidade da Microsoft, pode ignorar as permissões estáticas definidas nas informações de registo da aplicação no portal do Azure e solicitar permissões de forma incremental. Isto significa pedir inicialmente um conjunto mínimo de permissões e ir aumentando gradualmente conforme o cliente utilize funcionalidades adicionais da aplicação. Para fazer isso, você pode especificar os escopos de que seu aplicativo precisa a qualquer momento, incluindo os novos escopos scope no parâmetro ao solicitar um token de acesso - sem a necessidade de predefini-los nas informações de registro do aplicativo. Se o usuário ainda não tiver consentido com novos escopos adicionados à solicitação, ele será solicitado a consentir apenas com as novas permissões. Para saber mais, consulte Permissões, consentimento e escopos.

Permitir que um aplicativo solicite permissões dinamicamente por meio do parâmetro dá aos desenvolvedores controle total sobre a scope experiência do usuário. Você também pode carregar antecipadamente sua experiência de consentimento e solicitar todas as permissões em uma solicitação de autorização inicial. Se o seu aplicativo exigir um grande número de permissões, você poderá coletar essas permissões do usuário incrementalmente à medida que ele tenta usar determinados recursos do aplicativo ao longo do tempo.

O consentimento de administrador feito em nome de uma organização ainda requer 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 que um administrador dê 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 ponto de extremidade v1.0, um aplicativo pode se comportar como um recurso ou um destinatário de tokens. Um recurso pode definir vários escopos ou oAuth2Permissions que ele entende, permitindo que aplicativos cliente solicitem tokens desse recurso para um determinado conjunto de escopos. Considere a API do Microsoft Graph como um exemplo de recurso:

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

Isso é válido para o endpoint da plataforma de identidade da Microsoft. Um aplicativo ainda pode se comportar como um recurso, definir escopos e ser identificado por um URI. Os aplicativos cliente ainda podem solicitar acesso a esses escopos. No entanto, a maneira como um cliente solicita essas permissões mudou.

Para o endpoint v1.0, um pedido de autorização OAuth 2.0 para o Azure AD poderia ter sido como:

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

Aqui, o parâmetro resource indicou qual recurso o aplicativo cliente está solicitando autorização. O Azure AD calculou as permissões exigidas pelo aplicativo com base na configuração estática no portal do Azure e emitiu tokens de acordo.

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

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, o parâmetro scope indica qual recurso e permissões o aplicativo está solicitando autorização. O recurso desejado ainda está presente na solicitação - ele está englobado em cada um dos valores do parâmetro scope. O uso do parâmetro scope dessa maneira permite que o ponto de extremidade da plataforma de identidade da Microsoft seja mais compatível com a especificação OAuth 2.0 e se alinha mais estreitamente com as práticas comuns do setor. Ele também permite que os aplicativos façam consentimento incremental - solicitando permissões apenas quando o aplicativo as exige, em vez de antecipadamente.

Âmbitos bem conhecidos

Acesso off-line

As aplicações que utilizam o ponto final da plataforma de identidade da Microsoft podem requerer o uso de uma nova permissão bem conhecida para aplicações - o escopo offline_access. Todos os aplicativos precisarão 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 não estiver usando ativamente o aplicativo. O offline_access escopo aparecerá para o usuário em diálogos de consentimento como Acessar seus dados a qualquer momento, com o qual o usuário deve concordar. Solicitar a offline_access permissão permitirá que o seu aplicativo Web receba tokens de atualização OAuth 2.0 do endpoint 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 OAuth 2.0 por longos períodos de acesso.

Se a sua aplicação não solicitar o offline_access scope, não receberá tokens de atualização. Isso significa que, ao resgatar um código de autorização no fluxo de código de autorização do OAuth 2.0, você receberá de volta apenas um token de acesso do /token ponto de extremidade. Esse token de acesso permanece válido por um curto período de tempo (normalmente uma hora), mas acabará expirando. Naquele momento, a sua aplicação precisará redirecionar o utilizador de volta ao /authorize endpoint para recuperar um novo código de autorização. Durante esse redirecionamento, o usuário pode ou não precisar inserir suas credenciais novamente ou reconsentir com permissões, dependendo do tipo de aplicativo.

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

OpenID, perfil e e-mail

Historicamente, o fluxo de entrada mais básico do OpenID Connect com a plataforma de identidade da Microsoft forneceria 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 e-mail, ID do objeto e muito mais.

As informações às quais o openid escopo oferece acesso ao seu aplicativo agora são restritas. O openid escopo permitirá apenas que o seu aplicativo faça login do utilizador e receba um identificador específico da aplicação para o utilizador. Se você quiser obter dados pessoais sobre o usuário em seu aplicativo, seu aplicativo precisa solicitar permissões adicionais do usuário. Dois novos escopos email e profile, permitirão que você solicite permissões adicionais.

• O email escopo permite que seu aplicativo acesse o endereço de e-mail principal do usuário por meio da email declaração no id_token, supondo que o usuário tenha um endereço de e-mail endereçável.
• O profile escopo oferece ao seu aplicativo acesso a todas as outras informações básicas sobre o usuário, como nome, nome de usuário preferido, ID do objeto e assim por diante, no id_token.

Esses escopos permitem que você codifique seu aplicativo de forma minimalista para que você só possa pedir 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, consulte a referência de escopo da plataforma de identidade da Microsoft.

Declarações de tokens

O endpoint da plataforma de identidade da Microsoft emite, por omissão, um conjunto menor de declarações nos seus tokens para manter as cargas úteis pequenas. Se você tiver aplicativos e serviços que dependam de uma declaração específica em um token v1.0 que não é mais fornecido por padrão em um token de plataforma de identidade da Microsoft, considere usar o recurso de declarações opcional para incluir essa declaração.

Importante

Os tokens v1.0 e v2.0 podem ser emitidos tanto pelos endpoints v1.0 quanto pelos endpoints v2.0! 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 da Web que seu cliente chamará usando esse token. Portanto, se a sua aplicação usa o endpoint v2.0 para obter um token para chamar o Microsoft Graph, que espera tokens de acesso em formato v1.0, a sua aplicação receberá um token em formato v1.0.

Limitações

Há 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 autenticação da plataforma de identidade da Microsoft atendem às suas necessidades. O ponto de extremidade e a plataforma v1.0 ainda são totalmente suportados e, em alguns aspetos, são mais ricos 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.

Aqui está uma recomendação simplificada para desenvolvedores agora:

• Se você quiser ou precisar oferecer suporte a contas pessoais da Microsoft em seu aplicativo ou estiver escrevendo um novo aplicativo, use a plataforma de identidade da Microsoft. Mas antes de o fazer, certifique-se de que compreende as limitações discutidas neste artigo.
• Se você estiver migrando ou atualizando um aplicativo que depende do SAML, não poderá usar a plataforma de identidade da Microsoft. Em vez disso, consulte o guia do Azure AD v1.0.

O ponto de extremidade da plataforma de identidade da Microsoft evoluirá para eliminar as restrições listadas aqui, de modo que você só precisará usar o ponto de extremidade da 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 si. Continuaremos a atualizar este artigo para refletir o estado atual do endpoint da plataforma de identidade da Microsoft. Verifique novamente para reavaliar seus requisitos em relação aos recursos da plataforma de identidade da Microsoft.

Restrições aos registos de aplicações

Para cada aplicativo que você deseja integrar com o 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 da 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.

Os registos de aplicações que suportam contas escolares e profissionais e contas pessoais têm as seguintes ressalvas:

• Apenas dois segredos de aplicativo são permitidos por ID de 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. Este é o caso da maioria das aplicações que foram registadas utilizando uma conta Microsoft pessoal no Portal de Registo de Aplicações. Se você quiser compartilhar seu registro de aplicativo com vários desenvolvedores, registre o aplicativo em um locatário usando a nova seção Registros de aplicativo do portal do Azure.
• Há várias restrições sobre o formato do URL de redirecionamento permitido. Para obter mais informações sobre URL de redirecionamento, consulte a próxima seção.

Restrições em URLs de redirecionamento

Para obter informações mais atuais sobre as restrições em URLs de redirecionamento para aplicativos registados na plataforma de identidade da Microsoft, consulte Restrições e limitações de URI/URL de resposta 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, consulte Registrar um aplicativo usando a nova experiência de registros de aplicativo.

Restrições em bibliotecas e SDKs

Atualmente, a compatibilidade de bibliotecas para o ponto de extremidade da plataforma de identidade da Microsoft é limitada. Se quiser usar o ponto de extremidade da plataforma de identidade da Microsoft em um aplicativo de produção, você tem estas opções:

• Se você estiver criando um aplicativo Web, poderá usar com segurança o middleware do lado do servidor geralmente disponível para fazer login e validação de token. Estes incluem o middleware OWIN OpenID Connect para ASP.NET e o plug-in Node.js Passport. Para obter exemplos de código que usam middleware da Microsoft, consulte a seção Introdução à plataforma de identidade da Microsoft .
• Se estiver a criar uma aplicação de ambiente de trabalho ou móvel, pode utilizar uma das Bibliotecas de Autenticação da Microsoft (MSAL). Essas bibliotecas estão geralmente disponíveis ou em uma versão prévia suportada para produção, portanto, é seguro usá-las em aplicações de produção. Você pode ler mais informações sobre os termos de pré-visualização e as bibliotecas disponíveis na referência de bibliotecas de autenticação.
• Para plataformas não cobertas por bibliotecas da Microsoft, você pode integrar 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 OpenID Connect e OAuth estão explicitamente documentados para ajudá-lo a fazer essa integração.
• Finalmente, pode usar bibliotecas de código aberto OpenID Connect e OAuth para integrar com o endpoint 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 código aberto sem alterações. A disponibilidade deste tipo de bibliotecas varia consoante a língua e a plataforma. Os sites OpenID Connect e OAuth 2.0 mantêm uma lista de implementações populares. Para obter mais informações, consulte Plataforma de identidade da Microsoft e bibliotecas de autenticação e a lista de bibliotecas de cliente de código aberto e exemplos que foram testados com o ponto de extremidade da plataforma de identidade da Microsoft.
• Para referência, o .well-known ponto de extremidade para a plataforma de identidade comum da Microsoft é https://login.microsoftonline.com/common/v2.0/.well-known/openid-configuration. Substitua common pelo ID do locatário para obter dados específicos do locatário.

Alterações ao protocolo

O ponto de extremidade da plataforma de identidade da Microsoft não suporta SAML ou WS-Federation; ele suporta apenas OpenID Connect e OAuth 2.0. As alterações notáveis nos protocolos OAuth 2.0 do endpoint v1.0 são:

• A email declaração é devolvida se uma declaração opcional estiver configurada ou o âmbito=email tiver sido especificado no pedido.
• O scope parâmetro agora é suportado no lugar do resource parâmetro.
• Muitas respostas foram modificadas para torná-las mais compatíveis com a especificação OAuth 2.0, por exemplo, retornando expires_in corretamente como um int em vez de uma cadeia de caracteres.

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

Uso do SAML

Se você usou a Biblioteca de Autenticação do Ative Directory (ADAL) em aplicativos do Windows, talvez tenha aproveitado a autenticação integrada do Windows, que usa a concessão de asserçã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 Ative Directory sem inserir credenciais. Embora o SAML ainda seja um protocolo suportado para uso com usuários corporativos, o ponto de extremidade v2.0 é apenas para uso com aplicativos OAuth 2.0.

Próximos passos

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