Subject: [OAUTH-WG] OAuth 1.0a flow diagram

From: Idan Gazit <[email-masked]>
Date: Wed, 2 Dec 2009 02:21:19 +0200

Hey folks,

I redrew/updated an old diagram (http://documentation.fring.com/images/1/11/Oauth_diagram.png 
) outlining the OAuth authentication flow. The old one didn't reflect  
the changes in 1.0a.

The updated diagrams are here:

http://s3.pixane.com/Oauth_diagram.png
http://s3.pixane.com/Oauth_diagram.pdf

Please feel free to use them, I hereby place them in the public domain.

I was pointed in their direction by Mike Malone, after having looked  
for exactly such a thing (for quite a while). He mentioned that the  
reason it was chucked from the documentation is that it doesn't  
reflect the changes made in the wake of the session fixation attack. I  
took the old diagram, took the spec, and updated as required, with  
some minor changes for legibility and aesthetics.

Speaking as somebody who has tried (and failed) to digest OAuth by  
means of the long and detailed spec, this sort of diagram is extremely  
helpful in getting the "big picture" across. I'm not knocking the need  
for a good spec, but a one-page overview that pulls it all together  
without going into too much detail is sorely missing from the docs.  
This diagram goes a long way towards meeting that need.

Just my $0.02! Thanks for authoring this standard, hope this is useful!

-Idan

---

From: Eran Hammer-Lahav <[email-masked]>
Date: Tue, 1 Dec 2009 19:43:45 -0700

Which version of the 'long and detailed' spec?

EHL

> -----Original Message-----
> From: [email-masked] [mailto:[email-masked]] On Behalf
> Of Idan Gazit
> Sent: Tuesday, December 01, 2009 4:21 PM
> To: [email-masked]
> Subject: [OAUTH-WG] OAuth 1.0a flow diagram
> 
> Hey folks,
> 
> I redrew/updated an old diagram
> (http://documentation.fring.com/images/1/11/Oauth_diagram.png
> ) outlining the OAuth authentication flow. The old one didn't reflect the
> changes in 1.0a.
> 
> I was pointed in their direction by Mike Malone, after having looked for
> exactly such a thing (for quite a while). He mentioned that the reason it was
> chucked from the documentation is that it doesn't reflect the changes made
> in the wake of the session fixation attack. I took the old diagram, took the
> spec, and updated as required, with some minor changes for legibility and
> aesthetics.
> 
> Speaking as somebody who has tried (and failed) to digest OAuth by means
> of the long and detailed spec, this sort of diagram is extremely helpful in
> getting the "big picture" across. I'm not knocking the need for a good spec,
> but a one-page overview that pulls it all together without going into too
> much detail is sorely missing from the docs.
> _______________________________________________
> OAuth mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/oauth

---

From: Idan Gazit <[email-masked]>
Date: Wed, 2 Dec 2009 12:16:05 +0200

It's been a while since I last looked at it, quite possibly before  
June, so it might have been the 1.0 spec.

 From looking at oauth.net now, it seems that more introductory  
material was added (or made more prominent) since last I saw it.

My experience with the spec was sitting down to read it every once in  
a while and getting bogged down in signature methods and precise  
language describing the various entities in an OAuth transaction. I  
came to the spec with a good idea of what OAuth is and what it is  
supposed to accomplish, I just wanted a non-authoritative list of  
steps for a run-of-the-mill OAuth transaction written for ease of  
understanding rather than maximal specificity. Not instead of the  
spec, but in addition to, something that I could use to orient myself  
within the spec.

Again, I'd like to emphasize that I'm not criticizing the spec. I  
think my needs are representative of a common use-case: experienced  
web developer looking to provide or consume an OAuth service, probably  
using an existing library, and therefore disinterested in signature  
methods and other things which are already abstracted away. If I had  
to learn how HTTP worked by reading RFC2516 I'd probably be hopelessly  
lost too, but thankfully the internets are chock-full of diagrams  
which make the learning curve less steep.

Hope I haven't added too much noise to the list! I'm happy to provide  
a "cold eye" to future writing if it will be of help.

-I

---

From: Paul Madsen <[email-masked]>
Date: Wed, 02 Dec 2009 08:23:31 -0500

Idan, typo in Step E

'oauth_vesion (optional)'

paul

Idan Gazit wrote:
> (http://documentation.fring.com/images/1/11/Oauth_diagram.png) 
> outlining the OAuth authentication flow. The old one didn't reflect 
> the changes in 1.0a.
>

---

From: Idan Gazit <[email-masked]>
Date: Wed, 2 Dec 2009 15:29:56 +0200

Whoops, fixed. Good catch!

Replaced the old versions, same URLs:

Thanks!

-I

---

From: Eran Hammer-Lahav <[email-masked]>
Date: Wed, 2 Dec 2009 09:18:37 -0700

I want you to criticize the spec! I already called it worse names than most people so you are not likely to offend anyone. Take a look at the new spec [1] and let me know if it makes understanding the protocol easier for your target audience.

EHL

[1] http://tools.ietf.org/html/draft-hammer-oauth-07

> From: Idan Gazit [mailto:[email-masked]]
> Sent: Wednesday, December 02, 2009 2:16 AM
> To: Eran Hammer-Lahav
> Cc: [email-masked]
> Subject: Re: [OAUTH-WG] OAuth 1.0a flow diagram
> 
> It's been a while since I last looked at it, quite possibly before June, so it
> might have been the 1.0 spec.
> 
>  From looking at oauth.net now, it seems that more introductory material
> was added (or made more prominent) since last I saw it.
> 
> My experience with the spec was sitting down to read it every once in a
> while and getting bogged down in signature methods and precise language
> describing the various entities in an OAuth transaction. I came to the spec
> with a good idea of what OAuth is and what it is supposed to accomplish, I
> just wanted a non-authoritative list of steps for a run-of-the-mill OAuth
> transaction written for ease of understanding rather than maximal specificity.
> Not instead of the spec, but in addition to, something that I could use to
> orient myself within the spec.
> 
> Again, I'd like to emphasize that I'm not criticizing the spec. I think my needs
> are representative of a common use-case: experienced web developer
> looking to provide or consume an OAuth service, probably using an existing
> library, and therefore disinterested in signature methods and other things
> which are already abstracted away. If I had to learn how HTTP worked by
> reading RFC2516 I'd probably be hopelessly lost too, but thankfully the
> internets are chock-full of diagrams which make the learning curve less
> steep.
> 
> Hope I haven't added too much noise to the list! I'm happy to provide a "cold
> eye" to future writing if it will be of help.
> 
> -I
> 
>

---

From: Leah Culver <[email-masked]>
Date: Wed, 2 Dec 2009 08:40:51 -0800

Thanks for the new diagrams! I'm giving an OAuth talk today and I'll
probably use them. They look great!

Thanks!
Leah

---

From: Idan Gazit <[email-masked]>
Date: Wed, 2 Dec 2009 18:47:38 +0200

Honestly, somebody else made these first -- I just updated and  
prettified.

I'd love to know who laid out the original and thank *them* -- it is  
extremely well-designed.

-I

---

From: Peter Saint-Andre <[email-masked]>
Date: Thu, 03 Dec 2009 15:31:51 -0700

<hat type='individual'/>

On 12/1/09 5:21 PM, Idan Gazit wrote:
> (http://documentation.fring.com/images/1/11/Oauth_diagram.png) outlining
> the OAuth authentication flow. The old one didn't reflect the changes in
> 1.0a.
> 

Your diagrams are very helpful. Now we just need to convert them to
ASCII art for inclusion in an Internet-Draft. ;-)

> Please feel free to use them, I hereby place them in the public domain.

That's cool, too!

Peter

-- 
Peter Saint-Andre
https://stpeter.im/

---

From: Justin Richer <[email-masked]>
Date: Fri, 4 Dec 2009 09:28:16 -0500

When I was doing my implementations of 1.0, I kept a printout of the
original diagrams on my desk. They were much more helpful than the
actual technical spec for most of the implementation details that I
cared about, particularly since I was using a library for each part and
simply needed to know when to call what. I also re-used them in all of
my evangelistic talks on OAuth around the company. Thank you for
updating them to rev. a! I'd like to see these (or diagrams much like
them) included in the specs (or part of an "implementor's guide") in the
future.

 -- Justin

---

From: Richard Barnes <[email-masked]>
Date: Sun, 6 Dec 2009 21:39:41 -0500

Ask and ye shall receive:
<http://geopriv.dreamhosters.com/Oauth_diagram.txt>

(Updated terminology to match draft-hammer-oauth, i.e., s/Consumer/ 
Client/ and s/Service Provider/Server/)

On Dec 3, 2009, at 5:31 PM, Peter Saint-Andre wrote:

>> outlining

---

From: Chris Messina <[email-masked]>
Date: Sun, 6 Dec 2009 18:45:11 -0800

Richard, that ASCII art is top notch. Nice! ;)

Idan: what software did you use to make your flow? Would you mind sharing
the originals? I might make a few tweaks to see if I can make parts of the
diagram a bit more legible...!

Thanks,

Chris

On Sun, Dec 6, 2009 at 6:39 PM, Richard Barnes <[email-masked]> wrote:

> (Updated terminology to match draft-hammer-oauth, i.e., s/Consumer/Client/
> and s/Service Provider/Server/)
>
>
>

-- 
Chris Messina
Open Web Advocate

Personal: http://factoryjoe.com
Follow me on Twitter: http://twitter.com/chrismessina

Citizen Agency: http://citizenagency.com
Diso Project: http://diso-project.org
OpenID Foundation: http://openid.net

This email is:   [ ] shareable    [X] ask first   [ ] private

---

From: Richard Barnes <[email-masked]>
Date: Sun, 6 Dec 2009 21:49:24 -0500

The software was MacVim :)

Based on Idan's pictures at the top of this thread, namely:
<http://s3.pixane.com/Oauth_diagram.pdf>

Good luck revising.  Remember that you need to stay within 60 rows /  
72 columns to fit in the RFC format!
<http://tools.ietf.org/html/rfc678>

--Richard

On Dec 6, 2009, at 9:45 PM, Chris Messina wrote:

> Idan: what software did you use to make your flow? Would you mind  
> sharing the originals? I might make a few tweaks to see if I can  
> make parts of the diagram a bit more legible...!
>
> Thanks,
>
> Chris
>

---

From: Chris Messina <[email-masked]>
Date: Sun, 6 Dec 2009 19:09:56 -0800

Ah, sorry, I meant revising Idan's PDF version... not the ASCII version. ;)

On Sun, Dec 6, 2009 at 6:49 PM, Richard Barnes <[email-masked]> wrote:

> Good luck revising.  Remember that you need to stay within 60 rows / 72
> columns to fit in the RFC format!

-- 
Chris Messina
Open Web Advocate

---

From: Idan Gazit <[email-masked]>
Date: Mon, 7 Dec 2009 10:12:24 +0200

Chris, I used OmniGraffle. I've put the original up here:

http://s3.pixane.com/Oauth_diagram.graffle.zip

The only catch is that I've used some commercial fonts:

Museo Sans 900 (commercial)
Museo 100 (commercial)
League Gothic (free, http://bit.ly/league_gothic)

I'm happy to make changes, what parts of the diagram bother you?

-I

---

From: Idan Gazit <[email-masked]>
Date: Mon, 7 Dec 2009 10:13:34 +0200

Hey, that's awesome.

Should I update to match?

---

From: Richard Barnes <[email-masked]>
Date: Mon, 7 Dec 2009 09:12:59 -0500

I like consistency of terminology.  If we're trying to get people to  
move over to using the IETF spec, then it's probably a good idea to  
change the terms to match.  The mapping is pretty simple; quoting from  
draft-hammer-oauth-08:
"
    The original community specification used a somewhat different
    terminology which maps to this specifications as follows (original
    community terms provided on left):

    Consumer:  client

    Service Provider:  server

    User:  resource owner

    Consumer Key and Secret:  client credentials

    Request Token and Secret:  temporary credentials

    Access Token and Secret:  token credentials
"