Device Authorization Grant

​

Turn it on

AuthorizationServer: &theauth.AuthorizationServerConfig{
    Issuer:    "https://auth.example.com",
    Resources: []theauth.ProtectedResource{{Identifier: "https://api.example.com", Scopes: []string{"deploy"}}},
    DeviceAuthorization: &theauth.DeviceAuthorizationConfig{}, // every field is optional
}

​

What happens on the wire

1. The device calls POST /oauth/device_authorization with client_id, scope and resource. You can leave resource out when exactly one resource is configured. The response holds device_code, user_code, verification_uri, verification_uri_complete, expires_in and interval.
2. The device shows the code and URL, then polls POST /oauth/token every interval seconds with grant_type=urn:ietf:params:oauth:grant-type:device_code, the device_code and the client_id.
3. The user opens verification_uri_complete, signs in if needed, checks the client name and scopes, and presses Allow or Deny.
4. Each poll returns one of the RFC 8628 answers: authorization_pending, slow_down (the interval grows by 5 seconds), access_denied, expired_token, and finally tokens. A device_code redeems once. DPoP works on the token request like any other grant.

​

The verification page

GET  /oauth/device?user_code=BCDF-GHJK
     -> {"client_name": "...", "scope": "...", "expires_at": "..."}
POST /oauth/device {"user_code": "BCDF-GHJK", "action": "approve" | "deny" | "lookup"}
     -> {"status": "approved"}

​

Why the codes are hard to guess

• device_code carries 256 random bits. user_code is 8 letters drawn from a 20 letter alphabet with no vowels (about 34 bits), and it is single use.
• Both are stored only as HMAC-SHA256 under a key derived from EncryptionKey. A database leak does not reveal live codes, and the short user code cannot be brute-forced offline.
• Lookups on the verification page are limited per signed-in user (per client IP when nobody is signed in). MaxVerifyAttempts defaults to 10 per VerifyAttemptWindow of 15 minutes. A wrong, expired or already decided code all return the same error, so the page does not tell an attacker which case they hit.
• The defaults are a 10 minute lifetime (ExpiresIn) and a 5 second interval (Interval). UserCodeLength and UserCodeAlphabet can change, but an alphabet under 16 symbols or a length under 6 is rejected.

​

Operating it