Skip to content

Update OAuth2 section #927

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 14 commits into from
Aug 12, 2020
Merged

Update OAuth2 section #927

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
14 commits
Select commit Hold shift + click to select a range
7c734ed
update oauth section
mmccool Jul 13, 2020
0615a64
update ontology file
mmccool Jul 13, 2020
e7907e5
update ontology rendering, OAuth 2.0 usage
mmccool Jul 13, 2020
89fc97b
Merge remote-tracking branch 'upstream/master' into update-oauth2
mmccool Jul 27, 2020
b5dcfd9
correct mandatory fields for flows
mmccool Jul 27, 2020
8c4156e
edits
mmccool Aug 3, 2020
d3f873e
edits
mmccool Aug 3, 2020
04d3ae8
render
mmccool Aug 3, 2020
a0fee1f
add ed note
mmccool Aug 3, 2020
75a49fb
fix typo
mmccool Aug 3, 2020
e9bacd9
add table
mmccool Aug 3, 2020
e8552ff
add ed note
mmccool Aug 3, 2020
0fdc5e5
add refresh to table
mmccool Aug 3, 2020
b4f4228
make comment in security ontology consistent with text
mmccool Aug 10, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
47 changes: 43 additions & 4 deletions index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1359,17 +1359,56 @@ <h2>Security Vocabulary Definitions</h2>
<tr class="rfc2119-table-assertion" id="td-vocab-name--DigestSecurityScheme"><td><code>name</code></td><td>Name for query, header, or cookie parameters.</td><td>optional</td><td><a href="http://www.w3.org/TR/2012/REC-xmlschema11-2-20120405/#string"><code>string</code></a></td></tr></tbody></table></section>
<section><h3><code>APIKeySecurityScheme</code></h3><p>API key authentication security configuration identified by the <a>Vocabulary Term</a> <code>apikey</code> (i.e., <code>"scheme": "apikey"</code>). This is for the case where the access token is opaque and is not using a standard token format.</p><table class="def"><thead><tr><th><a>Vocabulary term</a></th><th>Description</th><th>Assignment</th><th>Type</th></tr></thead><tbody><tr class="rfc2119-table-assertion" id="td-vocab-in--APIKeySecurityScheme"><td><code>in</code></td><td>Specifies the location of security authentication information.</td><td><a href="#sec-default-values">with default</a></td><td><a href="http://www.w3.org/TR/2012/REC-xmlschema11-2-20120405/#string"><code>string</code></a> (one of <code>header</code>, <code>query</code>, <code>body</code>, or <code>cookie</code>)</td></tr>
<tr class="rfc2119-table-assertion" id="td-vocab-name--APIKeySecurityScheme"><td><code>name</code></td><td>Name for query, header, or cookie parameters.</td><td>optional</td><td><a href="http://www.w3.org/TR/2012/REC-xmlschema11-2-20120405/#string"><code>string</code></a></td></tr></tbody></table></section>
<section><h3><code>BearerSecurityScheme</code></h3><p>Bearer Token [[!RFC6750]] security configuration identified by the <a>Vocabulary Term</a> <code>bearer</code> (i.e., <code>"scheme": "bearer"</code>) for situations where bearer tokens are used independently of OAuth2. If the <code>oauth2</code> scheme is specified it is not generally necessary to specify this scheme as well as it is implied. For <code>format</code>, the value <code>jwt</code> indicates conformance with [[!RFC7519]], <code>jws</code> indicates conformance with [[!RFC7797]], <code>cwt</code> indicates conformance with [[!RFC8392]], and <code>jwe</code> indicates conformance with [[!RFC7516]], with values for <code>alg</code> interpreted consistently with those standards. <span class="rfc2119-assertion" id="td-security-bearer-format-extensions">Other formats and algorithms for bearer tokens MAY be specified in vocabulary extensions</span>.</p><table class="def"><thead><tr><th><a>Vocabulary term</a></th><th>Description</th><th>Assignment</th><th>Type</th></tr></thead><tbody><tr class="rfc2119-table-assertion" id="td-vocab-authorization--BearerSecurityScheme"><td><code>authorization</code></td><td>URI of the authorization server.</td><td>optional</td><td><a href="http://www.w3.org/TR/2012/REC-xmlschema11-2-20120405/#anyURI"><code>anyURI</code></a></td></tr>
<section><h3><code>BearerSecurityScheme</code></h3><p>Bearer Token [[!RFC6750]] security configuration identified by the <a>Vocabulary Term</a> <code>bearer</code> (i.e., <code>"scheme": "bearer"</code>) for situations where bearer tokens are used independently of OAuth 2.0. If the <code>oauth2</code> scheme is specified it is not generally necessary to specify this scheme as well as it is implied. For <code>format</code>, the value <code>jwt</code> indicates conformance with [[!RFC7519]], <code>jws</code> indicates conformance with [[!RFC7797]], <code>cwt</code> indicates conformance with [[!RFC8392]], and <code>jwe</code> indicates conformance with [[!RFC7516]], with values for <code>alg</code> interpreted consistently with those standards. <span class="rfc2119-assertion" id="td-security-bearer-format-extensions">Other formats and algorithms for bearer tokens MAY be specified in vocabulary extensions</span>.</p><table class="def"><thead><tr><th><a>Vocabulary term</a></th><th>Description</th><th>Assignment</th><th>Type</th></tr></thead><tbody><tr class="rfc2119-table-assertion" id="td-vocab-authorization--BearerSecurityScheme"><td><code>authorization</code></td><td>URI of the authorization server.</td><td>optional</td><td><a href="http://www.w3.org/TR/2012/REC-xmlschema11-2-20120405/#anyURI"><code>anyURI</code></a></td></tr>
<tr class="rfc2119-table-assertion" id="td-vocab-alg--BearerSecurityScheme"><td><code>alg</code></td><td>Encoding, encryption, or digest algorithm.</td><td><a href="#sec-default-values">with default</a></td><td><a href="http://www.w3.org/TR/2012/REC-xmlschema11-2-20120405/#string"><code>string</code></a> (e.g., <code>MD5</code>, <code>ES256</code>, or <code>ES512-256</code>)</td></tr>
<tr class="rfc2119-table-assertion" id="td-vocab-format--BearerSecurityScheme"><td><code>format</code></td><td>Specifies format of security authentication information.</td><td><a href="#sec-default-values">with default</a></td><td><a href="http://www.w3.org/TR/2012/REC-xmlschema11-2-20120405/#string"><code>string</code></a> (e.g., <code>jwt</code>, <code>cwt</code>, <code>jwe</code>, or <code>jws</code>)</td></tr>
<tr class="rfc2119-table-assertion" id="td-vocab-in--BearerSecurityScheme"><td><code>in</code></td><td>Specifies the location of security authentication information.</td><td><a href="#sec-default-values">with default</a></td><td><a href="http://www.w3.org/TR/2012/REC-xmlschema11-2-20120405/#string"><code>string</code></a> (one of <code>header</code>, <code>query</code>, <code>body</code>, or <code>cookie</code>)</td></tr>
<tr class="rfc2119-table-assertion" id="td-vocab-name--BearerSecurityScheme"><td><code>name</code></td><td>Name for query, header, or cookie parameters.</td><td>optional</td><td><a href="http://www.w3.org/TR/2012/REC-xmlschema11-2-20120405/#string"><code>string</code></a></td></tr></tbody></table></section>
<section><h3><code>PSKSecurityScheme</code></h3><p>Pre-shared key authentication security configuration identified by the <a>Vocabulary Term</a> <code>psk</code> (i.e., <code>"scheme": "psk"</code>).</p><table class="def"><thead><tr><th><a>Vocabulary term</a></th><th>Description</th><th>Assignment</th><th>Type</th></tr></thead><tbody><tr class="rfc2119-table-assertion" id="td-vocab-identity--PSKSecurityScheme"><td><code>identity</code></td><td>Identifier providing information which can be used for selection or confirmation.</td><td>optional</td><td><a href="http://www.w3.org/TR/2012/REC-xmlschema11-2-20120405/#string"><code>string</code></a></td></tr></tbody></table></section>
<section><h3><code>OAuth2SecurityScheme</code></h3><p>OAuth2 authentication security configuration for systems conformant with [[!RFC6749]] and [[!RFC8252]], identified by the <a>Vocabulary Term</a> <code>oauth2</code> (i.e., <code>"scheme": "oauth2"</code>). <span class="rfc2119-assertion" id="td-security-oauth2-code-flow">For the <code>code</code> flow both <code>authorization</code> and <code>token</code> MUST be included.</span> If no <code>scopes</code> are defined in the <code>SecurityScheme</code> then they are considered to be empty.</p><table class="def"><thead><tr><th><a>Vocabulary term</a></th><th>Description</th><th>Assignment</th><th>Type</th></tr></thead><tbody><tr class="rfc2119-table-assertion" id="td-vocab-authorization--OAuth2SecurityScheme"><td><code>authorization</code></td><td>URI of the authorization server.</td><td>optional</td><td><a href="http://www.w3.org/TR/2012/REC-xmlschema11-2-20120405/#anyURI"><code>anyURI</code></a></td></tr>
<section><h3><code>OAuth2SecurityScheme</code></h3><p>OAuth 2.0 authentication security configuration for systems conformant with [[!RFC6749]], [[!RFC8252]] and (for the <code>device</code> flow) [[!RFC8628]], identified by the <a>Vocabulary Term</a> <code>oauth2</code> (i.e., <code>"scheme": "oauth2"</code>).
<span class="rfc2119-assertion" id="td-security-oauth2-code-flow">For the <code>code</code> flow both <code>authorization</code> and <code>token</code> MUST be included.</span>
<span class="rfc2119-assertion" id="td-security-oauth2-client-flow">For the <code>client</code> flow <code>token</code> MUST be included.</span>
<span class="rfc2119-assertion" id="td-security-oauth2-client-flow-no-auth">For the <code>client</code> flow <code>authorization</code> MUST NOT be included.</span>
<span class="rfc2119-assertion" id="td-security-oauth2-device-flow">For the <code>device</code> flow both <code>authorization</code> and <code>token</code> MUST be included.</span>
In the case of the <code>device</code> flow
the value provided for <code>authorization</code> refers to the device authorization endpoint defined in [[!RFC8628]].
The mandatory elements for each flow are summarized in the following table:
<table class="def">
<tr><th>Element</th><th><code>code</code></th><th><code>client</code></th><th><code>device</code></th></tr>
<tr><td><code>authorization</code></td><td>mandatory</td><td>omit</td><td>mandatory; refers to device authorization endpoint</td></tr>
<tr><td><code>token</code></td><td>mandatory</td><td>mandatory</td><td>mandatory</td></tr>
<tr><td><code>refresh</code></td><td>optional</td><td>optional</td><td>optional</td></tr>
</table>
</p>
<p class="ednote">
Note that the table below lists these elements as "optional". In fact whether they are mandatory or not depends on the flow.
The <code>token</code> element is listed as optional even though it is mandatory for all predefined flows since it might
not be mandatory for some flows defined in an extension. We should investigate whether there is a better way to express these
"variant record" constraints.
</p>
<p>If multiple flows are available (for example, multiple OAuth 2.0 security schemes with different flows are given for a <code>Form</code>) then only
one may be selected for use by a <a>Consumer</a>.
<span class="rfc2119-assertion" id="td-security-oauth2-other-flows">If an OAuth 2.0 flow other than <code>code</code>, <code>client</code> or <code>device</code> needs to be specified an extension vocabulary MUST be used.</span>
This includes the <code>password</code> and <code>implicit</code> flows, which are no longer considered best practice [[WOT-SECURITY-GUIDELINES]].
This also applies to flows that are similar at the protocol level but do
not exactly follow the OAuth 2.0 specification,
for example by automating grants rather than invoking a user agent to interact with a human resource owner.
If no <code>scopes</code> are defined in the <code>SecurityScheme</code> then they are considered to be empty.</p>
<p class="ednote">The device authorization endpoint technically uses a different protocol than the authorization endpoint used by other flows,
and it might be possible for a developer to confuse the two.
However, since the <code>device</code> flow does not use the regular authorization endpoint there should be no ambiguity.
We are considering however an alternative design where there is a separate element,
<code>device_authorization</code>,
which MUST be included for the <code>device</code> flow (and then the regular authorization endpoint then MUST NOT be used).
</p>

<table class="def"><thead><tr><th><a>Vocabulary term</a></th><th>Description</th><th>Assignment</th><th>Type</th></tr></thead><tbody><tr class="rfc2119-table-assertion" id="td-vocab-authorization--OAuth2SecurityScheme"><td><code>authorization</code></td><td>URI of the authorization server.
In the case of the <code>device</code> flow, the URI provided for the <code>authorization</code> value refers to the <em>device authorization</em> endpoint [[!RFC8628]].
</td><td>optional</td><td><a href="http://www.w3.org/TR/2012/REC-xmlschema11-2-20120405/#anyURI"><code>anyURI</code></a></td></tr>
<tr class="rfc2119-table-assertion" id="td-vocab-token--OAuth2SecurityScheme"><td><code>token</code></td><td>URI of the token server.</td><td>optional</td><td><a href="http://www.w3.org/TR/2012/REC-xmlschema11-2-20120405/#anyURI"><code>anyURI</code></a></td></tr>
<tr class="rfc2119-table-assertion" id="td-vocab-refresh--OAuth2SecurityScheme"><td><code>refresh</code></td><td>URI of the refresh server.</td><td>optional</td><td><a href="http://www.w3.org/TR/2012/REC-xmlschema11-2-20120405/#anyURI"><code>anyURI</code></a></td></tr>
<tr class="rfc2119-table-assertion" id="td-vocab-scopes--OAuth2SecurityScheme"><td><code>scopes</code></td><td>Set of authorization scope identifiers provided as an array. These are provided in tokens returned by an authorization server and associated with forms in order to identify what resources a client may access and how. The values associated with a form should be chosen from those defined in an <code>OAuth2SecurityScheme</code> active on that form.</td><td>optional</td><td><a href="http://www.w3.org/TR/2012/REC-xmlschema11-2-20120405/#string"><code>string</code></a> or <a>Array</a> of <a href="http://www.w3.org/TR/2012/REC-xmlschema11-2-20120405/#string"><code>string</code></a></td></tr>
<tr class="rfc2119-table-assertion" id="td-vocab-flow--OAuth2SecurityScheme"><td><code>flow</code></td><td>Authorization flow.</td><td>mandatory</td><td><a href="http://www.w3.org/TR/2012/REC-xmlschema11-2-20120405/#string"><code>string</code></a> (e.g., <code>code</code>)</td></tr></tbody></table></section>
<tr class="rfc2119-table-assertion" id="td-vocab-flow--OAuth2SecurityScheme"><td><code>flow</code></td><td>Authorization flow.</td><td>mandatory</td><td><a href="http://www.w3.org/TR/2012/REC-xmlschema11-2-20120405/#string"><code>string</code></a> (e.g., <code>code</code>, <code>client</code>, or <code>device</code>)</td></tr></tbody></table></section>

</section>

Expand Down Expand Up @@ -2471,7 +2510,7 @@ <h3><code>securityDefinitions</code> and <code>security</code></h3>
</pre>

<p>
As another more complex example, OAuth2 makes use of scopes.
As another more complex example, OAuth 2.0 makes use of scopes.
These are identifiers that
may appear in tokens and must match with corresponding identifiers in a resource to allow
access to that resource (or <a>Interaction Affordance</a> in the case of W3C WoT).
Expand Down
Loading