Porquê atualizar a plataforma de identidade da Microsoft (v2.0)?

Artigo
11/09/2022

Ao desenvolver uma nova aplicação, é importante saber as diferenças entre os pontos finais do plataforma de identidades da Microsoft (v2.0) e do Azure Active Directory (v1.0). Este artigo aborda as principais diferenças entre os pontos finais e algumas limitações existentes para plataforma de identidades da Microsoft.

Quem pode iniciar sessão com pontos finais v1.0 e v2.0

O ponto final v1.0 permite que apenas as contas escolares e profissionais iniciem sessão na sua aplicação (Azure AD)
O ponto final plataforma de identidades da Microsoft permite que as contas escolares e profissionais de Microsoft Entra ID e contas Microsoft pessoais (MSA), como hotmail.com, outlook.com e msn.com, iniciem sessão.
Ambos os pontos finais também aceitam inícios de sessão de utilizadores convidados de um diretório Microsoft Entra para aplicações configuradas como inquilino único ou para aplicações multi-inquilino configuradas para apontar para o ponto final específico do inquilino (https://login.microsoftonline.com/{TenantId_or_Name}).

O ponto final plataforma de identidades da Microsoft permite-lhe escrever aplicações que aceitam inícios de sessão de contas Microsoft pessoais e contas escolares e profissionais. Isto permite-lhe escrever a sua aplicação completamente agnóstica. Por exemplo, se a sua aplicação chamar o Microsoft Graph, algumas funcionalidades e dados adicionais estarão disponíveis para contas profissionais, como os respetivos sites do SharePoint ou dados de diretório. Contudo, para muitas ações, como Ler o correio de um utilizador, o mesmo código pode aceder ao e-mail para contas pessoais, profissionais e escolares.

Para plataforma de identidades da Microsoft ponto final, pode utilizar a Biblioteca de Autenticação da Microsoft (MSAL) para obter acesso aos mundos do consumidor, educacional e empresarial. O ponto final Azure AD v1.0 aceita apenas inícios de sessão de contas escolares e profissionais.

As aplicações que utilizam o ponto final Azure AD v1.0 são necessárias para especificar antecipadamente as permissões OAuth 2.0 necessárias, por exemplo:

Exemplo que mostra a IU de Registo de Permissões

As permissões definidas diretamente no registo da aplicação são estáticas. Embora as permissões estáticas da aplicação definidas no portal do Azure manter o código simples e agradável, apresenta alguns problemas possíveis para os programadores:

A aplicação precisa de pedir todas as permissões necessárias no primeiro início de sessão do utilizador. Isto pode levar a uma longa lista de permissões que desencoraja os utilizadores finais de aprovarem o acesso da aplicação no início de sessão inicial.
A aplicação precisa de saber todos os recursos a que acederia antecipadamente. Foi difícil criar aplicações que pudessem aceder a um número arbitrário de recursos.

Com o ponto final plataforma de identidades da Microsoft, pode ignorar as permissões estáticas definidas nas informações de registo de aplicações no portal do Azure e pedir permissões de forma incremental, o que significa pedir um conjunto mínimo de permissões antecipadamente e crescer mais ao longo do tempo à medida que o cliente utiliza funcionalidades adicionais da aplicação. Para tal, pode especificar os âmbitos de que a sua aplicação precisa em qualquer altura ao incluir os novos âmbitos no scope parâmetro ao pedir um token de acesso, sem a necessidade de os pré-definir nas informações de registo da aplicação. Se o utilizador ainda não tiver consentido novos âmbitos adicionados ao pedido, ser-lhe-á pedido que autorize apenas as novas permissões. Para saber mais, veja permissões, consentimento e âmbitos.

Permitir que uma aplicação solicite permissões dinamicamente através do scope parâmetro dá aos programadores controlo total sobre a experiência do utilizador. Também pode carregar antecipadamente a sua experiência de consentimento e pedir todas as permissões num pedido de autorização inicial. Se a sua aplicação precisar de um grande número de permissões, pode recolher essas permissões do utilizador de forma incremental à medida que tenta utilizar determinadas funcionalidades da aplicação ao longo do tempo.

Administração consentimento feito em nome de uma organização ainda requer as permissões estáticas registadas para a aplicação, pelo que deve definir essas permissões para aplicações no portal de registo de aplicações se precisar que um administrador dê consentimento em nome de toda a organização. Isto reduz os ciclos exigidos pelo administrador da organização para configurar a aplicação.

Âmbitos, não recursos

Para aplicações que utilizam o ponto final v1.0, uma aplicação pode comportar-se como um recurso ou um destinatário de tokens. Um recurso pode definir vários âmbitos ou oAuth2Permissions que compreende, permitindo que as aplicações cliente solicitem tokens a partir desse recurso para um determinado conjunto de âmbitos. Considere o microsoft Graph API como um exemplo de um recurso:

Identificador de recurso ou AppID URI: https://graph.microsoft.com/
Âmbitos, ou oAuth2Permissions: Directory.Read, , Directory.Writee assim sucessivamente.

Isto aplica-se ao ponto final plataforma de identidades da Microsoft. Uma aplicação ainda pode comportar-se como um recurso, definir âmbitos e ser identificada por um URI. As aplicações cliente ainda podem pedir acesso a esses âmbitos. No entanto, a forma como um cliente pede essas permissões foi alterada.

Para o ponto final v1.0, um pedido de autorização do OAuth 2.0 para Azure AD poderá ter sido semelhante a:

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

Aqui, o parâmetro de recurso indicou o recurso que a aplicação cliente está a pedir autorização. Azure AD calculou as permissões exigidas pela aplicação com base na configuração estática no portal do Azure e os tokens emitidos em conformidade.

Para aplicações que utilizam o ponto final plataforma de identidades da Microsoft, o mesmo pedido de autorização OAuth 2.0 tem o seguinte aspeto:

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 de âmbito indica que recursos e permissões a aplicação está a pedir autorização. O recurso pretendido ainda está presente no pedido. Está englobado em cada um dos valores do parâmetro de âmbito. A utilização do parâmetro de âmbito desta forma permite que o ponto final plataforma de identidades da Microsoft seja mais compatível com a especificação OAuth 2.0 e alinha-se mais estreitamente com as práticas comuns do setor. Também permite que as aplicações dêem consentimento incremental , solicitando apenas permissões quando a aplicação as exigir em vez de iniciais.

Âmbitos bem conhecidos

Acesso offline

As aplicações que utilizam o ponto final plataforma de identidades da Microsoft podem exigir a utilização de uma nova permissão conhecida para aplicações – o offline_access âmbito. Todas as aplicações terão de pedir esta permissão se precisarem de aceder aos recursos em nome de um utilizador durante um período de tempo prolongado, mesmo quando o utilizador pode não estar a utilizar ativamente a aplicação. O offline_access âmbito será apresentado ao utilizador nas caixas de diálogo de consentimento como Aceder aos seus dados em qualquer altura, com o qual o utilizador tem de concordar. Pedir a offline_access permissão permitirá que a aplicação Web receba o OAuth 2.0 refresh_tokens do ponto final plataforma de identidades 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 para períodos de acesso prolongados.

Se a aplicação não pedir o offline_access âmbito, não receberá tokens de atualização. Isto significa que, quando resgatar um código de autorização no fluxo de código de autorização OAuth 2.0, só receberá um token de acesso do /token ponto final. Esse token de acesso permanece válido por um curto período de tempo (normalmente uma hora), mas irá eventualmente expirar. Nessa altura, a aplicação terá de redirecionar o utilizador de volta para o /authorize ponto final para obter um novo código de autorização. Durante este redirecionamento, o utilizador pode ou não precisar de introduzir as credenciais novamente ou voltar a reunir permissões, dependendo do tipo de aplicação.

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

OpenID, perfil e e-mail

Historicamente, o fluxo de início de sessão do OpenID Connect mais básico com plataforma de identidades da Microsoft forneceria muitas informações sobre o utilizador nas id_token resultantes. As afirmações num id_token podem incluir o nome do utilizador, o nome de utilizador preferencial, o endereço de e-mail, o ID do objeto e muito mais.

As informações às quais o openid âmbito dá acesso à sua aplicação são agora restritas. O openid âmbito só permitirá que a sua aplicação inicie sessão no utilizador e receba um identificador específico da aplicação para o utilizador. Se quiser obter dados pessoais sobre o utilizador na sua aplicação, a sua aplicação tem de pedir permissões adicionais ao utilizador. Dois novos âmbitos, email e profile, permitir-lhe-ão pedir permissões adicionais.

O email âmbito permite que a sua aplicação aceda ao endereço de e-mail principal do utilizador através da email afirmação no id_token, assumindo que o utilizador tem um endereço de e-mail endereçável.
O profile âmbito dá à sua aplicação acesso a todas as outras informações básicas sobre o utilizador, como o respetivo nome, nome de utilizador preferencial, ID de objeto, etc., no id_token.

Estes âmbitos permitem-lhe codificar a sua aplicação de uma forma de divulgação mínima para que só possa pedir ao utilizador o conjunto de informações de que a sua aplicação precisa para fazer o seu trabalho. Para obter mais informações sobre estes âmbitos, veja a referência de âmbito plataforma de identidades da Microsoft.

Afirmações de tokens

O ponto final plataforma de identidades da Microsoft emite um conjunto mais pequeno de afirmações nos seus tokens por predefinição para manter os payloads pequenos. Se tiver aplicações e serviços que tenham uma dependência de uma afirmação específica num token v1.0 que já não seja fornecido por predefinição num token de plataforma de identidades da Microsoft, considere utilizar a funcionalidade de afirmações opcionais para incluir essa afirmação.

Importante

Os tokens v1.0 e v2.0 podem ser emitidos pelos pontos finais v1.0 e v2.0! id_tokens correspondem sempre ao ponto final a partir do qual são pedidos e os tokens de acesso correspondem sempre ao formato esperado pela API Web que o cliente irá chamar com esse token. Por isso, se a sua aplicação utilizar o ponto final v2.0 para obter um token para chamar o Microsoft Graph, que espera tokens de acesso de formato v1.0, a sua aplicação receberá um token no formato v1.0.

Limitações

Existem algumas restrições a ter em conta ao utilizar plataforma de identidades da Microsoft.

Quando cria aplicações que se integram com o plataforma de identidades da Microsoft, tem de decidir se os protocolos de autenticação e ponto final plataforma de identidades da Microsoft satisfazem as suas necessidades. O ponto final e a plataforma v1.0 ainda são totalmente suportados e, em alguns aspetos, são mais ricos em funcionalidades do que plataforma de identidades da Microsoft. No entanto, plataforma de identidades da Microsoft introduz benefícios significativos para os programadores.

Eis uma recomendação simplificada para programadores agora:

Se quiser ou precisar de suportar contas Microsoft pessoais na sua aplicação ou se estiver a escrever uma nova aplicação, utilize plataforma de identidades da Microsoft. Mas antes de o fazer, certifique-se de que compreende as limitações abordadas neste artigo.
Se estiver a migrar ou a atualizar uma aplicação que depende de SAML, não poderá utilizar plataforma de identidades da Microsoft. Em vez disso, consulte o guia Azure AD v1.0.

O ponto final plataforma de identidades da Microsoft irá evoluir para eliminar as restrições aqui listadas, para que só precise de utilizar o ponto final plataforma de identidades da Microsoft. Entretanto, utilize este artigo para determinar se o ponto final plataforma de identidades da Microsoft é adequado para si. Continuaremos a atualizar este artigo para refletir o estado atual do ponto final plataforma de identidades da Microsoft. Verifique novamente para reavaliar os seus requisitos em relação às capacidades plataforma de identidades da Microsoft.

Restrições aos registos de aplicações

Para cada aplicação que pretende integrar com o ponto final plataforma de identidades da Microsoft, pode criar um registo de aplicação na nova experiência de Registos de aplicações no portal do Azure. As aplicações da conta Microsoft existentes não são compatíveis com o portal, mas todas as aplicações Microsoft Entra são, independentemente de onde ou quando foram registadas.

Registos de aplicações que suportam contas escolares e profissionais e contas pessoais têm as seguintes limitações:

Apenas dois segredos da aplicação são permitidos por ID da aplicação.
Uma aplicação que não tenha sido registada num inquilino só pode ser gerida pela conta que a registou. Não pode ser partilhado com outros programadores. Este é o caso da maioria das aplicações registadas com uma conta Microsoft pessoal no Portal de Registo de Aplicações. Se quiser partilhar o registo de aplicações com vários programadores, registe a aplicação num inquilino com a nova secção Registos de aplicações do portal do Azure.
Existem várias restrições no formato do URL de redirecionamento permitido. Para obter mais informações sobre o URL de redirecionamento, consulte a secção seguinte.

Restrições aos URLs de redirecionamento

Para obter as informações mais atualizadas sobre restrições de URLs de redirecionamento para aplicações registadas para plataforma de identidades da Microsoft, veja Redirecionar restrições e limitações de URLs de resposta/URI na documentação do plataforma de identidades da Microsoft.

Para saber como registar uma aplicação para utilização com plataforma de identidades da Microsoft, consulte Registar uma aplicação com a nova experiência de Registos de aplicações.

Restrições a bibliotecas e SDKs

Atualmente, o suporte da biblioteca para o ponto final plataforma de identidades da Microsoft é limitado. Se quiser utilizar o ponto final plataforma de identidades da Microsoft numa aplicação de produção, tem estas opções:

Se estiver a criar uma aplicação Web, pode utilizar com segurança o middleware do lado do servidor geralmente disponível para efetuar a validação de início de sessão e token. Estes incluem o middleware OWIN OpenID Connect para ASP.NET e o plug-in do Node.js Passport. Para obter exemplos de código que utilizam middleware da Microsoft, veja a secção plataforma de identidades da Microsoft introdução.
Se estiver a criar uma aplicação móvel ou de ambiente de trabalho, pode utilizar uma das Bibliotecas de Autenticação da Microsoft (MSAL). Estas bibliotecas estão geralmente disponíveis ou numa pré-visualização suportada pela produção, pelo que é seguro utilizá-las em aplicações de produção. Pode ler mais sobre os termos da pré-visualização e as bibliotecas disponíveis na referência de bibliotecas de autenticação.
Para plataformas não abrangidas pelas bibliotecas Da Microsoft, pode integrar com o ponto final plataforma de identidades da Microsoft ao enviar e receber diretamente mensagens de protocolo no código da aplicação. Os protocolos OpenID Connect e OAuth estão explicitamente documentados para o ajudar a efetuar essa integração.
Por fim, pode utilizar bibliotecas OpenID Connect e OAuth open source para integrar com o ponto final plataforma de identidades da Microsoft. O ponto final plataforma de identidades da Microsoft deve ser compatível com muitas bibliotecas de protocolo open source sem alterações. A disponibilidade destes tipos de bibliotecas varia de acordo com a linguagem e a plataforma. Os sites OpenID Connect e OAuth 2.0 mantêm uma lista de implementações populares. Para obter mais informações, veja plataforma de identidades da Microsoft e bibliotecas de autenticação e a lista de bibliotecas de cliente open source e exemplos que foram testados com o ponto final plataforma de identidades da Microsoft.
Para referência, o .well-known ponto final da plataforma de identidades da Microsoft ponto final comum é https://login.microsoftonline.com/common/v2.0/.well-known/openid-configuration. Substitua pelo common seu ID de inquilino para obter dados específicos para o seu inquilino.

Alterações de protocolo

O ponto final plataforma de identidades da Microsoft não suporta SAML ou WS-Federation; só suporta OpenID Connect e OAuth 2.0. As alterações notáveis aos protocolos OAuth 2.0 do ponto final v1.0 são:

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

Para compreender melhor o âmbito da funcionalidade de protocolo suportada no ponto final plataforma de identidades da Microsoft, veja Referência do protocolo OpenID Connect e OAuth 2.0.

Utilização saml

Se utilizou a Biblioteca de Autenticação do Active Directory (ADAL) em aplicações windows, poderá ter aproveitado a autenticação Integrada do Windows, que utiliza a concessão de asserção de Linguagem SAML (Security Assertion Markup Language). Com esta concessão, os utilizadores de inquilinos de Microsoft Entra federados podem autenticar-se automaticamente com a respetiva instância de Active Directory no local sem introduzir credenciais. Embora o SAML continue a ser um protocolo suportado para utilização com utilizadores empresariais, o ponto final v2.0 é apenas para utilização com aplicações OAuth 2.0.

Passos seguintes

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