Summary

Add documentation on OAuth2

Review Request #9378 — Created Nov. 15, 2017 and submitted Nov. 16, 2017, 2:37 p.m.

Information

Owner

david

Repository

Review Board

Branch

release-3.0.x

Bugs

Depends On

Commit

65b5ecc...

Reviewers

Groups

reviewboard

People

Description

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.

Testing Done

Built HTML, checked output.

Issues

Description	From	Last Updated
"OAuth2"	chipx86	Nov. 16, 2017, 1:42 p.m.
Should be webapi2.0-oauth2-authentication	chipx86	Nov. 16, 2017, 1:43 p.m.
"OAuth2"	chipx86	Nov. 16, 2017, 1:43 p.m.
"contents"	chipx86	Nov. 16, 2017, 1:43 p.m.
"oauth2-authorization-flow"	chipx86	Nov. 16, 2017, 1:44 p.m.
Can you move this below "api-token-policy"?	chipx86	Nov. 16, 2017, 1:44 p.m.
Missing backticks after :term:	chipx86	Nov. 16, 2017, 1:45 p.m.
"OAuth2"	chipx86	Nov. 16, 2017, 1:45 p.m.
Looks like we have a casing inconsistency in the form. Mind fixing it while working on this? We define labels …	chipx86	Nov. 16, 2017, 1:45 p.m.
Should use: :rfc:`RFC 6749 Section 2.1 <6749#section-2.1>` This will link to the right place.	chipx86	Nov. 16, 2017, 1:46 p.m.
Can you use :term: for "local sites"?	chipx86	Nov. 16, 2017, 1:46 p.m.
"oauth2-authorization-flow"	chipx86	Nov. 16, 2017, 1:46 p.m.
"OAuth2"	chipx86	Nov. 16, 2017, 1:47 p.m.
"oauth2"	chipx86	Nov. 16, 2017, 1:47 p.m.
"webapi2.0-oauth2-authentication" and :mailheader: for the header name (note that single backticks like this without a role name will create a …	chipx86	Nov. 16, 2017, 1:47 p.m.
"oauth2-scopes"	chipx86	Nov. 16, 2017, 1:47 p.m.

flake8 passed.

JSHint passed.

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.

david Nov. 16, 2017, 2:09 p.m.

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.

chipx86 Nov. 16, 2017, 2:14 p.m.

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)".

docs/manual/webapi/2.0/authenticating.rst (Diff revision 1)
The issue has been resolved. Show all issues
```
"OAuth2"
```
docs/manual/webapi/2.0/authenticating.rst (Diff revision 1)
The issue has been resolved. Show all issues
```
Should be webapi2.0-oauth2-authentication
```
docs/manual/webapi/2.0/authenticating.rst (Diff revision 1)
The issue has been resolved. Show all issues
```
"OAuth2"
```
docs/manual/webapi/2.0/authenticating.rst (Diff revision 1)
The issue has been resolved. Show all issues
```
"contents"
```
docs/manual/webapi/2.0/authenticating.rst (Diff revision 1)
The issue has been resolved. Show all issues
```
"oauth2-authorization-flow"
```
docs/manual/webapi/2.0/index.rst (Diff revision 1)
The issue has been resolved. Show all issues
```
Can you move this below "api-token-policy"?
```
docs/manual/webapi/2.0/oauth2.rst (Diff revision 1)
The issue has been resolved. Show all issues
```
Missing backticks after :term:
```
docs/manual/webapi/2.0/oauth2.rst (Diff revision 1)
The issue has been resolved. Show all issues
```
"OAuth2"
```

docs/manual/webapi/2.0/oauth2.rst (Diff revision 1)

The issue has been resolved. 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).

docs/manual/webapi/2.0/oauth2.rst (Diff revision 1)

The issue has been resolved. Show all issues

Should use:

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

This will link to the right place.

docs/manual/webapi/2.0/oauth2.rst (Diff revision 1)
The issue has been resolved. Show all issues
```
Can you use :term: for "local sites"?
```
docs/manual/webapi/2.0/oauth2.rst (Diff revision 1)
The issue has been resolved. Show all issues
```
"oauth2-authorization-flow"
```
docs/manual/webapi/2.0/oauth2.rst (Diff revision 1)
The issue has been resolved. Show all issues
```
"OAuth2"
```
docs/manual/webapi/2.0/oauth2.rst (Diff revision 1)
The issue has been resolved. Show all issues
```
"oauth2"
```

docs/manual/webapi/2.0/oauth2.rst (Diff revision 1)

The issue has been resolved. 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).

docs/manual/webapi/2.0/oauth2.rst (Diff revision 1)
The issue has been resolved. Show all issues
```
"oauth2-scopes"
```

Commit:

0cc9dc0739a61e7569dd0efb59f8ad5344ca22ad

65b5ecc5900b9dd115b50eb7712a946b0a59fab8

Diff:

Revision 2 (+208 -13)

Show changes

	docs/manual/users/settings.rst
	docs/manual/webapi/index.rst
	docs/manual/webapi/2.0/authenticating.rst
	docs/manual/webapi/2.0/index.rst
	docs/manual/webapi/2.0/oauth2.rst
	reviewboard/oauth/forms.py

Checks run (2 succeeded)

flake8 passed.

JSHint passed.

Ship it!

```
Ship It!
```

Status:: Completed
Change Summary:: Pushed to release-3.0.x (16be050)