Add documentation on OAuth2

Review Request #9378 — Created Nov. 15, 2017 and submitted

Information

Review Board
release-3.0.x
65b5ecc...

Reviewers

This change adds a new page to the docs for how to use OAuth with the
Review Board API. This includes the specifics of using the UI to
register a new application, as well as the details of the authorization
handshake.

Built HTML, checked output.

Description From Last Updated

"OAuth2"

chipx86chipx86

Should be webapi2.0-oauth2-authentication

chipx86chipx86

"OAuth2"

chipx86chipx86

"contents"

chipx86chipx86

"oauth2-authorization-flow"

chipx86chipx86

Can you move this below "api-token-policy"?

chipx86chipx86

Missing backticks after :term:

chipx86chipx86

"OAuth2"

chipx86chipx86

Looks like we have a casing inconsistency in the form. Mind fixing it while working on this? We define labels …

chipx86chipx86

Should use: :rfc:`RFC 6749 Section 2.1 <6749#section-2.1>` This will link to the right place.

chipx86chipx86

Can you use :term: for "local sites"?

chipx86chipx86

"oauth2-authorization-flow"

chipx86chipx86

"OAuth2"

chipx86chipx86

"oauth2"

chipx86chipx86

"webapi2.0-oauth2-authentication" and :mailheader: for the header name (note that single backticks like this without a role name will create a …

chipx86chipx86

"oauth2-scopes"

chipx86chipx86
chipx86
  1. This looks great. Thanks for taking this on!

    Biggest comment you'll see throughout (I tried to catch all instances) is "OAuth" vs. "OAuth2." The distinction matters, as these are two incompatible standards.

    I noticed we're using "oauth" instead of "oauth2" in parts of the API and codebase... This might be okay still, as we'll probably use the same URLs to support both standards, and it's consistent with GitHub and other APIs, but docs should at least be explicit about which we're referring to. There might be other such inconsistencies we'll need to fix somewhere in the codebase, but not worth doing in this change.

    1. I don't see any compelling reason for Review Board to ever support OAuth 1. I think it's fine to have "oauth" in the code with the understanding that it's only the 2.0 version of the spec.

    2. Yeah, I don't either. In my mind when writing that, "we'll probably use the same URLs" was "we'd probably have used the same URLS (if we were supporting both)".

  2. Show all issues

    "OAuth2"

  3. Show all issues

    Should be webapi2.0-oauth2-authentication

  4. Show all issues

    "OAuth2"

  5. Show all issues

    "contents"

  6. Show all issues

    "oauth2-authorization-flow"

  7. docs/manual/webapi/2.0/index.rst (Diff revision 1)
     
     
    Show all issues

    Can you move this below "api-token-policy"?

  8. docs/manual/webapi/2.0/oauth2.rst (Diff revision 1)
     
     
    Show all issues

    Missing backticks after :term:

  9. docs/manual/webapi/2.0/oauth2.rst (Diff revision 1)
     
     
    Show all issues

    "OAuth2"

  10. docs/manual/webapi/2.0/oauth2.rst (Diff revision 1)
     
     
     
     
     
     
     
     
     
    Show all issues

    Looks like we have a casing inconsistency in the form. Mind fixing it while working on this? We define labels in reviewboard/oauth/forms.py (see line 217).

  11. docs/manual/webapi/2.0/oauth2.rst (Diff revision 1)
     
     
    Show all issues

    Should use:

    :rfc:`RFC 6749 Section 2.1 <6749#section-2.1>`
    

    This will link to the right place.

  12. docs/manual/webapi/2.0/oauth2.rst (Diff revision 1)
     
     
    Show all issues

    Can you use :term: for "local sites"?

  13. docs/manual/webapi/2.0/oauth2.rst (Diff revision 1)
     
     
    Show all issues

    "oauth2-authorization-flow"

  14. docs/manual/webapi/2.0/oauth2.rst (Diff revision 1)
     
     
    Show all issues

    "OAuth2"

  15. docs/manual/webapi/2.0/oauth2.rst (Diff revision 1)
     
     
     
     
    Show all issues

    "oauth2"

  16. docs/manual/webapi/2.0/oauth2.rst (Diff revision 1)
     
     
    Show all issues

    "webapi2.0-oauth2-authentication" and :mailheader: for the header name (note that single backticks like this without a role name will create a broken link as well).

  17. docs/manual/webapi/2.0/oauth2.rst (Diff revision 1)
     
     
    Show all issues

    "oauth2-scopes"

  18. 
      
david
chipx86
  1. Ship It!
  2. 
      
david
Review request changed
Status:
Completed
Change Summary:
Pushed to release-3.0.x (16be050)