Plataforma de identidade da Microsoft e o fluxo de concessão de autorização de dispositivo OAuth 2.0

  • Artigo

A Plataforma de Identidade da Microsoft dá suporte à concessão de autorização de dispositivo, que permite que os usuários entrem com as próprias contas em dispositivos com restrição de entrada, como uma smart TV, um dispositivo IoT ou uma impressora. Para habilitar esse fluxo, o dispositivo exige que o usuário visite uma página da Web em um navegador em outro dispositivo para entrar. Depois que o usuário entra, o dispositivo é capaz de obter tokens de acesso e atualizar tokens conforme necessário.

Este artigo descreve como programar diretamente no protocolo do seu aplicativo. Quando possível, recomendamos que você use as MSAL (bibliotecas de autenticação da Microsoft) com suporte para adquirir tokens e chamar APIs Web seguras. Veja também os aplicativos de exemplo que usam a MSAL para obter exemplos.

Diagrama de protocolo

Todo o fluxo de código do dispositivo é mostrado no diagrama a seguir. Cada etapa é explicada no decorrer deste artigo.

Device code flow

Solicitação de autorização do dispositivo

Primeiro, o cliente precisa verificar com o servidor de autenticação se há um código do dispositivo e do usuário usado para iniciar a autenticação. O cliente coleta essa solicitação do ponto de extremidade /devicecode. Nessa solicitação, o cliente também deve incluir as permissões que precisa adquirir do usuário.

A partir do momento em que a solicitação é enviada, o usuário tem 15 minutos para entrar. Esse é o valor padrão de expires_in. A solicitação só deverá ser feita quando o usuário indicar que está pronto para entrar.

// Line breaks are for legibility only.

POST https://login.microsoftonline.com/{tenant}/oauth2/v2.0/devicecode
Content-Type: application/x-www-form-urlencoded

client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&scope=user.read%20openid%20profile
Parâmetro Condição Descrição
tenant Obrigatório Pode ser /common, /consumers ou /organizations. Também pode ser o locatário de diretório do qual você deseja solicitar permissão no formato GUID ou de nome amigável.
client_id Obrigatório A ID do aplicativo (cliente) que a experiência centro de administração do Microsoft Entra - Registros de aplicativo atribui ao seu aplicativo.
scope Obrigatório Uma lista separada por espaços de escopos para os quais você deseja o consentimento do usuário.

Resposta de autorização do dispositivo

Uma resposta bem-sucedida é um objeto JSON que contém as informações necessárias para permitir que o usuário entre.

Parâmetro Formatar Descrição
device_code String Uma cadeia de caracteres longa usada para verificar a sessão entre o cliente e o servidor de autorização. O cliente usa esse parâmetro para solicitar o token de acesso do servidor de autorização.
user_code String Uma cadeia de caracteres curta mostrada ao usuário usada para identificar a sessão em um dispositivo secundário.
verification_uri URI O URI que o usuário deve acessar com o user_code para entrar.
expires_in INT O número de segundos antes que o device_code e o user_code expirem.
interval INT O número de segundos que o cliente deve aguardar entre solicitações de sondagem.
message String Uma cadeia de caracteres legível por humanos com instruções para o usuário. Ela pode ser localizada incluindo um parâmetro de consulta na solicitação do formulário ?mkt=xx-XX, preenchendo o código de cultura do idioma apropriado.

Observação

O campo de resposta verification_uri_complete não está incluído ou não tem suporte no momento. Mencionamos isso porque, se você ler o padrão, verá que verification_uri_complete está listado como uma parte opcional do padrão de fluxo de código do dispositivo.

Como autenticar o usuário

Depois que o cliente recebe user_code e verification_uri, os valores são exibidos e o usuário é direcionado para iniciar sessão via navegador móvel ou PC.

Se o usuário se autenticar com uma conta pessoal usando /common ou /consumers, receberá uma solicitação para entrar novamente a fim de transferir o estado de autenticação para o dispositivo. Isso ocorre porque o dispositivo não consegue acessar os cookies do usuário. Eles também serão solicitados a consentir com as permissões solicitadas pelo cliente. No entanto, isso não se aplica a contas corporativas ou de estudante usadas para autenticação.

Enquanto o usuário está se autenticando no verification_uri, o cliente deverá estar sondando o ponto de extremidade /token para o token solicitado usando o device_code.

POST https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded

grant_type=urn:ietf:params:oauth:grant-type:device_code&client_id=535fb089-9ff3-47b6-9bfb-4f1264799865&device_code=GMMhmHCXhWEzkobqIHGG_EnNYYsAkukHspeYUk9E8...
Parâmetro Obrigatório Descrição
tenant Obrigatório O mesmo locatário ou alias de locatário usado na solicitação inicial.
grant_type Obrigatório Precisa ser urn:ietf:params:oauth:grant-type:device_code
client_id Obrigatório Precisa corresponder à client_id usada na solicitação inicial.
device_code Obrigatório O device_code retornado na solicitação de autorização de dispositivo.

Erros esperados

O fluxo de código do dispositivo é um protocolo de sondagem, portanto, espera-se que o cliente receba alguns erros antes da conclusão da autenticação do usuário.

Erro Descrição Ação do Cliente
authorization_pending O usuário não terminou a autenticação, mas não cancelou o fluxo. Repita a solicitação depois de pelo menos interval segundos.
authorization_declined O usuário final negou a solicitação de autorização. Interrompa a sondagem e reverta para um estado não autenticado.
bad_verification_code O device_code enviado ao ponto de extremidade /token não foi reconhecido. Verifique se o cliente está enviando o device_code correto na solicitação.
expired_token O valor de expires_in foi excedido e a autenticação não é mais possível com device_code. Interrompa a sondagem e reverta para um estado não autenticado.

Resposta de autenticação bem-sucedida

Uma resposta de token bem-sucedida tem a seguinte aparência:

{
    "token_type": "Bearer",
    "scope": "User.Read profile openid email",
    "expires_in": 3599,
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...",
    "refresh_token": "AwABAAAAvPM1KaPlrEqdFSBzjqfTGAMxZGUTdM0t4B4...",
    "id_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJub25lIn0.eyJhdWQiOiIyZDRkMTFhMi1mODE0LTQ2YTctOD..."
}
Parâmetro Formatar Descrição
token_type String Sempre Bearer.
scope Cadeia de caracteres separadas por espaço Se um token de acesso for retornado, isso listará os escopos em que o token de acesso é válido.
expires_in INT Número de segundos para o qual o token de acesso incluído é válido.
access_token Cadeia de caracteres opaca Emitido para os escopos que foram solicitados.
id_token JWT Emitido quando o parâmetro original scope inclui o escopo openid.
refresh_token Cadeia de caracteres opaca Emitido quando o parâmetro original scope inclui offline_access.

Você pode usar o token de atualização para adquirir novos tokens de acesso e de atualização usando o mesmo fluxo incluído na documentação do fluxo de código OAuth.

Aviso

Não tente validar nem ler tokens de APIs que não sejam suas em seu código, incluindo os tokens deste exemplo. Os tokens de serviços da Microsoft podem usar um formato especial que não será validado como um JWT e também podem ser criptografados para usuários do consumidor (conta Microsoft). Embora a leitura de tokens seja uma ferramenta útil de depuração e aprendizagem, não assuma dependências disso em seu código ou assuma informações específicas sobre tokens que não são de uma API que você controla.