Saltar para o conteúdo
Usher IdentityUsher Identity
Documentação · TVs e ferramentas de linha de comandos

TVs, consolas e ferramentas de linha de comandos

Uma TV não consegue mostrar facilmente uma página de início de sessão, e uma ferramenta de linha de comandos não deve pedir uma palavra-passe. Com o fluxo de dispositivo, o dispositivo mostra um código curto, e a pessoa introduz-o no Lobby do seu ambiente, no telemóvel ou no computador, onde já tem sessão iniciada.

Registe a app

Na Usher Console, abra o ambiente e escolha Aplicações → Nova aplicação → TV ou linha de comandos. A app recebe um ID de cliente e nenhum segredo: um dispositivo não consegue guardá-lo.

O fluxo

Terminal
# 1. the device asks for a code
curl -s -X POST https://acme.usherid.com/api/auth/device/code \
  -d client_id=YOUR_CLIENT_ID -d scope='openid email offline_access'
# → { "device_code": "…", "user_code": "6L95PBQQ",
#     "verification_uri": "https://acme.usherid.com/device",
#     "verification_uri_complete": "https://acme.usherid.com/device?user_code=6L95PBQQ",
#     "expires_in": 600, "interval": 5 }

# 2. it shows the code (and a QR code of verification_uri_complete), then polls
curl -s -X POST https://acme.usherid.com/api/auth/oauth2/token \
  -d grant_type=urn:ietf:params:oauth:grant-type:device_code \
  -d device_code=… -d client_id=YOUR_CLIENT_ID
# → { "error": "authorization_pending" } until the person allows it,
#   then { "access_token": "…", "id_token": "…", "refresh_token": "…" }
  • Consulte com moderação. Espere interval segundos entre consultas. Consultar mais depressa tem como resposta slow_down.
  • Pare quando lhe disserem. access_denied significa que a pessoa recusou; expired_token significa que passaram dez minutos. Peça um novo código.
  • Mostre também o endereço. Nem toda a gente consegue ler um código QR: mostre o verification_uri e o código, espaçado como 6L95-PBQQ.

Em /device, o Lobby mostra à pessoa que app está a pedir e o quê. Diz-lhe para continuar apenas se foi ela que iniciou o processo e se o seu dispositivo mostra o mesmo código.

Associe os tokens ao dispositivo (DPoP)

Um token copiado de um dispositivo continua a ser um token. Com DPoP (RFC 9449), o dispositivo guarda uma chave privada e envia uma nova prova assinada em cada pedido. Um token associado a essa chave é inútil sem ela.

  • Peça tokens associados: envie um cabeçalho DPoP nos seus pedidos de token, e o Usher associa o que emite à sua chave (o token_type é DPoP).
  • Exija-os: ative Exigir DPoP quando criar a app. A partir daí, o Usher não lhe emite nenhum token sem uma prova.
  • Use-os com Authorization: DPoP <token>, mais uma prova para esse pedido.
  • Bibliotecas: a maioria das bibliotecas OAuth com suporte para DPoP faz tudo isto por si (a opção DPoP do openid-client, por exemplo).