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

A plataforma de identidade da Microsoft dá suporte à concessão de autorização de dispositivo, que permite que os usuários entrem com suas contas em dispositivos com restrição de entrada, como uma smart TV, um dispositivo IoT ou uma impressora. Para habilitar esse fluxo, o dispositivo faz o usuário acessar uma página da Web em seu 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. Confira também os aplicativos de exemplo que usam MSAL.

Dica

Tente executar a solicitação no Postman
Tente executar esta solicitação e muito mais no Postman, mas não se esqueça de substituir os tokens e as IDs!

Diagrama do protocolo

Todo o fluxo de código do dispositivo é semelhante ao diagrama a seguir. Descrevemos cada uma das etapas mais adiante neste artigo.

Fluxo de código do dispositivo

Solicitação de autorização do dispositivo

O cliente deve primeiro verificar o servidor de autenticação para obter um código de usuário e de dispositivo 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 essa solicitação é enviada, o usuário tem apenas 15 minutos para entrar (o valor normal para expires_in), portanto, somente faça essa solicitação 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=6731de76-14a6-49ae-97bc-6eba6914391e
&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 Portal do Microsoft Azure - 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 será 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 para o usuário que é 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

Após o recebimento de user_code e verification_uri, o cliente exibirá isso ao usuário, instruindo-o a entrar com sua respectiva conta usando o navegador do telefone celular ou do computador.

Se o usuário se autenticar com uma conta pessoal (em /common ou /consumers), ele será solicitado a entrar novamente para transferir o estado de autenticação ao dispositivo. Ele também será solicitado a fornecer consentimento, para garantir que esteja ciente das permissões que estão sendo concedidas. 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=6731de76-14a6-49ae-97bc-6eba6914391e
&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, o cliente deverá esperar receber erros antes que o usuário termine a autenticação.

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 Pelo menos expires_in segundos foram decorridos e a autenticação não é mais possível com este 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 será assim:

{
    "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 "Portador".
scope Cadeia de caracteres separadas por espaço Se um token de acesso for retornado, isso listará os escopos para os quais o token de acesso é válido.
expires_in INT Número de segundos antes que o token de acesso incluído seja 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.