Auth Flow Review

[hupili]

SAP

• auth, in synchronous model, this is the access point for users and apps. According to different auth_info configurations, the behaviour is different. Users can override auth_first and auth_second to add more alternatives.
• need_auth. The name is ambiguous. In next major version, it will be called need_two_stage_auth. Platforms like Twitter and email do not need two stage auth. This member function of them will return False. When need_auth is false, one should only call auth() as a whole to complete the authentication/ authorization process and do not assume the existence of auth_first and auth_second.
• auth_first / auth_second. As is said above, the two methods should only be used: 1) to separate the two-stages, e.g. SNSRouter; 2) when need_auth is True.

The flow

Here's the most complete flow

auth()*
  get_saved_token()
  auth_first()*
    request_url()+
  auth_second()*
    fetch_code()+
    get_access_token()+
  save_token()

The markers:

• *: those are normal SAP for upper layers. See SAP section for more description.
• +: those are configurable places. We provide multiple alternatives so that most desktop normal use cases are covered. Only override them when necessary.

Remarks:

• get_access_token is not isolated at present. This is because we are dealing with the code-style OAuth2 flows at first. Note that many platforms are still using OAuth1 (similar to token-style OAuth2), we need to upgrade the framework.

Following are some use cases:

code-style OAuth via browser + local HTTPD

auth_info:{
"cmd_request_url": "(local_webserver)+(webbrowser)",
"cmd_fetch_code": "(local_webserver)",
"cmd_get_access_token": "(direct)"
}

When see (direct), the plugin supplied _get_access_token is called. In SNSBase, this is defaulted to _oauth2_get_access_token.

token-style OAuth via browser + local HTTPD

auth_info:{
"cmd_request_url": "(local_webserver)+(webbrowser)",
"cmd_fetch_code": "(dummy)",
"cmd_get_access_token": "(local_webserver)"
}

input access_token directly

auth_info:{
"cmd_request_url": "(dummy)",
"cmd_fetch_code": "(dummy)",
"cmd_get_access_token": "(console_input)"
}

e.g. sometimes, you already get the access_token somehow....

TODO

• Retire the else branch of request_url and fetch_code. That is to disable arbitrary command execution. According to my current knowledge, nobody is using it. The original intention is to give some flexibility to non-Python programmers. Since most users are also Python programmers, a better way is to override them by Python functions, see how SNSRouter extends the two auth components.
• Clear the auth_first and auth_second if the plugin does not use it.
• Add object storage interface. The current get_saved_token() and save_token() only uses file as the medium. Object storage adapter allows changing the backend. Same applies for conf/.
• get_access_token
• In some OAuth models, parameters are piggybacked by URI fragmentation, i.e. #access_token=xxxx. The lightweight HTTPD shipped with SNSAPI can be upgraded to issue a redirect.

Related

#77 #87 #88