An additional profile for obtaining an Access Token
Dick Hardt
page into the Client, but also allows the Server to put the code into
the title of the resulting page so that crafty Rich Apps can access
it. Somewhat of a hack, but better to describe it in a standard way
then have each Server have their own hack. Thoughts?
-- Dick
5.5 Rich App Profile
This profile is suitable where the Client is an application the User
has installed on their computer and there is a browser available for
the Client to launch. This profile enables a Client to act on behalf
of the User regardless of how the User authenticates to the Server and
without access to the User’s credentials.
5.5.1 Provisioning
Prior to initiating this protocol profile, the Client MAY be required
to register the Client Display Name with the Server.
5.5.2 Client Directs the User to the Server
The Client initiates an authorization request by opening the User’s
browser with the Server's User Authorization URL, and including the
following parameters:
wrap_display_name:
REQUIRED. The Client Display Name
wrap_scope
OPTIONAL. The Server MAY define authorization scope values for the
Client to include
Additional parameters:
Any additional parameters, as defined by the Server.
5.5.3 Server Confirms Delegation Request with User
Upon receiving an authorization request from the Client by way of the
User’s browser, the Server authenticates the user, presents the User
with the Protected Resource access that will be granted to the Client,
and prompts the User to confirm the request.
If the User approves the request, the Server generates a single use
Verification Code and instructs the user to enter it into the Client.
The Server may enable the Verification Code to be valid only long
enough for the user to enter the value into the Client.
When displaying the user the resulting page after successful
delegation by the User, the Server MAY append the Verification Code to
the title of the HTML page so that Clients that can see the programs
running on the User’s machine can obtain the Verification Code without
having to have the user enter the Verification Code into the Client.
The Client can parse the title looking for “code=” and then the rest
of the title is the Verification Code.
Eg. For example.com where Verification Code = WF34F7HG, the Server
would set the title of the page to something like:
Example.com delegation successful, code=WF34F7HG
If the User denies access, the Server MAY append “code=denied” to the
title of the HTML page so that the Client can detect that the User has
denied access.
5.5.4 Client Requests Delegation Token
The Client obtains the User’s username and password from the user.
The Client makes an HTTPS request to the Server’s Delegation Token URL
using POST. The request contains the following parameters:
wrap_display_name:
REQUIRED. The Client Display Name used in 5.5.2
wrap_verification_code:
REQUIRED. The Verification Code received from the Server
Additional parameters:
Any additional parameters, as defined by the Server.
5.5.5 Successful Delegation Token Response from Server
The Server checks the Verification Code was previously issued to the
same Client Display Name, has not expired and has not been used. If
these conditions are met, the Server marks the Verification Code as
being used and returns:
HTTP 200 OK
with the Delegation Token in the response body. The response body
contains the following parameters:
wrap_delegation_token
REQUIRED. The Delegation Token
Additional parameters:
Any additional parameters, as defined by the Server.
The Client securely stores the Delegation Token for later use.
5.5.6 Unsuccessful Delegation Token Response from Server
If the verification fails, the Server MUST respond with:
HTTP 401 Unauthorized
and the HTTP header:
WWW-Authenticate: WRAP
HTTP 400 Bad Request
The Client needs to obtain a new Verification Code per 5.5.2.
5.5.7 Client Refreshes Access Token
Servers are RECOMMENDED to issue Access Tokens that expire and require
Clients to refresh them. Upon receiving the HTTP 401 response when
accessing protected resources, the Client should request a new Access
Token by repeating 5.5.4.