Updated WRAP spec 0.9.6.0

[Dick Hardt]

Complete spec except for references and security considerations.

 

Changes since last document are grammatical, and the examples were updated to reflect spec changes.

 

Documents have been uploaded to Google WRAP Group.

 

-Dick

[Brian Eaton]

On Thu, Oct 22, 2009 at 3:18 PM, Dick Hardt <Dick....@microsoft.com> wrote:
> Documents have been uploaded to Google WRAP Group.

I'll see your PDF and raise you... another PDF.

Cheers,
Brian

[Brian Eaton]

Ah, one other comments that I'd missed in my earlier review... The
CAPTCHA flow you propose earlier looks impossible to implement, the
client needs to echo back something to the server after answering the
captcha so that they server knows what captcha got answered. =)

Here's how the flow would look:

Initial request:
client_id=xyz&username=bob&password=secret

Initial response:
captcha_url=http://www.example.com/captcha12345

Next request:
client_id=xyz&username=bob&password=secret&answer=teapot

The problem is that the server processing that last request doesn't
necessarily know which captcha challenge the client received.
Simplest way to fix it I can see is to have the last request look like
this:
client_id=xyz&username=bob&password=secret&answer=teapot&captcha_url=http://www.example.com/captcha12345

Cheers,
Brian

[Dick Hardt]

Doh, my bad, thanks for catching ...

[Dick Hardt]

Brian wins. Brian's PDF copy with comments inserted. WRAP spec 0.9.7.0 in next email

WRAP 0.9.6.0 comments

Section 1.1

"Since the Access Token provides the Client authorization to the Protected Resource for

the life of the Access Token, the Authorization Server should issue Access Tokens that

expire within an appropriate time."

I think this will be true in the general case, but it's not actually required by the protocol.

(As I mentioned earlier, the fact that ATs have baked in expiration makes it much easier

to implement revocation.) Also, I think delegation tokens are a big enough deal that

they merit a mention in this section. Lastly, it's a bit weird (though I can see why you

did it this way) to talk about protected resource access prior to permission granting.

Maybe we could add a section between 1 and 1.1? Something like this?

Initial Authorization

WRAP protocol flows typically begin with a client obtaining permission to access a

resource. Different credentials and profiles can be used to obtain this permission, but

once authorized a client is provided a Delegation Token and Access Tokens.

Reworked 1.1 to include some of the explanations you have. Thanks.

Delegation Tokens represent long-lived permission to access a resource. These tokens

are extremely sensitive, and are only sent to the Authorization Server over HTTPS.

Since Delegation Tokens only appear in User Delegation Flow, added copy about them there.

Section 1.2

Maybe instead of "Two Legged Flow", call this "Autonomous Client Flow"

Section 1.3

Maybe instead of "Three Legged Flow", call this "User Delegation Flow".

Great suggestions. Done.

Maybe change "User delegating to a Client to act on behalf of a User" to read "User

delegating to a client to act on behalf of that User." I dunno. The existing text read

funny, but I'm having trouble rephrasing it so it sounds better.

Rich App Profile

"the Authorization presents the Verification Code to the User" doesn't quite parse.

Should be "The Authorization Server presents the Verification Code to the User."

the list of methods to obtain the verification code might be easier to read as bullet

points.

Done

I think the Rich App Profile needs a bit of a shakedown, I'll put that in my comments on

5.5.

Definitions

"Client" should be listed before "Client Identifier"

Section

Fixed a number of similar errors. Thanks.

4.1 "Access Token"

Way too many implementation constraints here. How about this instead?

The exact format of the Access Token is opaque to Clients and is out of scope of this

specification. However, Protected Resources MUST be able to verify that the Access

Token was issued by a trusted Authorization Server and is still valid. Access Tokens

SHOULD periodically expire. The expiry time of Access Tokens is determined as an

appropriate balance between excessive resource utilization if too short and unauthorized

access if too long.

Replaced my paragraph with your paragraph. Thanks.

Section 4.4 "Client Calls Protected Resource Using Post Parameter"

This whole section is a bad idea. It's really difficult (err, impossible?) to implement for

non-form-encoded post bodies, and it just causes confusion and bad code when people

try to implement it. OAuth allowed this, and no one ever actually deployed it, and

that's a good thing.

Others like it being in there.

Can we replace section 4.4 with something like this?

Accessing Protected Resources Using Other Mechanisms

The Protected Resource MAY allow the Client to present the Access Token using any

scheme agreed on by the Client and Protected Resource. Use of the Authorization

header is RECOMMENDED, since HTTP implementations are aware that Authorization

headers have special security properties and may require special treatment in caches

and logs.

Protected Resources SHOULD take precautions to insure that Access Tokens are not

inadvertently logged or captured.

Good additional language. Added at top of Section 4

General comment on error handling

I think we are misusing the HTTP 400 error code. In particular, I've seen servers return

HTTP 400 for non-authorization related problems. It would be bad if a malformed URL

was misinterpreted as an authorization problem; it can make debugging really hard.

(why is this app asking me to login again? I know that password was right!)

How about this as a general strategy for error handling?

1) Authorization Server errors are returned in the body of a 401 HTTP response.

I think we need to define an encoding mechanism for the body. The spec says things

like "response body has parameters X and Y", but doesn't mention how they are

encoded. I assume we want form-encoding?

2) Protected Resource returns 401 HTTP Response with error detail in WWWAuthenticate

header.

Again, we need an encoding mechanism. name="url-encoded-value" is probably

good. (Multiple name-value pairs separated by whitespace.)

3) For both of those cases, we define the following (optional) error parameters

wrap_error_reason: machine readable error codes

wrap_error_explanation: developer readable error explanations

I'd like to get feedback from others before making that change. 400 responses only happen in some profiles.

General comment on POSTS to the authorization server

We should specify that these are form-encoded. (Oh, never mind. Found it in section

6.5. Maybe a pointer?)

Pointer added

Section 5.4.5 Client Requests Delegation Token

No mentioned here of server validating the verification code/callback. I think the

validation rules from section 5.4.7 should be moved here instead. How about

The Authorization Server verifies that the Delegation Token request is valid as follows:

- the client secret MUST match the client id

- the client id MUST match the client id from the authorization redirect

- the client verification code MUST match the client id from the authorization redirect

- the callback MUST match the callback URL from the authorization redirect

- the verification code MUST not have expired

The Authorization Server MAY also require that a verification code is not reused.

Good catch. Added.

General Comment: the phrase "Authorization Servers are RECOMMENDED to" is a little

awkward, should probably say "Authorization Servers SHOULD" everywhere.

Changed

Section 5.5 Rich App Profile

We need wrap_client_state here (iphone apps with callback URLs are just as vulnerable

session fixation as web apps).

At which point this profile is identical to the web app profile, except with no client secret,

and callback URL optional. I think that's good.

Section 5.5.3

We should (eventually) move some common language about the structure of the

verification code to security considerations I think.

Section 5.5.3.*

I think we can bundle all of these sections together in a way that would make them

easier to follow. Maybe something like this?

<snip>

Great rewrite. Changed.

Section 5.5.6

There is a random occurrence of "HTTP 400 Bad Request" in the text. =)

Thanks. Fixed the other two as well.

Section 5.5.7 Access Token Refresh

We MUST require client id and client secret when refreshing delegation tokens.

Otherwise there is no way to recover from compromised delegation tokens besides

revoking all of them.

(If we require client id and client secret, we can just rotate the client secret.)

If the Client's token is compromised, AS should invalidate and the Client needs to get a new one. 

If the Client is a web app and the whole DB is comprised. (Possible, but unlikely) I think it is a good idea the Client has to re-establish trust with the User to get a new set of tokens. 

Client secrets don't exist anymore in Rich Apps.

Section 6.6

Where did the 2083 byte limit come from?

Google search =)

Section 6.7

rather than saying JWT and SWT are recommended, we should say "MAY".

Done.

<WRAP_0_9_6_0_comments.pdf>