Fluxo Device Code

Fluxo de Código de Dispositivo

O fluxo de código de dispositivo (device code) é um fluxo de autenticação OAuth 2.0 projetado para dispositivos com capacidades de entrada limitadas ou sem navegador web integrado. Este fluxo:

• Permite autenticação em dispositivos IoT, CLI, terminais
• Redireciona o utilizador para outro dispositivo para autenticação
• Fornece uma experiência consistente com as políticas de autenticação do Entra ID
• Suporta MFA, SSO e outras políticas de acesso condicional

Funcionamento

1. O aplicativo solicita um código de dispositivo ao Entra ID
2. O utilizador é instruído a visitar um URL em outro dispositivo e inserir o código
3. O aplicativo original faz polling para verificar se o utilizador completou a autenticação
4. Após autenticação bem-sucedida, o aplicativo recebe tokens de acesso e atualização

Implementação com PowerShell

Exemplo de implementação do fluxo de código de dispositivo em PowerShell:

# Parâmetros da aplicação
$tenantId = "contoso.onmicrosoft.com"
$clientId = "00000000-0000-0000-0000-000000000000"
$scope = "https://graph.microsoft.com/User.Read"

# Solicitar código de dispositivo
$deviceCodeUrl = "https://login.microsoftonline.com/$tenantId/oauth2/v2.0/devicecode"
$deviceCodeBody = @{
    client_id = $clientId
    scope = $scope
}

$deviceCodeResponse = Invoke-RestMethod -Uri $deviceCodeUrl -Method Post -Body $deviceCodeBody

# Exibir instruções para o utilizador
Write-Host "Para fazer login, visite: $($deviceCodeResponse.verification_uri)"
Write-Host "E insira o código: $($deviceCodeResponse.user_code)"

# Iniciar polling para obter o token
$tokenUrl = "https://login.microsoftonline.com/$tenantId/oauth2/v2.0/token"
$tokenBody = @{
    grant_type = "urn:ietf:params:oauth:grant-type:device_code"
    client_id = $clientId
    device_code = $deviceCodeResponse.device_code
}

# Intervalo de polling (em segundos)
$interval = $deviceCodeResponse.interval
$expiresIn = $deviceCodeResponse.expires_in
$startTime = Get-Date

$accessToken = $null

while (-not $accessToken) {
    # Verificar se o código expirou
    $elapsedSeconds = ((Get-Date) - $startTime).TotalSeconds
    if ($elapsedSeconds -ge $expiresIn) {
        Write-Error "O código de dispositivo expirou. Reinicie o processo."
        break
    }
    
    try {
        # Tentar obter o token
        $tokenResponse = Invoke-RestMethod -Uri $tokenUrl -Method Post -Body $tokenBody -ErrorAction Stop
        $accessToken = $tokenResponse.access_token
        Write-Host "Autenticação bem-sucedida!"
    }
    catch {
        $error = $_.ErrorDetails.Message | ConvertFrom-Json
        
        # Se ainda está aguardando o utilizador, espere e tente novamente
        if ($error.error -eq "authorization_pending") {
            Write-Host "Aguardando o utilizador completar a autenticação..."
            Start-Sleep -Seconds $interval
        }
        # Outros erros
        else {
            Write-Error "Erro: $($error.error) - $($error.error_description)"
            break
        }
    }
}

# Usar o token para acessar o Microsoft Graph
if ($accessToken) {
    $headers = @{
        "Authorization" = "Bearer $accessToken"
    }
    
    $graphResponse = Invoke-RestMethod -Uri "https://graph.microsoft.com/v1.0/me" -Headers $headers
    Write-Host "Olá, $($graphResponse.displayName)!"
}

Casos de Uso

• Aplicativos de linha de comando (CLI)
• Dispositivos IoT com capacidade de exibição limitada
• Aplicativos em smart TVs, consoles de jogos
• Dispositivos sem navegador completo ou com entrada limitada
• Scripts e automações que requerem autenticação interativa

Considerações de Segurança

• O código de dispositivo tem um tempo de expiração curto (normalmente 15 minutos)
• O fluxo deve respeitar as políticas de acesso condicional configuradas
• A experiência multi-fator é preservada
• Evite armazenar o código de dispositivo em logs ou arquivos não criptografados
• Implemente tratamento adequado de erros, especialmente para códigos expirados

Melhores Práticas

• Solicite apenas os escopos (permissões) necessários
• Forneça instruções claras ao usuário sobre como completar a autenticação
• Implemente uma interface amigável para mostrar o progresso do polling
• Armazene o token de atualização de forma segura para minimizar novas autenticações