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

Artigo
04/08/2024

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=00001111-aaaa-2222-bbbb-3333cccc4444&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.

Compartilhar via