Plataforma de identidade microsoft e protocolo OpenID Connect

  • Artigo
  • 17 minutos para ler

O OpenID Connect (OIDC) é um protocolo de autenticação baseado no OAuth 2.0 que pode utilizar para iniciar de forma segura a sessão de um utilizador numa aplicação. Quando utilizar a implementação da plataforma de identidade da Microsoft do OpenID Connect, pode adicionar acesso de sôs-in e API às suas aplicações. Este artigo mostra como fazê-lo independentemente da linguagem e descreve como enviar e receber mensagens HTTP sem usar quaisquer bibliotecas de código aberto da Microsoft.

O OpenID Connect alarga o protocolo de autorização OAuth 2.0 para utilização como protocolo de autenticação , para que possa fazer um único início de sposição utilizando o OAuth. O OpenID Connect introduz o conceito de um token de ID, que é um símbolo de segurança que permite ao cliente verificar a identidade do utilizador. O token de ID também obtém informações básicas de perfil sobre o utilizador. Também introduz o ponto final do UserInfo, uma API que devolve informações sobre o utilizador.

Dica

Try running this request in Postman
Tente executar este pedido e muito mais no Carteiro.

Diagrama de protocolo: Início de sação

O fluxo de entrada mais básico tem os passos mostrados no diagrama seguinte. Cada passo é descrito em detalhe neste artigo.

OpenID Connect protocol: Sign-in

Pegue o documento de metadados OpenID Connect

O OpenID Connect descreve um documento de metadados (RFC) que contém a maioria das informações necessárias para que uma aplicação faça o sôm. Isto inclui informações como os URLs a utilizar e a localização das chaves de assinatura pública do serviço. Pode encontrar este documento anexando o caminho do documento de descoberta para o URL da autoridade:

Caminho do documento de descoberta: /.well-known/openid-configuration

Autoridade: https://login.microsoftonline.com/{tenant}/v2.0

A {tenant} lata leva um de quatro valores:

Valor Descrição
common Os utilizadores com uma conta pessoal da Microsoft e uma conta de trabalho ou escola da Azure AD podem iniciar scontabilidade na aplicação.
organizations Apenas os utilizadores com contas de trabalho ou escola da Azure AD podem iniciar scontabilidade na aplicação.
consumers Apenas os utilizadores com uma conta pessoal da Microsoft podem iniciar scontabilidade na aplicação.
8eaef023-2b34-4da1-9baa-8bc8c9d6a490 ou contoso.onmicrosoft.com Apenas os utilizadores de um inquilino específico da Azure AD (sejam membros do diretório com uma conta de trabalho ou de escola, ou se são hóspedes no diretório com uma conta pessoal da Microsoft) podem inscrever-se na aplicação. Ou o nome de domínio amigável do inquilino AZure AD ou o identificador GUID do inquilino podem ser usados. Você também pode usar o inquilino de consumo, 9188040d-6c67-4c5b-b112-36a304b66dadno lugar do consumers inquilino.

A autoridade difere entre as nuvens nacionais - por exemplo, https://login.microsoftonline.de para o exemplo da Azure AD Alemanha. Se não utilizar a nuvem pública, por favor reveja os pontos finais da nuvem nacional para encontrar o adequado para si. Certifique-se de que o arrendatário e está /v2.0/ presente no seu pedido para que possa utilizar a versão v2.0 do ponto final.

Dica

Experimente! Clique https://login.microsoftonline.com/common/v2.0/.well-known/openid-configuration para ver a common configuração.

Pedido de amostra

Para chamar o ponto final userinfo para a autoridade comum na nuvem pública, use o seguinte:

GET /common/v2.0/.well-known/openid-configuration
Host: login.microsoftonline.com

Resposta de amostra

Os metadados são um documento simples de Notação de Objetos JavaScript (JSON). Veja o seguinte corte para um exemplo. O conteúdo está totalmente descrito na especificação OpenID Connect.

{
  "authorization_endpoint": "https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize",
  "token_endpoint": "https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token",
  "token_endpoint_auth_methods_supported": [
    "client_secret_post",
    "private_key_jwt"
  ],
  "jwks_uri": "https://login.microsoftonline.com/{tenant}/discovery/v2.0/keys",
  "userinfo_endpoint": "https://graph.microsoft.com/oidc/userinfo",
  "subject_types_supported": [
      "pairwise"
  ],
  ...

}

Se a sua aplicação tiver teclas de assinatura personalizadas como resultado da utilização da funcionalidade de mapeamento de reclamações , tem de anexar um appid parâmetro de consulta que contenha o ID da aplicação para obter uma jwks_uri indicação para as informações-chave de assinatura da sua aplicação. Por exemplo: https://login.microsoftonline.com/{tenant}/v2.0/.well-known/openid-configuration?appid=6731de76-14a6-49ae-97bc-6eba6914391e contém um jwks_uri de https://login.microsoftonline.com/{tenant}/discovery/v2.0/keys?appid=6731de76-14a6-49ae-97bc-6eba6914391e.

Normalmente, utilizaria este documento de metadados para configurar uma biblioteca OpenID Connect ou SDK; a biblioteca usaria os metadados para fazer o seu trabalho. No entanto, se não estiver a utilizar uma biblioteca OpenID Connect pré-construída, pode seguir os passos no restante deste artigo para fazer o sismo numa aplicação web utilizando a plataforma de identidade da Microsoft.

Envie o pedido de inscrição

Quando a sua aplicação web precisa de autenticar o utilizador, pode direcionar o utilizador para o /authorize ponto final. Este pedido é semelhante à primeira parte do fluxo de código de autorização OAuth 2.0, com estas distinções importantes:

  • O pedido deve incluir o openid âmbito de aplicação do scope parâmetro.
  • O response_type parâmetro deve incluir id_token.
  • O pedido deve incluir o nonce parâmetro.

Importante

Para solicitar com sucesso um sinal de ID do ponto final /autorização, o registo da aplicação no portal de registo deve ter a concessão implícita de id_tokens habilitada no separador autenticação (que define a oauth2AllowIdTokenImplicitFlow bandeira no manifesto de candidatura).true Se não estiver ativado, será devolvido um unsupported_response erro: "O valor fornecido para o parâmetro de entrada 'response_type' não é permitido para este cliente. Valor esperado é 'código'"

Por exemplo:

// Line breaks are for legibility only.

GET https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize?
client_id=6731de76-14a6-49ae-97bc-6eba6914391e
&response_type=id_token
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&response_mode=form_post
&scope=openid
&state=12345
&nonce=678910
Parâmetro Condição Descrição
tenant Obrigatório Pode utilizar o {tenant} valor no caminho do pedido para controlar quem pode iniciar sê-lo na aplicação. Os valores permitidos sãocommon, organizationsconsumerse os identificadores de inquilinos. Para mais informações, consulte o protocolo básico. Criticamente, para cenários de hóspedes em que você assina um utilizador de um inquilino em outro inquilino, você deve fornecer o identificador de inquilino para assinar corretamente no inquilino de recursos.
client_id Necessário O ID da Aplicação (cliente) que o portal Azure – Experiência de registos de aplicações atribuído à sua app.
response_type Necessário Deve incluir id_token para o iniciar sção de openID Connect. Também pode incluir outros response_type valores, tais como code.
redirect_uri Recomendado O redirecionamento URI da sua aplicação, onde as respostas de autenticação podem ser enviadas e recebidas pela sua aplicação. Deve corresponder exatamente a um dos URIs de redirecionamento que registou no portal, exceto que deve estar codificado por URL. Se não estiver presente, o ponto final escolherá um registado redirect_uri aleatoriamente para enviar o utilizador de volta.
scope Necessário Uma lista de âmbitos separados pelo espaço. Para o OpenID Connect, deve incluir o âmbito openid, que se traduz na permissão de Signo-lo na UI de consentimento. Pode também incluir outros âmbitos neste pedido de consentimento.
nonce Necessário Um valor incluído no pedido, gerado pela app, que será incluído no valor id_token resultante como reclamação. A aplicação pode verificar este valor para mitigar os ataques de reprodução de token. O valor normalmente é uma corda aleatória e única que pode ser usada para identificar a origem do pedido.
response_mode Recomendado Especifica o método que deve ser usado para enviar o código de autorização resultante de volta para a sua aplicação. Pode ser form_post ou fragment. Para aplicações web, recomendamos a utilização response_mode=form_post, para garantir a transferência mais segura de fichas para a sua aplicação.
state Recomendado Um valor incluído no pedido que também será devolvido na resposta simbólica. Pode ser uma série de conteúdos que quiser. Um valor único gerado aleatoriamente é normalmente usado para evitar ataques de falsificação de pedidos de trans-locais. O estado também é utilizado para codificar informações sobre o estado do utilizador na aplicação antes do pedido de autenticação ocorrer, como a página ou visualização em que o utilizador estava ligado.
prompt Opcional Indica o tipo de interação do utilizador que é necessária. Os únicos valores válidos neste momento sãologin, noneeconsentselect_account. A prompt=login alegação obriga o utilizador a introduzir as suas credenciais nesse pedido, o que nega uma única inscrição. O prompt=none parâmetro é o oposto, e deve ser emparelhado com um login_hint para indicar em que utilizador deve ser inscrito. Estes parâmetros garantem que o utilizador não é apresentado com qualquer solicitação interativa. Se o pedido não puder ser concluído silenciosamente através de um único sinal de sação (porque nenhum utilizador está inscrito, o utilizador insinuado não está inscrito ou há vários utilizadores inscritos e não é fornecida nenhuma sugestão), a plataforma de identidade da Microsoft retorna um erro. A prompt=consent alegação desencadeia o diálogo de consentimento OAuth após a indicação do utilizador. O diálogo pede ao utilizador que conceda permissões à aplicação. Por fim, select_account mostra ao utilizador um seletor de conta, negando sSO silencioso, mas permitindo ao utilizador escolher a conta com a qual pretende iniciar sessão, sem exigir entrada credencial. Não podem usar login_hint e select_account juntos.
login_hint Opcional Pode utilizar este parâmetro para pré-preenchimento do nome de utilizador e do campo de endereço de e-mail da página de início de s início para o utilizador, caso conheça o nome de utilizador com antecedência. Muitas vezes, as aplicações usam este parâmetro durante a reauthentication, depois de já terem extraído a login_hintreivindicação opcional de um início de sposição anterior.
domain_hint Opcional O reino do utilizador num diretório federado. Isto ignora o processo de descoberta baseado em e-mail que o utilizador passa na página de início de s início, para uma experiência de utilizador um pouco mais simplificada. Para os inquilinos que são federados através de um diretório no local como o AD FS, isso resulta frequentemente numa entrada perfeita por causa da sessão de login existente.

Neste momento, solicita-se ao utilizador que introduza as suas credenciais e complete a autenticação. A plataforma de identidade da Microsoft verifica que o utilizador consentiu com as permissões indicadas no scope parâmetro de consulta. Se o utilizador não tiver consentido com nenhuma dessas permissões, a plataforma de identidade da Microsoft solicita ao utilizador que consinta nas permissões necessárias. Você pode ler mais sobre permissões, consentimento e aplicativos multi-inquilinos.

Após o utilizador autenticar e conceder o consentimento, a plataforma de identidade da Microsoft devolve uma resposta à sua aplicação no URI de redirecionamento indicado, utilizando o método especificado no response_mode parâmetro.

Resposta bem sucedida

Uma resposta bem sucedida quando se usa response_mode=form_post assim:

POST /myapp/ HTTP/1.1
Host: localhost
Content-Type: application/x-www-form-urlencoded

id_token=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik1uQ19WWmNB...&state=12345
Parâmetro Description
id_token O sinal de identificação que a aplicação solicitou. Pode utilizar o id_token parâmetro para verificar a identidade do utilizador e iniciar uma sessão com o utilizador. Para obter mais informações sobre fichas de identificação e seus conteúdos, consulte a id_tokens referência.
state Se um state parâmetro for incluído no pedido, o mesmo valor deve aparecer na resposta. A aplicação deve verificar se os valores do Estado no pedido e resposta são idênticos.

Resposta de erro

As respostas de erro também podem ser enviadas para o URI de redirecionamento para que a aplicação possa manuseá-las. Uma resposta de erro é assim:

POST /myapp/ HTTP/1.1
Host: localhost
Content-Type: application/x-www-form-urlencoded

error=access_denied&error_description=the+user+canceled+the+authentication
Parâmetro Description
error Uma cadeia de código de erro que pode utilizar para classificar tipos de erros que ocorrem e para reagir a erros.
error_description Uma mensagem de erro específica que pode ajudá-lo a identificar a causa principal de um erro de autenticação.

Códigos de erro para erros de ponto final de autorização

A tabela a seguir descreve códigos de erro que podem ser devolvidos no error parâmetro da resposta de erro:

Código de erro Description Ação do cliente
invalid_request Erro de protocolo, como um parâmetro em falta, exigido. Corrija e reenvia o pedido. Este é um erro de desenvolvimento que normalmente é apanhado durante os testes iniciais.
unauthorized_client O pedido do cliente não pode solicitar um código de autorização. Isto ocorre geralmente quando a aplicação do cliente não está registada em Azure AD ou não é adicionada ao inquilino AZURE AD do utilizador. A aplicação pode solicitar ao utilizador instruções para instalar a aplicação e adicioná-la ao Azure AD.
access_denied O proprietário do recurso negou o consentimento. A aplicação do cliente pode notificar o utilizador de que não pode prosseguir a menos que o utilizador consinta.
unsupported_response_type O servidor de autorização não suporta o tipo de resposta no pedido. Corrija e reenvia o pedido. Este é um erro de desenvolvimento que normalmente é apanhado durante os testes iniciais.
server_error O servidor encontrou um erro inesperado. Repita o pedido. Estes erros podem resultar de condições temporárias. A aplicação do cliente pode explicar ao utilizador que a sua resposta está atrasada devido a um erro temporário.
temporarily_unavailable O servidor está temporariamente demasiado ocupado para lidar com o pedido. Repita o pedido. A aplicação do cliente pode explicar ao utilizador que a sua resposta está atrasada devido a uma condição temporária.
invalid_resource O recurso alvo é inválido porque ou não existe, a Azure AD não pode encontrá-lo, ou não está corretamente configurado. Isto indica que o recurso, se existe, não foi configurado no inquilino. A aplicação pode solicitar ao utilizador instruções para instalar a aplicação e adicioná-la ao Azure AD.

Validar o símbolo de ID

Receber uma id_token nem sempre é suficiente para autenticar o utilizador; pode também ser necessário validar a assinatura do id_token e verificar as reclamações no token de acordo com os requisitos da sua aplicação. Como todas as plataformas OIDC, a plataforma de identidade da Microsoft utiliza os Tokens Web JSON (JWTs) e a criptografia de chaves públicas para assinar fichas de identificação e verificar se são válidos.

Nem todas as aplicações beneficiam de verificar o token de ID - aplicações nativas e aplicações de página única, por exemplo, raramente beneficiam de validar o token de ID. Alguém com acesso físico ao dispositivo (ou browser) pode contornar a validação de muitas formas - desde a edição do tráfego web até ao dispositivo para fornecer fichas e chaves falsas para simplesmente depurar a aplicação para saltar a lógica de validação. Por outro lado, as aplicações web e as APIs que utilizam um token de ID para autorização devem validar cuidadosamente o símbolo de ID, uma vez que estão a obter acesso aos dados.

Uma vez validada a assinatura do id_token, há algumas reclamações que terá de verificar. Consulte a id_token referência para mais informações, incluindo a validação de fichas e informações importantes sobre a assinatura da chave rollover. Recomendamos a utilização de uma biblioteca para analisar e validar tokens - há pelo menos uma disponível para a maioria dos idiomas e plataformas.

Também pode pretender validar reclamações adicionais dependendo do seu cenário. Algumas validações comuns incluem:

  • Garantindo que o utilizador/organização se inscreveu para a aplicação.
  • Garantindo que o utilizador tem a devida autorização/privilégios
  • Garantindo uma certa força de autenticação ocorreu, como a autenticação de vários fatores.

Uma vez validado o id_token, pode iniciar uma sessão com o utilizador e utilizar as reclamações no id_token para obter informações sobre o utilizador na sua aplicação. Estas informações podem ser utilizadas para exibição, registos, personalização, etc.

Diagrama de protocolo: Aquisição de ficha de acesso

Muitas aplicações web precisam não só de assinar o utilizador, mas também de aceder a um serviço web em nome do utilizador utilizando o OAuth. Este cenário combina OpenID Connect para autenticação do utilizador, ao mesmo tempo que obtém um código de autorização que pode utilizar para obter tokens de acesso se estiver a utilizar o fluxo de código de autorização OAuth.

O fluxo completo de entrada e aquisição do OpenID Connect fica semelhante ao diagrama seguinte. Descrevemos cada passo em detalhe nas próximas secções do artigo.

OpenID Connect protocol: Token acquisition

Obtenha um token de acesso para ligar para o UserInfo

Para adquirir um token para o ponto final do Utilizador OIDC, modifique o pedido de inscrição:

// Line breaks are for legibility only.

GET https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize?
client_id=6731de76-14a6-49ae-97bc-6eba6914391e        // Your registered Application ID
&response_type=id_token%20token                       // this will return both an id_token and an access token
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F       // Your registered redirect URI, URL encoded
&response_mode=form_post                              // 'form_post' or 'fragment'
&scope=openid+profile+email                           // `openid` is required.  `profile` and `email` provide additional information in the UserInfo endpoint the same way they do in an ID token. 
&state=12345                                          // Any value, provided by your app
&nonce=678910                                         // Any value, provided by your app

Também pode utilizar o fluxo de código de autorização, o fluxo de código do dispositivo ou um token de atualização no lugar de response_type=token obter um símbolo para a sua aplicação.

Dica

Clique no seguinte link para executar este pedido. Depois de iniciar seduca, o seu navegador é redirecionado para https://localhost/myapp/, com um token de ID e um token na barra de endereços. Note que este pedido utiliza response_mode=fragment apenas para fins de demonstração - para um webapp recomendamos a utilização form_post para segurança adicional sempre que possível. https://login.microsoftonline.com/common/oauth2/v2.0/authorize...

Resposta simbólica bem sucedida

Uma resposta bem sucedida de usar response_mode=form_post se parece com isto:

POST /myapp/ HTTP/1.1
Host: localhost
Content-Type: application/x-www-form-urlencoded
 access_token=eyJ0eXAiOiJKV1QiLCJub25jZSI6I....
 &token_type=Bearer
 &expires_in=3598
 &scope=email+openid+profile
 &id_token=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI....
 &state=12345

Os parâmetros de resposta significam a mesma coisa, independentemente do fluxo usado para os adquirir.

Parâmetro Description
access_token O token que será usado para chamar o ponto final do UserInfo.
token_type Sempre "Portador"
expires_in Quanto tempo até o sinal de acesso expirar, em segundos.
scope As permissões concedidas no token de acesso. Note que, uma vez que o ponto final do UserInfo está hospedado no MS Graph, pode haver âmbitos de gráficos adicionais listados aqui (por exemplo, user.read) se foram previamente concedidos à app. Isto porque um símbolo de um dado recurso inclui sempre todas as permissões concedidas ao cliente.
id_token O sinal de identificação que a aplicação solicitou. Pode utilizar o token de identificação para verificar a identidade do utilizador e iniciar uma sessão com o utilizador. Você encontrará mais detalhes sobre fichas de identificação e seus conteúdos na id_tokens referência.
state Se um parâmetro de estado for incluído no pedido, o mesmo valor deve aparecer na resposta. A aplicação deve verificar se os valores do Estado no pedido e resposta são idênticos.

Aviso

Não tente validar ou ler fichas para qualquer API que não possua, incluindo as fichas neste exemplo, no seu código. Os tokens para os serviços da Microsoft podem usar um formato especial que não será validado como um JWT, e também podem ser encriptados para utilizadores de consumidores (conta Microsoft). Enquanto ler tokens é uma ferramenta útil de depuragem e aprendizagem, não tome dependências sobre isso no seu código ou assuma detalhes sobre fichas que não são para um API que você controla.

Resposta de erro

As respostas de erro também podem ser enviadas para o URI de redirecionamento para que a aplicação possa manuseá-las adequadamente. Uma resposta de erro é assim:

POST /myapp/ HTTP/1.1
Host: localhost
Content-Type: application/x-www-form-urlencoded

error=access_denied&error_description=the+user+canceled+the+authentication
Parâmetro Description
error Uma cadeia de código de erro que pode utilizar para classificar tipos de erros que ocorrem e para reagir a erros.
error_description Uma mensagem de erro específica que pode ajudá-lo a identificar a causa principal de um erro de autenticação.

Para uma descrição de possíveis códigos de erro e respostas recomendadas do cliente, consulte códigos de erro para obter erros de autorização.

Quando tiver um código de autorização e um token de identificação, pode inscrever o utilizador e obter fichas de acesso em seu nome. Para iniciar sísem o utilizador, tem de validar o token de ID exatamente como descrito. Para obter fichas de acesso, siga os passos descritos na documentação do fluxo de código OAuth.

Chamando o ponto final do UserInfo

Reveja a documentação Do UserInfo para ver como ligar para o ponto final do UserInfo com este token.

Enviar um pedido de sinalização

Quando pretender assinar o utilizador da sua aplicação, não é suficiente para limpar os cookies da sua aplicação ou terminar a sessão do utilizador. Também deve redirecionar o utilizador para a plataforma de identidade da Microsoft para assinar. Se não o fizer, o utilizador reaudiu para a sua aplicação sem introduzir novamente as suas credenciais, pois terá uma sessão de sessão de inscrição única válida com a plataforma de identidade da Microsoft.

Pode redirecionar o utilizador para o end_session_endpoint (que suporta pedidos HTTP GET e POST) listados no documento de metadados OpenID Connect:

GET https://login.microsoftonline.com/common/oauth2/v2.0/logout?
post_logout_redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
Parâmetro Condição Description
post_logout_redirect_uri Recomendado O URL para o qual o utilizador é redirecionado após a assinatura com sucesso. Se o parâmetro não estiver incluído, o utilizador é mostrado uma mensagem genérica que é gerada pela plataforma de identidade da Microsoft. Este URL deve corresponder a um dos URIs de redirecionamento registados para a sua aplicação no portal de registo de aplicações.
logout_hint Opcional Permite que o s-out ocorra sem pedir ao utilizador que selecione uma conta. Para utilizar logout_hint, ative a login_hintreclamação opcional na sua aplicação ao cliente e utilize o valor da login_hint reclamação opcional como logout_hint parâmetro. Não utilize UPNs ou números de telefone como o valor do logout_hint parâmetro.

Fim de sessão único

Quando redireciona o utilizador para o end_session_endpoint, a plataforma de identidade da Microsoft limpa a sessão do utilizador a partir do navegador. No entanto, o utilizador pode ainda ser inscrito noutras aplicações que utilizem as contas da Microsoft para autenticação. Para permitir que essas aplicações assinem o utilizador simultaneamente, a plataforma de identidade da Microsoft envia um pedido HTTP GET ao registo LogoutUrl de todas as aplicações a que o utilizador se encontra atualmente inscrito. As aplicações devem responder a este pedido, limpando qualquer sessão que identifique o utilizador e devolvendo uma 200 resposta. Se pretender apoiar uma única sinse-out na sua aplicação, deve implementar tal LogoutUrl no código da sua aplicação. Pode definir o LogoutUrl portal de registo de aplicações.

Passos seguintes