[Twisted-Python] twisted cred: why does avatarId need to be a str?

[Laurens Van Houtven]

Actually, I believe much of the confusion is cleared up. Apparently I
misunderstood what a Realm does. Oops!

The application in the original mail, which I will continue to talk about in
this one, is a token endpoint. I've been told an explanation of what that is
is in order. To start out: it is NOT the thing that actually serves
protected resources, that's a resource server, which is a different beast
entirely. The job of a token endpoint is to turn certain kinds of
credentials into an access token; the access token, in turn, can be used to
access protected resources. So basically, these credentials are about
already provided access grants, that haven't been turned into access tokens
yet. Examples of such credentials which can be turned in for access tokens:

    - authorization code: This represents an access grant from the end user.
Instead of receiving an access token when the grant was issued, you got this
code, which basically is a credential that says "This person is allowed to
access the protected resource, but we haven't given him a proper token to do
that yet". The token endpoint is for turning one of these into a token.
    - refresh token: in case your access token has been used up or expired,
one refresh token can be exchanged for one access token
    - assertion: this is basically just a pair of opaque strings (a type and
a value); it's used for tying OAuth in with existing systems. Hence, this is
deliberately vague.
    - user credentials: this is the classic username/password. It's a bit
silly to use this; the only advantage is that you can limit which servers
need access to these credentials.

The key thing to remember is: 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.

Since people asked for more detail as to which data exactly needs to be
passed to the Realm (yes, even now that I know what the Realm actually
does). This is basically all of the data in the token endpoint's
response. The response contains the following data, in JSON format:
(explanations of what each thing is in the following paragraphs)
    - the access token (an ascii string, mandatory)
    - the expiration time (optional)
    - the refresh token (another ascii string, similar to the access token,
optional)
    - scope (an ascii string consisting of a set of space-separated words,
optional)

Optional here does not really mean "at my option" but "occasionally
required", so it is necessary that all four can be passed to the IRealm at
the same time. Furthermore, it's impossible to use the Mind for some of
them, because ICredentialsCheckers never see the Mind, and all of that data
(access token, refresh token, expiration time, scope) are only ever visible
to the ICredentialsChecker.

Again, the access token is something you use to actually access a protected
resource. The refresh token is something you use to get a new token when
your old one expires or is used up. Defining the scope properly is hard,
it's deliberately vague in the spec as well; it's a set of strings that
determine what you can do with your shiny new access token. For example, for
Facebook, the scope might be "name friends likes" for a token that allows
someone to access your name, your list of friends and what you like, but not
your pictures, gender, date of birth. These values are not determined by the
spec, and you can just make some up for your service.

Also, to clear up a misunderstanding:
> (and furthermore, why is anybody responsible for "requesting the new
token" in the first place?  why do any new tokens ever need to be requested
on the service provider's side of things?)
Yes, sorry, that was a poorly chosen verb. I should have just said "creates
a new token"; I didn't, because typically token creation and storage happens
somewhere else in a centralized place (hence, this code *requests* it).


Does that help?
Laurens
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://twistedmatrix.com/pipermail/twisted-python/attachments/20100909/fce6624e/attachment.htm