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

2025-04-02

A plataforma de identidade da Microsoft dá suporte à concessão de autorização do dispositivo, que permite que os usuários entrem em dispositivos com restrição de entrada, como uma smart TV, um dispositivo IoT ou uma impressora. Para habilitar esse fluxo, o dispositivo faz com que o usuário visite uma página da Web em um navegador em outro dispositivo para entrar. Depois que o usuário entrar, o dispositivo poderá obter tokens de acesso e atualizar tokens conforme necessário.

Este artigo descreve como programar diretamente contra o protocolo em seu aplicativo. Quando possível, recomendamos usar as MSAL (bibliotecas de autenticação da Microsoft) com suporte para adquirir tokens e chamar APIs Web seguras. Você pode consultar aplicativos de exemplo que usam MSAL para obter exemplos.

Diagrama de protocolo

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

Fluxo de código do dispositivo

Solicitação de autorização do dispositivo

O cliente deve primeiro verificar com o servidor de autenticação um dispositivo e o código do usuário usados para iniciar a autenticação. O cliente coleta essa solicitação do /devicecode ponto de extremidade. Na solicitação, o cliente também deve incluir as permissões necessárias para 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 para expires_in. A solicitação só deve 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`. Ele também pode ser o locatário do diretório do qual você deseja solicitar permissão no GUID ou no formato 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	Formato	Descrição
`device_code`	fio	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`	fio	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 para o qual o usuário deve ir 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`	fio	Uma cadeia de caracteres legível por humanos com instruções para o usuário. Isso pode ser localizado incluindo um parâmetro de consulta na solicitação do formulário `?mkt=xx-XX`, preenchendo o código de cultura de idioma apropriado.

Observação

O verification_uri_complete campo de resposta não está incluído ou 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.

Autenticando o usuário

Depois que o cliente recebe user_code e verification_urios valores são exibidos e o usuário é direcionado para entrar por meio de seu navegador móvel ou pc.

Se o usuário se autenticar com uma conta pessoal, usando /common ou /consumers, será solicitado que ele entre novamente para transferir o estado de autenticação para o dispositivo. Isso ocorre porque o dispositivo não consegue acessar os cookies do usuário. Eles sã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á autenticando no verification_uri, o cliente deve estar sondando o /token ponto de extremidade 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 alias de locatário ou 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	Deve corresponder ao `client_id` usado na solicitação inicial.
`device_code`	Obrigatório	O `device_code` retornado na solicitação de autorização do dispositivo.

Erros esperados

O fluxo de código do dispositivo é um protocolo de sondagem, portanto, os erros atendidos ao cliente devem ser esperados antes da conclusão da autenticação do usuário.

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

Resposta de autenticação bem-sucedida

Uma resposta de token bem-sucedida se parece com:

{
    "token_type": "Bearer",
    "scope": "User.Read profile openid email",
    "expires_in": 3599,
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...",
    "refresh_token": "AwABAAAAvPM1KaPlrEqdFSBzjqfTGAMxZGUTdM0t4B4...",
    "id_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJub25lIn0.eyJhdWQiOiIyZDRkMTFhMi1mODE0LTQ2YTctOD..."
}

Parâmetro	Formato	Descrição
`token_type`	fio	Sempre `Bearer`.
`scope`	Cadeias de caracteres separadas por espaço	Se um token de acesso foi retornado, ele lista os escopos para os quais o token de acesso é válido.
`expires_in`	int	Número de segundos para os quais 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 `scope` original inclui o escopo `openid`.
`refresh_token`	Cadeia de caracteres opaca	Emitido quando o parâmetro `scope` original inclui `offline_access`.

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

Aviso

Não tente validar ou ler tokens para qualquer API que você não possua, incluindo os tokens neste exemplo, em seu código. Tokens para serviços da Microsoft podem usar um formato especial que não será validado como um JWT e também pode ser criptografado para usuários consumidores (conta da Microsoft). Embora a leitura de tokens seja uma ferramenta útil de depuração e aprendizado, não use dependências sobre isso em seu código ou assuma detalhes sobre tokens que não são para uma API que você controla.

Compartilhar via