Over the past couple days, Luke Shepard, David Recordon, and I have been
brainstorming an OAuth profile for standardizing the flow that devices such as
game consoles and entertainment centers use to hook up with services such as
Netflix and iTunes. The basic flow is that a device can gain authorization by
directing the user to visit a URL on their computer and to enter a verification
code copied from the device's screen.
A draft spec is attached to this email. Any thoughts or feedback?
Note: this is one of the many profiles going into the OAuth 2.0 draft that
David is writing (http://daveman692.livejournal.com/349384.html).
-Brent
# This is an initial draft for discussion and is designed to act like devices
which integrate with Netflix and iTunes. It was written initially by Brent
Goldman (br...@facebook.com).
The Device Profile is suitable when the client is a device which does not have
an easy data entry method (e.g., game consoles or entertainment centers), but
where the end user has access to a separate computer with simple data entry
methods (e.g., their home computer, a laptop, or a smartphone).
Prior to making a request using this profile, the client MUST have obtained a
client identifier from the authorization server.
The client constructs an HTTP "POST" request to the device authorization
endpoint and includes the following REQUIRED parameters:
oauth_client_identifier The client identifier.
The client MAY also include the following OPTIONAL parameters, as well as any
additional parameters as defined by the authorization server:
oauth_scope If the authorization server has defined a manner for the client
to request certain capabilities of the access token, this parameter SHOULD be
used to do so.
Since the request results in the transmission of temporary plain text
credentials in the HTTP response, the authorization server MUST require the use
of a transport-layer mechanism such as TLS or SSL (or a secure channel with
equivalent protections).
For example, the client makes the following HTTPS request:
POST /request_token HTTP/1.1
Host: server.example.com
oauth_client_identifier=s6BhdRkqt3
Upon receiving an authorization request by the client, the authorization server
generates a device verification code and a user verification code. These are
included in the HTTP response body using the
"application/x-www-form-urlencoded" content type as defined by
[W3C.REC-html40-19980424] with a 200 status code (OK). The response contains
the following REQUIRED parameters:
oauth_device_code The device verification code.
oauth_user_code The user verification code.
oauth_verification_url The user verification URL on the authorization
server.
The authorization server MAY also include the following parameters, as well as
any additional parameters as defined by the authorization server:
oauth_verification_token_expires_in The lifetime of the two verification
codes in seconds.
oauth_verification_rate_limit The minimum amount of time in seconds that
the client SHOULD wait between polling requests to the device authorization URL.
For example:
HTTP/1.1 200 OK
Content-Type: application/x-www-form-urlencoded
oauth_device_code=74tq5miHKB&oauth_user_code=94248&oauth_verification_url=http%3A%2F%2Fwww%2Eexample%2Ecom%2Fdevice
The client MUST display the user verification URL and the user verification
code to the end user. The client MUST instruct the user to visit the user
verification URL in a web browser, and to enter the user verification token
upon doing so.
The way in which the authorization server handles the authorization request,
including whether it uses a secure channel such as TLS/SSL, is beyond the scope
of this specification. However, the server MUST first verify the identity of
the resource owner. After doing so, the server MUST prompt the end user for the
user verification code.
The authorization server MUST verify that the user verification code is valid
and MAY verify that the client is authorized to use this profile. If the
request is authorized, the authorization server MUST instruct the end user to
follow the instructions on the client device.
The client MAY have an interface element (such as a button) that the end user
interacts with to communicate that the authorization process is complete, and
this button MUST initiate the following request. The client MAY also initiate
the following request by polling at an arbitrary interval in order to create a
more responsive user experience, though the client MUST NOT exceed the
verification rate limit if one is specified. The client MAY both poll and have
an interface element, but MUST NOT have neither.
The client constructs an HTTP "POST" request to the device authorization
endpoint and includes the following REQUIRED parameters:
oauth_client_identifier The client identifier.
oauth_device_verification_code The device verification code.
Since the request results in the transmission of plain text credentials in the
HTTP response, the authorization server MUST require the use of a
transport-layer mechanism such as TLS or SSL (or a secure channel with
equivalent protections).
For example, the client makes the following HTTPS request:
POST /device_authorize HTTP/1.1
Host: server.example.com
oauth_client_identifier=s6BhdRkqt3&oauth_device_verification_code=J2vC42OifV
If the request is authorized, the access token is included in the HTTP response
body using the "application/x-www-form-urlencoded" content type as defined by
[W3C.REC-html40-19980424] with a 200 status code (OK). The response contains
the following REQUIRED parameter:
oauth_access_token The access token.
The authorization server MAY also include the following parameters, as well as
any additional parameters as defined by the authorization server:
oauth_access_token_expires_in The lifetime of the access token in seconds.
For example:
HTTP/1.1 200 OK
Content-Type: application/x-www-form-urlencoded
oauth_access_token=FJQbwq9OD8&oauth_access_token_expires_in=600
If the authorization server is unable to issue an access token to the client,
the HTTP response body uses the "application/x-www-form-urlencoded" content
type as defined by [W3C.REC-html40-19980424] with a 401 status code
(Unauthorized). The response contains the following REQUIRED parameter:
oauth_error_reason Value must be one of "authorization_declined",
"authorization_pending", "slow_down", or "verification_code_expired" (case
sensitive).
For example:
HTTP/1.1 401 Authorization Required
WWW-Authenticate: OAuth realm="https://server.example.com/";
oauth_error_reason=authorization_pending_______________________________________________
OAuth mailing list
OAuth@ietf.org
https://www.ietf.org/mailman/listinfo/oauth
