<div class="gmail_quote">I'll give a very practical example of an example request + response, because I'm not entirely sure I communicated that properly. The code we're discussing is part of a TokenEndpoint, which is an IResource. Something (a client, in OAuth terminology) makes a request that looks like this:</div>
<div class="gmail_quote"><br></div><div class="gmail_quote">---</div><div class="gmail_quote"><div class="gmail_quote">POST /token HTTP/1.1</div><div class="gmail_quote">Host: <a href="http://server.example.com" target="_blank">server.example.com</a></div>
<div class="gmail_quote">
Content-Type: application/x-www-form-urlencoded</div><div class="gmail_quote"><br></div><div class="gmail_quote">grant_type=password&client_id=s6BhdRkqt3&client_secret=47HDu8s&username=johndoe&password=A3ddj3w</div>
<div>---</div><div><br></div></div><div class="gmail_quote">And hopefully the code we're discussing answers with a request that looks like this:</div><div class="gmail_quote"><br></div><div class="gmail_quote">---</div>
<div class="gmail_quote"><div class="gmail_quote">
HTTP/1.1 200 OK</div><div class="gmail_quote">Content-Type: application/json</div><div class="gmail_quote">
Cache-Control: no-store</div><div class="gmail_quote"><br></div><div class="gmail_quote">{</div><div class="gmail_quote">"access_token":"SlAV32hkKG",</div><div class="gmail_quote">"expires_in":3600,</div>
<div class="gmail_quote">
"refresh_token":"8xLOxBtZp8"</div><div class="gmail_quote">"scope": "tummies cookies parrots"</div><div class="gmail_quote">}</div><div>---</div><div><br></div></div><div class="gmail_quote">
Where, as mentioned before, everything besides "access_token" is not always required (but it must be possible to set them, because occasionally they are required).</div><div class="gmail_quote"><br></div><div class="gmail_quote">
On Fri, Sep 10, 2010 at 2:34 AM, Glyph Lefkowitz <span dir="ltr"><<a href="mailto:glyph@twistedmatrix.com" target="_blank">glyph@twistedmatrix.com</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
<div style="word-wrap:break-word"><div>for any given cred implementation, there are two key questions:</div><div><ol><li>What is the avatar interface?</li><li>What is the associated mind interface?</li></ol></div>
<div>If we're not talking about a system where the avatar interface (the one passed to 'login', the one that the realm must return something that gets implemented) is IResource, then that's the problem. What <i>is</i> that interface that you're talking about? Be very specific: what methods does it have and why?</div>
</div></blockquote><div><br></div><div>Okay, to be specific: I believe the appropriate interface is IResource. This is in line with t.web's general way of interacting with cred: you give me credentials, I give you a protected IResource.<br>
</div><div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div style="word-wrap:break-word"><div>It sounds like OAuth is very precisely implementing something that maps almost exactly onto the <i>checker</i> part of cred, but you're doing it by implementing a realm to allow applications to provide their own logic. This might not be the wrong idea, but it needs to be spelled out very clearly.</div>
</div></blockquote><div><br></div><div>Doing everything in the checker probably might make more sense. The reason I originally thought to do this in the IRealm is that I figured credentials checkers should just check credentials, and creating a new credential (the access token) wasn't part of ICredentialsChecker's job (more like IRealm's job). Apparently I was mistaken.</div>
<div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
<div style="word-wrap:break-word"><div>As you describe it:</div><div><div><blockquote type="cite">token endpoints let you trade in some credentials that prove you're supposed to have access for a token that actually *gives* you that access</blockquote>
</div></div><div>In cred-ese, that would be "checkers let you trade in some credentials that prove you're supposed to have access for an <avatar ID, which you give to a Realm> that actually *gives* you that access". As far as the OAuth response is concerned, it's like a checker. Looking at the individual parts, assuming that the avatar interface for the purposes of this discussion is IResource, it breaks down like this in my mind:</div>
<div><div><blockquote type="cite"><div> - the access token (an ascii string, mandatory)</div></blockquote></div><div>Avatar ID. (See, it's a str!)</div></div></div></blockquote><div><br></div><div>Heh, okay; as long as there's a plausible way to get the other important information (see rest of email) into the HTTP response, I'll believe you. </div>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div style="word-wrap:break-word"><div><blockquote type="cite">
<div> - the expiration time (optional)</div></blockquote><div>Implementation detail of the session. Avatars are actually sessions, which expire: sometimes (as with POP) at the end of a connection, sometimes (as with nevow.guard's HTTP support) with a session timeout.</div>
</div></div></blockquote><div><br></div><div>Right, but:</div><div>a) The avatar needs to know about this timeout, since the timeout information needs to be able to make it into the HTTP response.</div><div>b) The expiration time is only known to the thing that creates the access token (obviously). >From the previous discussion, this is apparently ICredentialsChecker.</div>
<div><br></div><div>c) (From (a, b)) The ICredentialsChecker needs to be able to communicate the expiration to the avatar.</div><div>d) The ICredentialsChecker and IRealm can only communicate through the avatarId.</div><div>
<br></div><div>Conclusion (from c,d): The expiration time needs to be in the avatarId?</div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div style="word-wrap:break-word">
<div><div><blockquote type="cite"><div> - the refresh token (another ascii string, similar to the access token, optional)</div></blockquote><div><br></div></div><div>Implementation detail of the authentication protocol. The client library and server library should be transparently refreshing this without telling either the client application code or server application code, right?</div>
</div></div></blockquote><div><br></div><div>Sure, but we're still writing library code here.</div><div><br></div><div>If the avatar interface isn't actually IResource, but a new interface IAccessToken, getting the refresh token later might be feasible. (It should be a different interface, because in order to create a refresh token outside of this entire cred cycle, I need to know about the thing it's refreshing -- so, the information in the response needs to be easily accessible and not just an opaque IResource).</div>
<div><br></div><div>I agree entirely that clever client library code would abstract this mess away from application code. However, right now this code still needs to somehow be able to eventually produce HTTP responses that don't abstract anything yet and just contain all the appropriate data, because that's just what the OAuth spec says it needs to be able to do. There isn't any real application code in the token endpoint; they're pretty similar for all OAuth setups, and customization would typically happen through implementing the appropriate ICredentialsChecker.</div>
<div><br></div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div style="word-wrap:break-word"><div><div><blockquote type="cite"><div> - scope (an ascii string consisting of a set of space-separated words, optional)</div>
</blockquote></div></div><div><br></div>This part doesn't quite fit, but could be expressed in one of two ways: a modification to the avatar ID, or as some extra structure on the Mind that modifies what functionality the Realm bundles in to your avatar implementation (without changing the interface provided by that object, of course).</div>
</blockquote><div><br></div><div>Unfortunately I don't believe this can be done through the mind. Again working under the previous assumption that ICredentialsChecker and not the IRealm is responsible for creating the access token, and scope is known to the thing that makes the access token, the ICredentialsChecker knows about the scope. Unfortunately the only way to pass stuff between the ICredentialsChecker and the IRealm is the avatar ID, so you don't have a choice.</div>
<div><br></div><div> </div></div>thanks for your infinite patience,
<div>Laurens</div>