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 oferece suporte à concessão de autorização de 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 faz login, o dispositivo é capaz de obter tokens de acesso e atualizar tokens conforme necessário.

Este artigo descreve como programar diretamente contra o protocolo na sua aplicação. Quando possível, recomendamos que utilize as Bibliotecas de Autenticação da Microsoft (MSAL) suportadas para adquirir tokens e chamar as APIs Web seguras. Você pode consultar aplicativos de exemplo que usam MSAL para exemplos.

Diagrama de protocolo

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

Device code flow

Pedido de autorização do dispositivo

O cliente deve primeiro verificar com o servidor de autenticação se há um dispositivo e código de usuário usado 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 que precisa adquirir do usuário.

A partir do momento em que o pedido é enviado, o utilizador tem 15 minutos para iniciar sessão. Este é 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	Description
`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`	Necessário	A ID do Aplicativo (cliente) que o Centro de administração do Microsoft Entra – Registros de aplicativo experiência atribuída ao seu aplicativo.
`scope`	Necessário	Uma lista separada por espaços de escopos para os quais você deseja que o usuário consinta.

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 faça login.

Parâmetro	Formato	Description
`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 pequena cadeia de caracteres mostrada ao usuário usada para identificar a sessão em um dispositivo secundário.
`verification_uri`	URI	O URI ao qual o usuário deve ir com o `user_code` para entrar.
`expires_in`	número inteiro	O número de segundos antes do `device_code` e `user_code` expirar.
`interval`	número inteiro	O número de segundos que o cliente deve aguardar entre as solicitações de sondagem.
`message`	String	Uma string 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.

Nota

O verification_uri_complete campo de resposta não está incluído nem é suportado neste 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_uri, os valores são exibidos e o usuário é direcionado para entrar através de seu navegador móvel ou PC.

Se o usuário se autenticar com uma conta pessoal, usando /common ou /consumers, ele será solicitado a entrar 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 escolares usadas para autenticar.

Enquanto o usuário está autenticando no verification_uri, o cliente deve sondar 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	Necessário	Description
`tenant`	Obrigatório	O mesmo alias de locatário ou locatário usado na solicitação inicial.
`grant_type`	Necessário	Deve ser `urn:ietf:params:oauth:grant-type:device_code`
`client_id`	Necessário	Deve corresponder ao `client_id` usado na solicitação inicial.
`device_code`	Necessá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 servidos ao cliente devem ser esperados antes da conclusão da autenticação do usuário.

Erro	Description	Ação do Cliente
`authorization_pending`	O usuário não terminou a autenticação, mas não cancelou o fluxo.	Repita o pedido 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` endpoint não foi reconhecido.	Verifique se o cliente está enviando o correto `device_code` na solicitação.
`expired_token`	O valor de foi excedido `expires_in` e a autenticação não é mais possível com `device_code`o .	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	Description
`token_type`	String	Sempre `Bearer`.
`scope`	Strings separadas por espaço	Se um token de acesso foi retornado, isso lista os escopos nos quais o token de acesso é válido.
`expires_in`	número inteiro	Número de segundos para os quais o token de acesso incluído é válido.
`access_token`	Corda opaca	Emitido para os escopos que foram solicitados .
`id_token`	JWT	Emitido se o parâmetro original `scope` incluísse o `openid` escopo.
`refresh_token`	Corda opaca	Emitido se o parâmetro original `scope` incluísse `offline_access`.

Você pode usar o token de atualização para adquirir novos tokens de acesso e tokens de atualização usando o mesmo fluxo documentado na documentação de fluxo de 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. Os tokens para 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 consumidores (conta da Microsoft). Embora a leitura de tokens seja uma ferramenta útil de depuração e aprendizagem, não dependa disso em seu código ou assuma especificidades sobre tokens que não são para uma API que você controla.

Partilhar via