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 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.
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=535fb089-9ff3-47b6-9bfb-4f1264799865
&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=535fb089-9ff3-47b6-9bfb-4f1264799865&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_codeo . |
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.