From 7c734ed974dbabb9fa5e8adf91e9a38b3604c53b Mon Sep 17 00:00:00 2001 From: Michael McCool Date: Mon, 13 Jul 2020 10:29:32 -0300 Subject: [PATCH 01/13] update oauth section --- index.html | 13 +++++++++++-- index.template.html | 13 +++++++++++-- 2 files changed, 22 insertions(+), 4 deletions(-) diff --git a/index.html b/index.html index fb5552506..a8bb338b1 100644 --- a/index.html +++ b/index.html @@ -1365,11 +1365,20 @@

Security Vocabulary Definitions

inSpecifies the location of security authentication information.with defaultstring (one of header, query, body, or cookie) nameName for query, header, or cookie parameters.optionalstring

PSKSecurityScheme

Pre-shared key authentication security configuration identified by the Vocabulary Term psk (i.e., "scheme": "psk").

Vocabulary termDescriptionAssignmentType
identityIdentifier providing information which can be used for selection or confirmation.optionalstring
-

OAuth2SecurityScheme

OAuth2 authentication security configuration for systems conformant with [[!RFC6749]] and [[!RFC8252]], identified by the Vocabulary Term oauth2 (i.e., "scheme": "oauth2"). For the code flow both authorization and token MUST be included. If no scopes are defined in the SecurityScheme then they are considered to be empty.

+

OAuth2SecurityScheme

OAuth2 authentication security configuration for systems conformant with [[!RFC6749]], [[!RFC8252]] and (for the device flow) [[!RFC8628]], identified by the Vocabulary Term oauth2 (i.e., "scheme": "oauth2"). +For the code flow both authorization and token MUST be included. +For the client flow both authorization and token MUST be included. +For the device flow both authorization and token MUST be included. +If an OAuth 2.0 flow other than code, client or device needs to be specified an extension vocabulary MUST be used. +This includes the password and implicit flows, which are no longer considered best practice. +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 scopes are defined in the SecurityScheme then they are considered to be empty.

Vocabulary termDescriptionAssignmentType
authorizationURI of the authorization server.optionalanyURI
-
Vocabulary termDescriptionAssignmentType
authorizationURI of the authorization server.optionalanyURI
tokenURI of the token server.optionalanyURI
refreshURI of the refresh server.optionalanyURI
scopesSet 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 OAuth2SecurityScheme active on that form.optionalstring or Array of string
flowAuthorization flow.mandatorystring (e.g., code)
+flowAuthorization flow.mandatorystring (e.g., code, client, or device) diff --git a/index.template.html b/index.template.html index 8687c1527..8acabac94 100644 --- a/index.template.html +++ b/index.template.html @@ -1314,11 +1314,20 @@

Security Vocabulary Definitions

inSpecifies the location of security authentication information.with defaultstring (one of header, query, body, or cookie) nameName for query, header, or cookie parameters.optionalstring

PSKSecurityScheme

Pre-shared key authentication security configuration identified by the Vocabulary Term psk (i.e., "scheme": "psk").

Vocabulary termDescriptionAssignmentType
identityIdentifier providing information which can be used for selection or confirmation.optionalstring
-

OAuth2SecurityScheme

OAuth2 authentication security configuration for systems conformant with [[!RFC6749]] and [[!RFC8252]], identified by the Vocabulary Term oauth2 (i.e., "scheme": "oauth2"). For the code flow both authorization and token MUST be included. If no scopes are defined in the SecurityScheme then they are considered to be empty.

+

OAuth2SecurityScheme

OAuth2 authentication security configuration for systems conformant with [[!RFC6749]], [[!RFC8252]] and (for the device flow) [[!RFC8628]], identified by the Vocabulary Term oauth2 (i.e., "scheme": "oauth2"). +For the code flow both authorization and token MUST be included. +For the client flow both authorization and token MUST be included. +For the device flow both authorization and token MUST be included. +If an OAuth 2.0 flow other than code, client or device needs to be specified an extension vocabulary MUST be used. +This includes the password and implicit flows, which are no longer considered best practice. +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 scopes are defined in the SecurityScheme then they are considered to be empty.

Vocabulary termDescriptionAssignmentType
authorizationURI of the authorization server.optionalanyURI
-
Vocabulary termDescriptionAssignmentType
authorizationURI of the authorization server.optionalanyURI
tokenURI of the token server.optionalanyURI
refreshURI of the refresh server.optionalanyURI
scopesSet 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 OAuth2SecurityScheme active on that form.optionalstring or Array of string
flowAuthorization flow.mandatorystring (e.g., code)
+flowAuthorization flow.mandatorystring (e.g., code, client, or device) From 0615a649b71adf4e0cb1268c03d79b1769dcc833 Mon Sep 17 00:00:00 2001 From: Michael McCool Date: Mon, 13 Jul 2020 10:45:20 -0300 Subject: [PATCH 02/13] update ontology file --- ontology/wot-security.ttl | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ontology/wot-security.ttl b/ontology/wot-security.ttl index 2bfd41277..275d506ad 100644 --- a/ontology/wot-security.ttl +++ b/ontology/wot-security.ttl @@ -114,7 +114,7 @@ :OAuth2SecurityScheme rdf:type rdfs:Class, owl:Class ; rdfs:label "OAuth2SecurityScheme" ; rdfs:subClassOf :SecurityScheme ; - rdfs:comment "OAuth2 authentication security configuration for systems conformant with !RFC6749 and !RFC8252, identified by the term oauth2 (i.e., \"scheme\": \"oauth2\"). For the implicit flow authorization MUST be included. For the password and client flows token MUST be included. For the code flow both authorization and token MUST be included. If no scopes are defined in the SecurityScheme then they are considered to be empty."@en . + rdfs:comment "OAuth 2.0 authentication security configuration for systems conformant with [[!RFC6749]], [[!RFC8252]] and (for the device flow) [[!RFC8628]], identified by the Vocabulary Term oauth2 (i.e., \"scheme\": \"oauth2\"). For the code flow both authorization and token MUST be included. For the client flow both authorization and token MUST be included. For the device flow both authorization and token MUST be included. If an OAuth 2.0 flow other than code, client or device needs to be specified an extension vocabulary MUST be used. This includes the password and implicit flows, which are no longer considered best practice. 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 scopes are defined in the SecurityScheme then they are considered to be empty.

"@en . :PSKSecurityScheme rdf:type rdfs:Class, owl:Class ; rdfs:label "PSKSecurityScheme" ; From e7907e5a5060ffb798e93218c8dcdd8a9d2aec18 Mon Sep 17 00:00:00 2001 From: Michael McCool Date: Mon, 13 Jul 2020 10:52:57 -0300 Subject: [PATCH 03/13] update ontology rendering, OAuth 2.0 usage --- index.html | 6 +++--- index.template.html | 6 +++--- ontology/wotsec.html | 2 +- 3 files changed, 7 insertions(+), 7 deletions(-) diff --git a/index.html b/index.html index a8bb338b1..aefa92cb0 100644 --- a/index.html +++ b/index.html @@ -1359,13 +1359,13 @@

Security Vocabulary Definitions

nameName for query, header, or cookie parameters.optionalstring

APIKeySecurityScheme

API key authentication security configuration identified by the Vocabulary Term apikey (i.e., "scheme": "apikey"). This is for the case where the access token is opaque and is not using a standard token format.

Vocabulary termDescriptionAssignmentType
inSpecifies the location of security authentication information.with defaultstring (one of header, query, body, or cookie)
nameName for query, header, or cookie parameters.optionalstring
-

BearerSecurityScheme

Bearer Token [[!RFC6750]] security configuration identified by the Vocabulary Term bearer (i.e., "scheme": "bearer") for situations where bearer tokens are used independently of OAuth2. If the oauth2 scheme is specified it is not generally necessary to specify this scheme as well as it is implied. For format, the value jwt indicates conformance with [[!RFC7519]], jws indicates conformance with [[!RFC7797]], cwt indicates conformance with [[!RFC8392]], and jwe indicates conformance with [[!RFC7516]], with values for alg interpreted consistently with those standards. Other formats and algorithms for bearer tokens MAY be specified in vocabulary extensions.

+

BearerSecurityScheme

Bearer Token [[!RFC6750]] security configuration identified by the Vocabulary Term bearer (i.e., "scheme": "bearer") for situations where bearer tokens are used independently of OAuth 2.0. If the oauth2 scheme is specified it is not generally necessary to specify this scheme as well as it is implied. For format, the value jwt indicates conformance with [[!RFC7519]], jws indicates conformance with [[!RFC7797]], cwt indicates conformance with [[!RFC8392]], and jwe indicates conformance with [[!RFC7516]], with values for alg interpreted consistently with those standards. Other formats and algorithms for bearer tokens MAY be specified in vocabulary extensions.

Vocabulary termDescriptionAssignmentType
authorizationURI of the authorization server.optionalanyURI
Vocabulary termDescriptionAssignmentType
authorizationURI of the authorization server.optionalanyURI
algEncoding, encryption, or digest algorithm.with defaultstring (e.g., MD5, ES256, or ES512-256)
formatSpecifies format of security authentication information.with defaultstring (e.g., jwt, cwt, jwe, or jws)
inSpecifies the location of security authentication information.with defaultstring (one of header, query, body, or cookie)
nameName for query, header, or cookie parameters.optionalstring

PSKSecurityScheme

Pre-shared key authentication security configuration identified by the Vocabulary Term psk (i.e., "scheme": "psk").

Vocabulary termDescriptionAssignmentType
identityIdentifier providing information which can be used for selection or confirmation.optionalstring
-

OAuth2SecurityScheme

OAuth2 authentication security configuration for systems conformant with [[!RFC6749]], [[!RFC8252]] and (for the device flow) [[!RFC8628]], identified by the Vocabulary Term oauth2 (i.e., "scheme": "oauth2"). +

OAuth2SecurityScheme

OAuth 2.0 authentication security configuration for systems conformant with [[!RFC6749]], [[!RFC8252]] and (for the device flow) [[!RFC8628]], identified by the Vocabulary Term oauth2 (i.e., "scheme": "oauth2"). For the code flow both authorization and token MUST be included. For the client flow both authorization and token MUST be included. For the device flow both authorization and token MUST be included. @@ -2480,7 +2480,7 @@

securityDefinitions and security

- 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 Interaction Affordance in the case of W3C WoT). diff --git a/index.template.html b/index.template.html index 8acabac94..10a69be12 100644 --- a/index.template.html +++ b/index.template.html @@ -1308,13 +1308,13 @@

Security Vocabulary Definitions

nameName for query, header, or cookie parameters.optionalstring

APIKeySecurityScheme

API key authentication security configuration identified by the Vocabulary Term apikey (i.e., "scheme": "apikey"). This is for the case where the access token is opaque and is not using a standard token format.

Vocabulary termDescriptionAssignmentType
inSpecifies the location of security authentication information.with defaultstring (one of header, query, body, or cookie)
nameName for query, header, or cookie parameters.optionalstring
-

BearerSecurityScheme

Bearer Token [[!RFC6750]] security configuration identified by the Vocabulary Term bearer (i.e., "scheme": "bearer") for situations where bearer tokens are used independently of OAuth2. If the oauth2 scheme is specified it is not generally necessary to specify this scheme as well as it is implied. For format, the value jwt indicates conformance with [[!RFC7519]], jws indicates conformance with [[!RFC7797]], cwt indicates conformance with [[!RFC8392]], and jwe indicates conformance with [[!RFC7516]], with values for alg interpreted consistently with those standards. Other formats and algorithms for bearer tokens MAY be specified in vocabulary extensions.

+

BearerSecurityScheme

Bearer Token [[!RFC6750]] security configuration identified by the Vocabulary Term bearer (i.e., "scheme": "bearer") for situations where bearer tokens are used independently of OAuth 2.0. If the oauth2 scheme is specified it is not generally necessary to specify this scheme as well as it is implied. For format, the value jwt indicates conformance with [[!RFC7519]], jws indicates conformance with [[!RFC7797]], cwt indicates conformance with [[!RFC8392]], and jwe indicates conformance with [[!RFC7516]], with values for alg interpreted consistently with those standards. Other formats and algorithms for bearer tokens MAY be specified in vocabulary extensions.

Vocabulary termDescriptionAssignmentType
authorizationURI of the authorization server.optionalanyURI
Vocabulary termDescriptionAssignmentType
authorizationURI of the authorization server.optionalanyURI
algEncoding, encryption, or digest algorithm.with defaultstring (e.g., MD5, ES256, or ES512-256)
formatSpecifies format of security authentication information.with defaultstring (e.g., jwt, cwt, jwe, or jws)
inSpecifies the location of security authentication information.with defaultstring (one of header, query, body, or cookie)
nameName for query, header, or cookie parameters.optionalstring

PSKSecurityScheme

Pre-shared key authentication security configuration identified by the Vocabulary Term psk (i.e., "scheme": "psk").

Vocabulary termDescriptionAssignmentType
identityIdentifier providing information which can be used for selection or confirmation.optionalstring
-

OAuth2SecurityScheme

OAuth2 authentication security configuration for systems conformant with [[!RFC6749]], [[!RFC8252]] and (for the device flow) [[!RFC8628]], identified by the Vocabulary Term oauth2 (i.e., "scheme": "oauth2"). +

OAuth2SecurityScheme

OAuth 2.0 authentication security configuration for systems conformant with [[!RFC6749]], [[!RFC8252]] and (for the device flow) [[!RFC8628]], identified by the Vocabulary Term oauth2 (i.e., "scheme": "oauth2"). For the code flow both authorization and token MUST be included. For the client flow both authorization and token MUST be included. For the device flow both authorization and token MUST be included. @@ -2429,7 +2429,7 @@

securityDefinitions and security

- 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 Interaction Affordance in the case of W3C WoT). diff --git a/ontology/wotsec.html b/ontology/wotsec.html index a20325146..23e397865 100644 --- a/ontology/wotsec.html +++ b/ontology/wotsec.html @@ -40,7 +40,7 @@

Introduction

CertSecurityScheme

IRI: https://www.w3.org/2019/wot/security#CertSecurityScheme

Certificate-based asymmetric key security configuration conformant with X509V3 identified by the term cert (i.e., "scheme": "cert").
Sub-class ofwotsec:SecurityScheme
In the domain ofwotsec:identity

DigestSecurityScheme

IRI: https://www.w3.org/2019/wot/security#DigestSecurityScheme

Digest authentication security configuration identified by the term digest (i.e., "scheme": "digest"). This scheme is similar to basic authentication but with added features to avoid man-in-the-middle attacks.
Sub-class ofwotsec:SecurityScheme
In the domain ofwotsec:in
wotsec:name
wotsec:qop

NoSecurityScheme

IRI: https://www.w3.org/2019/wot/security#NoSecurityScheme

A security configuration corresponding to identified by the term nosec (i.e., "scheme": "nosec"), indicating there is no authentication or other mechanism required to access the resource.
Sub-class ofwotsec:SecurityScheme
-

OAuth2SecurityScheme

IRI: https://www.w3.org/2019/wot/security#OAuth2SecurityScheme

OAuth2 authentication security configuration for systems conformant with !RFC6749 and !RFC8252, identified by the term oauth2 (i.e., "scheme": "oauth2"). For the implicit flow authorization MUST be included. For the password and client flows token MUST be included. For the code flow both authorization and token MUST be included. If no scopes are defined in the SecurityScheme then they are considered to be empty.
Sub-class ofwotsec:SecurityScheme
In the domain ofwotsec:authorization
wotsec:flow
wotsec:refresh
wotsec:scopes
wotsec:token
+

OAuth2SecurityScheme

IRI: https://www.w3.org/2019/wot/security#OAuth2SecurityScheme

OAuth 2.0 authentication security configuration for systems conformant with [[!RFC6749]], [[!RFC8252]] and (for the device flow) [[!RFC8628]], identified by the Vocabulary Term oauth2 (i.e., "scheme": "oauth2"). For the code flow both authorization and token MUST be included. For the client flow both authorization and token MUST be included. For the device flow both authorization and token MUST be included. If an OAuth 2.0 flow other than code, client or device needs to be specified an extension vocabulary MUST be used. This includes the password and implicit flows, which are no longer considered best practice. 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 scopes are defined in the SecurityScheme then they are considered to be empty.

Sub-class ofwotsec:SecurityScheme
In the domain ofwotsec:authorization
wotsec:flow
wotsec:refresh
wotsec:scopes
wotsec:token

PSKSecurityScheme

IRI: https://www.w3.org/2019/wot/security#PSKSecurityScheme

Pre-shared key authentication security configuration identified by the term psk (i.e., "scheme": "psk").
Sub-class ofwotsec:SecurityScheme
In the domain ofwotsec:identity

PoPSecurityScheme

IRI: https://www.w3.org/2019/wot/security#PoPSecurityScheme

Proof-of-possession (PoP) token authentication security configuration identified by the term pop (i.e., "scheme": "pop"). Here jwt indicates conformance with !RFC7519, jws indicates conformance with !RFC7797, cwt indicates conformance with !RFC8392, and jwe indicates conformance with RFC7516, with values for alg interpreted consistently with those standards. Other formats and algorithms for PoP tokens MAY be specified in vocabulary extensions.
Sub-class ofwotsec:SecurityScheme
In the domain ofwotsec:alg
wotsec:authorization
wotsec:format
wotsec:in
wotsec:name

PublicSecurityScheme

IRI: https://www.w3.org/2019/wot/security#PublicSecurityScheme

Raw public key asymmetric key security configuration identified by the term public (i.e., "scheme": "public").
Sub-class ofwotsec:SecurityScheme
In the domain ofwotsec:identity
From b5dcfd9c3667f85e091157efccb3763ebc70ca4a Mon Sep 17 00:00:00 2001 From: Michael McCool Date: Mon, 27 Jul 2020 09:41:46 -0300 Subject: [PATCH 04/13] correct mandatory fields for flows --- index.html | 9 +++++++-- index.template.html | 9 +++++++-- ontology/wot-security.ttl | 2 +- 3 files changed, 15 insertions(+), 5 deletions(-) diff --git a/index.html b/index.html index aefa92cb0..ec3a72570 100644 --- a/index.html +++ b/index.html @@ -1367,8 +1367,13 @@

Security Vocabulary Definitions

PSKSecurityScheme

Pre-shared key authentication security configuration identified by the Vocabulary Term psk (i.e., "scheme": "psk").

Vocabulary termDescriptionAssignmentType
identityIdentifier providing information which can be used for selection or confirmation.optionalstring

OAuth2SecurityScheme

OAuth 2.0 authentication security configuration for systems conformant with [[!RFC6749]], [[!RFC8252]] and (for the device flow) [[!RFC8628]], identified by the Vocabulary Term oauth2 (i.e., "scheme": "oauth2"). For the code flow both authorization and token MUST be included. -For the client flow both authorization and token MUST be included. -For the device flow both authorization and token MUST be included. +For the client flow authorization MUST NOT be included. +For the client flow token MUST be included. +For the device flow both authorization and token MUST be included. +In the case of the device flow, the URI provided for the authorization value refers to the +device authorization endpoint [[!RFC8628]]. +If multiple flows are available (for example, multiple security schemes are given for a form) then only +one may be selected for use. If an OAuth 2.0 flow other than code, client or device needs to be specified an extension vocabulary MUST be used. This includes the password and implicit flows, which are no longer considered best practice. This also applies to flows that are similar at the protocol level but do diff --git a/index.template.html b/index.template.html index 10a69be12..7bf7c0053 100644 --- a/index.template.html +++ b/index.template.html @@ -1316,8 +1316,13 @@

Security Vocabulary Definitions

PSKSecurityScheme

Pre-shared key authentication security configuration identified by the Vocabulary Term psk (i.e., "scheme": "psk").

Vocabulary termDescriptionAssignmentType
identityIdentifier providing information which can be used for selection or confirmation.optionalstring

OAuth2SecurityScheme

OAuth 2.0 authentication security configuration for systems conformant with [[!RFC6749]], [[!RFC8252]] and (for the device flow) [[!RFC8628]], identified by the Vocabulary Term oauth2 (i.e., "scheme": "oauth2"). For the code flow both authorization and token MUST be included. -For the client flow both authorization and token MUST be included. -For the device flow both authorization and token MUST be included. +For the client flow authorization MUST NOT be included. +For the client flow token MUST be included. +For the device flow both authorization and token MUST be included. +In the case of the device flow, the URI provided for the authorization value refers to the +device authorization endpoint [[!RFC8628]]. +If multiple flows are available (for example, multiple security schemes are given for a form) then only +one may be selected for use. If an OAuth 2.0 flow other than code, client or device needs to be specified an extension vocabulary MUST be used. This includes the password and implicit flows, which are no longer considered best practice. This also applies to flows that are similar at the protocol level but do diff --git a/ontology/wot-security.ttl b/ontology/wot-security.ttl index 275d506ad..582bc45b7 100644 --- a/ontology/wot-security.ttl +++ b/ontology/wot-security.ttl @@ -114,7 +114,7 @@ :OAuth2SecurityScheme rdf:type rdfs:Class, owl:Class ; rdfs:label "OAuth2SecurityScheme" ; rdfs:subClassOf :SecurityScheme ; - rdfs:comment "OAuth 2.0 authentication security configuration for systems conformant with [[!RFC6749]], [[!RFC8252]] and (for the device flow) [[!RFC8628]], identified by the Vocabulary Term oauth2 (i.e., \"scheme\": \"oauth2\"). For the code flow both authorization and token MUST be included. For the client flow both authorization and token MUST be included. For the device flow both authorization and token MUST be included. If an OAuth 2.0 flow other than code, client or device needs to be specified an extension vocabulary MUST be used. This includes the password and implicit flows, which are no longer considered best practice. 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 scopes are defined in the SecurityScheme then they are considered to be empty.

"@en . + rdfs:comment "FIX - INCONSISTENT WITH BODY. OAuth 2.0 authentication security configuration for systems conformant with [[!RFC6749]], [[!RFC8252]] and (for the device flow) [[!RFC8628]], identified by the Vocabulary Term oauth2 (i.e., \"scheme\": \"oauth2\"). For the code flow both authorization and token MUST be included. For the client flow both authorization and token MUST be included. For the device flow both authorization and token MUST be included. If an OAuth 2.0 flow other than code, client or device needs to be specified an extension vocabulary MUST be used. This includes the password and implicit flows, which are no longer considered best practice. 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 scopes are defined in the SecurityScheme then they are considered to be empty.

"@en . :PSKSecurityScheme rdf:type rdfs:Class, owl:Class ; rdfs:label "PSKSecurityScheme" ; From 8c4156e7331a4bfe417d9edcc500a2969a363599 Mon Sep 17 00:00:00 2001 From: Michael McCool Date: Mon, 3 Aug 2020 09:36:24 -0300 Subject: [PATCH 05/13] edits --- index.html | 8 ++++---- index.template.html | 8 ++++---- ontology/wotsec.html | 2 +- 3 files changed, 9 insertions(+), 9 deletions(-) diff --git a/index.html b/index.html index ec3a72570..cd8d3123c 100644 --- a/index.html +++ b/index.html @@ -1367,15 +1367,15 @@

Security Vocabulary Definitions

PSKSecurityScheme

Pre-shared key authentication security configuration identified by the Vocabulary Term psk (i.e., "scheme": "psk").

Vocabulary termDescriptionAssignmentType
identityIdentifier providing information which can be used for selection or confirmation.optionalstring

OAuth2SecurityScheme

OAuth 2.0 authentication security configuration for systems conformant with [[!RFC6749]], [[!RFC8252]] and (for the device flow) [[!RFC8628]], identified by the Vocabulary Term oauth2 (i.e., "scheme": "oauth2"). For the code flow both authorization and token MUST be included. -For the client flow authorization MUST NOT be included. For the client flow token MUST be included. +For the client flow authorization MUST NOT be included. For the device flow both authorization and token MUST be included. In the case of the device flow, the URI provided for the authorization value refers to the device authorization endpoint [[!RFC8628]]. -If multiple flows are available (for example, multiple security schemes are given for a form) then only -one may be selected for use. +If multiple flows are available (for example, multiple security schemes are given for a Form) then only +one may be selected for use by a Consumer. If an OAuth 2.0 flow other than code, client or device needs to be specified an extension vocabulary MUST be used. -This includes the password and implicit flows, which are no longer considered best practice. +This includes the password and implicit 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. diff --git a/index.template.html b/index.template.html index 7bf7c0053..b7531e01a 100644 --- a/index.template.html +++ b/index.template.html @@ -1316,15 +1316,15 @@

Security Vocabulary Definitions

PSKSecurityScheme

Pre-shared key authentication security configuration identified by the Vocabulary Term psk (i.e., "scheme": "psk").

Vocabulary termDescriptionAssignmentType
identityIdentifier providing information which can be used for selection or confirmation.optionalstring

OAuth2SecurityScheme

OAuth 2.0 authentication security configuration for systems conformant with [[!RFC6749]], [[!RFC8252]] and (for the device flow) [[!RFC8628]], identified by the Vocabulary Term oauth2 (i.e., "scheme": "oauth2"). For the code flow both authorization and token MUST be included. -For the client flow authorization MUST NOT be included. For the client flow token MUST be included. +For the client flow authorization MUST NOT be included. For the device flow both authorization and token MUST be included. In the case of the device flow, the URI provided for the authorization value refers to the device authorization endpoint [[!RFC8628]]. -If multiple flows are available (for example, multiple security schemes are given for a form) then only -one may be selected for use. +If multiple flows are available (for example, multiple security schemes are given for a Form) then only +one may be selected for use by a Consumer. If an OAuth 2.0 flow other than code, client or device needs to be specified an extension vocabulary MUST be used. -This includes the password and implicit flows, which are no longer considered best practice. +This includes the password and implicit 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. diff --git a/ontology/wotsec.html b/ontology/wotsec.html index 23e397865..48ab5df4c 100644 --- a/ontology/wotsec.html +++ b/ontology/wotsec.html @@ -40,7 +40,7 @@

Introduction

CertSecurityScheme

IRI: https://www.w3.org/2019/wot/security#CertSecurityScheme

Certificate-based asymmetric key security configuration conformant with X509V3 identified by the term cert (i.e., "scheme": "cert").
Sub-class ofwotsec:SecurityScheme
In the domain ofwotsec:identity

DigestSecurityScheme

IRI: https://www.w3.org/2019/wot/security#DigestSecurityScheme

Digest authentication security configuration identified by the term digest (i.e., "scheme": "digest"). This scheme is similar to basic authentication but with added features to avoid man-in-the-middle attacks.
Sub-class ofwotsec:SecurityScheme
In the domain ofwotsec:in
wotsec:name
wotsec:qop

NoSecurityScheme

IRI: https://www.w3.org/2019/wot/security#NoSecurityScheme

A security configuration corresponding to identified by the term nosec (i.e., "scheme": "nosec"), indicating there is no authentication or other mechanism required to access the resource.
Sub-class ofwotsec:SecurityScheme
-

OAuth2SecurityScheme

IRI: https://www.w3.org/2019/wot/security#OAuth2SecurityScheme

OAuth 2.0 authentication security configuration for systems conformant with [[!RFC6749]], [[!RFC8252]] and (for the device flow) [[!RFC8628]], identified by the Vocabulary Term oauth2 (i.e., "scheme": "oauth2"). For the code flow both authorization and token MUST be included. For the client flow both authorization and token MUST be included. For the device flow both authorization and token MUST be included. If an OAuth 2.0 flow other than code, client or device needs to be specified an extension vocabulary MUST be used. This includes the password and implicit flows, which are no longer considered best practice. 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 scopes are defined in the SecurityScheme then they are considered to be empty.

Sub-class ofwotsec:SecurityScheme
In the domain ofwotsec:authorization
wotsec:flow
wotsec:refresh
wotsec:scopes
wotsec:token
+

OAuth2SecurityScheme

IRI: https://www.w3.org/2019/wot/security#OAuth2SecurityScheme

FIX - INCONSISTENT WITH BODY. OAuth 2.0 authentication security configuration for systems conformant with [[!RFC6749]], [[!RFC8252]] and (for the device flow) [[!RFC8628]], identified by the Vocabulary Term oauth2 (i.e., "scheme": "oauth2"). For the code flow both authorization and token MUST be included. For the client flow both authorization and token MUST be included. For the device flow both authorization and token MUST be included. If an OAuth 2.0 flow other than code, client or device needs to be specified an extension vocabulary MUST be used. This includes the password and implicit flows, which are no longer considered best practice. 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 scopes are defined in the SecurityScheme then they are considered to be empty.

Sub-class ofwotsec:SecurityScheme
In the domain ofwotsec:authorization
wotsec:flow
wotsec:refresh
wotsec:scopes
wotsec:token

PSKSecurityScheme

IRI: https://www.w3.org/2019/wot/security#PSKSecurityScheme

Pre-shared key authentication security configuration identified by the term psk (i.e., "scheme": "psk").
Sub-class ofwotsec:SecurityScheme
In the domain ofwotsec:identity

PoPSecurityScheme

IRI: https://www.w3.org/2019/wot/security#PoPSecurityScheme

Proof-of-possession (PoP) token authentication security configuration identified by the term pop (i.e., "scheme": "pop"). Here jwt indicates conformance with !RFC7519, jws indicates conformance with !RFC7797, cwt indicates conformance with !RFC8392, and jwe indicates conformance with RFC7516, with values for alg interpreted consistently with those standards. Other formats and algorithms for PoP tokens MAY be specified in vocabulary extensions.
Sub-class ofwotsec:SecurityScheme
In the domain ofwotsec:alg
wotsec:authorization
wotsec:format
wotsec:in
wotsec:name

PublicSecurityScheme

IRI: https://www.w3.org/2019/wot/security#PublicSecurityScheme

Raw public key asymmetric key security configuration identified by the term public (i.e., "scheme": "public").
Sub-class ofwotsec:SecurityScheme
In the domain ofwotsec:identity
From d3f873eeaa83acbdbb1577a35a1a981764b0646a Mon Sep 17 00:00:00 2001 From: Michael McCool Date: Mon, 3 Aug 2020 09:39:00 -0300 Subject: [PATCH 06/13] edits --- index.template.html | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/index.template.html b/index.template.html index b7531e01a..9ba6af54e 100644 --- a/index.template.html +++ b/index.template.html @@ -1319,8 +1319,6 @@

Security Vocabulary Definitions

For the client flow token MUST be included. For the client flow authorization MUST NOT be included. For the device flow both authorization and token MUST be included. -In the case of the device flow, the URI provided for the authorization value refers to the -device authorization endpoint [[!RFC8628]]. If multiple flows are available (for example, multiple security schemes are given for a Form) then only one may be selected for use by a Consumer. If an OAuth 2.0 flow other than code, client or device needs to be specified an extension vocabulary MUST be used. @@ -1328,7 +1326,9 @@

Security Vocabulary Definitions

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 scopes are defined in the SecurityScheme then they are considered to be empty.

+If no scopes are defined in the SecurityScheme then they are considered to be empty.

Vocabulary termDescriptionAssignmentType
authorizationURI of the authorization server.optionalanyURI
From 04d3ae8b6f456249615e8a4adf383e5cafe0b9ce Mon Sep 17 00:00:00 2001 From: Michael McCool Date: Mon, 3 Aug 2020 10:08:52 -0300 Subject: [PATCH 07/13] render --- index.html | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/index.html b/index.html index cd8d3123c..34bf56eed 100644 --- a/index.html +++ b/index.html @@ -1370,8 +1370,6 @@

Security Vocabulary Definitions

For the client flow token MUST be included. For the client flow authorization MUST NOT be included. For the device flow both authorization and token MUST be included. -In the case of the device flow, the URI provided for the authorization value refers to the -device authorization endpoint [[!RFC8628]]. If multiple flows are available (for example, multiple security schemes are given for a Form) then only one may be selected for use by a Consumer. If an OAuth 2.0 flow other than code, client or device needs to be specified an extension vocabulary MUST be used. @@ -1379,7 +1377,9 @@

Security Vocabulary Definitions

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 scopes are defined in the SecurityScheme then they are considered to be empty.

Vocabulary termDescriptionAssignmentType
authorizationURI of the authorization server. +In the case of the device flow, the URI provided for the authorization value refers to the device authorization endpoint [[!RFC8628]]. +optionalanyURI
tokenURI of the token server.optionalanyURI
refreshURI of the refresh server.optionalanyURI
scopesSet 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 OAuth2SecurityScheme active on that form.optionalstring or Array of string
+If no scopes are defined in the SecurityScheme then they are considered to be empty.

Vocabulary termDescriptionAssignmentType
authorizationURI of the authorization server.optionalanyURI
From a0fee1f6fa366967d454bccb8bdfe378ab8797d1 Mon Sep 17 00:00:00 2001 From: Michael McCool Date: Mon, 3 Aug 2020 10:19:26 -0300 Subject: [PATCH 08/13] add ed note --- index.html | 7 +++++-- index.template.html | 7 +++++-- 2 files changed, 10 insertions(+), 4 deletions(-) diff --git a/index.html b/index.html index 34bf56eed..59b371704 100644 --- a/index.html +++ b/index.html @@ -1370,14 +1370,17 @@

Security Vocabulary Definitions

For the client flow token MUST be included. For the client flow authorization MUST NOT be included. For the device flow both authorization and token MUST be included. -If multiple flows are available (for example, multiple security schemes are given for a Form) then only +If multiple flows are available (for example, multiple OAuth 2.0 security schemes with different flows are given for a Form) then only one may be selected for use by a Consumer. If an OAuth 2.0 flow other than code, client or device needs to be specified an extension vocabulary MUST be used. This includes the password and implicit 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 scopes are defined in the SecurityScheme then they are considered to be empty.

Vocabulary termDescriptionAssignmentType
authorizationURI of the authorization server. +In the case of the device flow, the URI provided for the authorization value refers to the device authorization endpoint [[!RFC8628]]. +optionalanyURI
tokenURI of the token server.optionalanyURI
refreshURI of the refresh server.optionalanyURI
scopesSet 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 OAuth2SecurityScheme active on that form.optionalstring or Array of string
Vocabulary termDescriptionAssignmentType
authorizationURI of the authorization server. +If no scopes are defined in the SecurityScheme then they are considered to be empty.

+

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 device 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 member, device_authorization, which MUST be included for the device flow (and then the regular auhtoriation endpoint then MUST NOT be used).

+ + diff --git a/index.template.html b/index.template.html index 9ba6af54e..cf45a194d 100644 --- a/index.template.html +++ b/index.template.html @@ -1319,14 +1319,17 @@

Security Vocabulary Definitions

For the client flow token MUST be included.For the client flow authorization MUST NOT be included.For the device flow both authorization and token MUST be included. -If multiple flows are available (for example, multiple security schemes are given for a Form) then only +If multiple flows are available (for example, multiple OAuth 2.0 security schemes with different flows are given for a Form) then only one may be selected for use by a Consumer. If an OAuth 2.0 flow other than code, client or device needs to be specified an extension vocabulary MUST be used. This includes the password and implicit 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 scopes are defined in the SecurityScheme then they are considered to be empty.

Vocabulary termDescriptionAssignmentType
authorizationURI of the authorization server. In the case of the device flow, the URI provided for the authorization value refers to the device authorization endpoint [[!RFC8628]]. optionalanyURI
tokenURI of the token server.optionalanyURI
Vocabulary termDescriptionAssignmentType
authorizationURI of the authorization server. +If no scopes are defined in the SecurityScheme then they are considered to be empty.

+

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 device 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 member, device_authorization, which MUST be included for the device flow (and then the regular auhtoriation endpoint then MUST NOT be used).

+ + From 75a49fb0e058ac4f8140c0a12b42e6b06f963a49 Mon Sep 17 00:00:00 2001 From: Michael McCool Date: Mon, 3 Aug 2020 10:23:00 -0300 Subject: [PATCH 09/13] fix typo --- index.html | 8 +++++++- index.template.html | 8 +++++++- 2 files changed, 14 insertions(+), 2 deletions(-) diff --git a/index.html b/index.html index 59b371704..b69e9999e 100644 --- a/index.html +++ b/index.html @@ -1378,7 +1378,13 @@

Security Vocabulary Definitions

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 scopes are defined in the SecurityScheme then they are considered to be empty.

-

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 device 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 member, device_authorization, which MUST be included for the device flow (and then the regular auhtoriation endpoint then MUST NOT be used).

+

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 device 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, +device_authorization, +which MUST be included for the device flow (and then the regular authorization endpoint then MUST NOT be used). +

Vocabulary termDescriptionAssignmentType
authorizationURI of the authorization server. In the case of the device flow, the URI provided for the authorization value refers to the device authorization endpoint [[!RFC8628]]. optionalanyURI
tokenURI of the token server.optionalanyURI
+
Vocabulary termDescriptionAssignmentType
authorizationURI of the authorization server. In the case of the device flow, the URI provided for the authorization value refers to the device authorization endpoint [[!RFC8628]]. diff --git a/index.template.html b/index.template.html index cf45a194d..d28e5b659 100644 --- a/index.template.html +++ b/index.template.html @@ -1327,7 +1327,13 @@

Security Vocabulary Definitions

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 scopes are defined in the SecurityScheme then they are considered to be empty.

-

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 device 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 member, device_authorization, which MUST be included for the device flow (and then the regular auhtoriation endpoint then MUST NOT be used).

+

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 device 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, +device_authorization, +which MUST be included for the device flow (and then the regular authorization endpoint then MUST NOT be used). +

+
Vocabulary termDescriptionAssignmentType
authorizationURI of the authorization server. In the case of the device flow, the URI provided for the authorization value refers to the device authorization endpoint [[!RFC8628]]. From e9bacd9a53bfd626b553398a9beb34971ecbfbb3 Mon Sep 17 00:00:00 2001 From: Michael McCool Date: Mon, 3 Aug 2020 10:35:02 -0300 Subject: [PATCH 10/13] add table --- index.html | 9 ++++++++- index.template.html | 9 ++++++++- 2 files changed, 16 insertions(+), 2 deletions(-) diff --git a/index.html b/index.html index b69e9999e..4504050b4 100644 --- a/index.html +++ b/index.html @@ -1370,7 +1370,14 @@

Security Vocabulary Definitions

For the client flow token MUST be included. For the client flow authorization MUST NOT be included. For the device flow both authorization and token MUST be included. -If multiple flows are available (for example, multiple OAuth 2.0 security schemes with different flows are given for a Form) then only +The required elements for each flow are summarized in the following table: + + + + +
Elementcodeclientdevice
authorizationrequiredomitrequired; refers to device authorization endpoint
tokenrequiredrequiredrequired
+

+

If multiple flows are available (for example, multiple OAuth 2.0 security schemes with different flows are given for a Form) then only one may be selected for use by a Consumer. If an OAuth 2.0 flow other than code, client or device needs to be specified an extension vocabulary MUST be used. This includes the password and implicit flows, which are no longer considered best practice [[WOT-SECURITY-GUIDELINES]]. diff --git a/index.template.html b/index.template.html index d28e5b659..b03d060ea 100644 --- a/index.template.html +++ b/index.template.html @@ -1319,7 +1319,14 @@

Security Vocabulary Definitions

For the client flow token MUST be included. For the client flow authorization MUST NOT be included. For the device flow both authorization and token MUST be included. -If multiple flows are available (for example, multiple OAuth 2.0 security schemes with different flows are given for a Form) then only +The required elements for each flow are summarized in the following table: + + + + +
Elementcodeclientdevice
authorizationrequiredomitrequired; refers to device authorization endpoint
tokenrequiredrequiredrequired
+

+

If multiple flows are available (for example, multiple OAuth 2.0 security schemes with different flows are given for a Form) then only one may be selected for use by a Consumer. If an OAuth 2.0 flow other than code, client or device needs to be specified an extension vocabulary MUST be used. This includes the password and implicit flows, which are no longer considered best practice [[WOT-SECURITY-GUIDELINES]]. From e8552ff9d63cdec8d4ffa0a9d4420637b4202833 Mon Sep 17 00:00:00 2001 From: Michael McCool Date: Mon, 3 Aug 2020 10:46:42 -0300 Subject: [PATCH 11/13] add ed note --- index.html | 16 ++++++++++++---- index.template.html | 16 ++++++++++++---- 2 files changed, 24 insertions(+), 8 deletions(-) diff --git a/index.html b/index.html index 4504050b4..34efc5f61 100644 --- a/index.html +++ b/index.html @@ -1370,13 +1370,21 @@

Security Vocabulary Definitions

For the client flow token MUST be included. For the client flow authorization MUST NOT be included. For the device flow both authorization and token MUST be included. -The required elements for each flow are summarized in the following table: - +In the case of the device flow +the value provided for authorization refers to the device authorization endpoint defined in [[!RFC8628]]. +The mandatory elements for each flow are summarized in the following table: +
- - + +
Elementcodeclientdevice
authorizationrequiredomitrequired; refers to device authorization endpoint
tokenrequiredrequiredrequired
authorizationmandatoryomitmandatory; refers to device authorization endpoint
tokenmandatorymandatorymandatory

+

+Note that the table below lists these elements as "optional". In fact whether they are mandatory or not depends on the flow. +The token 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. +

If multiple flows are available (for example, multiple OAuth 2.0 security schemes with different flows are given for a Form) then only one may be selected for use by a Consumer. If an OAuth 2.0 flow other than code, client or device needs to be specified an extension vocabulary MUST be used. diff --git a/index.template.html b/index.template.html index b03d060ea..e41002a7d 100644 --- a/index.template.html +++ b/index.template.html @@ -1319,13 +1319,21 @@

Security Vocabulary Definitions

For the client flow token MUST be included. For the client flow authorization MUST NOT be included. For the device flow both authorization and token MUST be included. -The required elements for each flow are summarized in the following table: - +In the case of the device flow +the value provided for authorization refers to the device authorization endpoint defined in [[!RFC8628]]. +The mandatory elements for each flow are summarized in the following table: +
- - + +
Elementcodeclientdevice
authorizationrequiredomitrequired; refers to device authorization endpoint
tokenrequiredrequiredrequired
authorizationmandatoryomitmandatory; refers to device authorization endpoint
tokenmandatorymandatorymandatory

+

+Note that the table below lists these elements as "optional". In fact whether they are mandatory or not depends on the flow. +The token 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. +

If multiple flows are available (for example, multiple OAuth 2.0 security schemes with different flows are given for a Form) then only one may be selected for use by a Consumer. If an OAuth 2.0 flow other than code, client or device needs to be specified an extension vocabulary MUST be used. From 0fdc5e5d2fef0279e7f4c400ac128b5fdb04358d Mon Sep 17 00:00:00 2001 From: Michael McCool Date: Mon, 3 Aug 2020 10:50:01 -0300 Subject: [PATCH 12/13] add refresh to table --- index.html | 1 + index.template.html | 1 + 2 files changed, 2 insertions(+) diff --git a/index.html b/index.html index 34efc5f61..be3404c87 100644 --- a/index.html +++ b/index.html @@ -1377,6 +1377,7 @@

Security Vocabulary Definitions

Elementcodeclientdevice
authorizationmandatoryomitmandatory; refers to device authorization endpoint
tokenmandatorymandatorymandatory
refreshoptionaloptionaloptional

diff --git a/index.template.html b/index.template.html index e41002a7d..1767f3f78 100644 --- a/index.template.html +++ b/index.template.html @@ -1326,6 +1326,7 @@

Security Vocabulary Definitions

Elementcodeclientdevice
authorizationmandatoryomitmandatory; refers to device authorization endpoint
tokenmandatorymandatorymandatory
refreshoptionaloptionaloptional

From b4f4228c607e0b0b494a5beeb6a3156b28d6bc03 Mon Sep 17 00:00:00 2001 From: Michael McCool Date: Mon, 10 Aug 2020 20:49:38 -0300 Subject: [PATCH 13/13] make comment in security ontology consistent with text --- ontology/wot-security.ttl | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ontology/wot-security.ttl b/ontology/wot-security.ttl index 582bc45b7..4eb66bc86 100644 --- a/ontology/wot-security.ttl +++ b/ontology/wot-security.ttl @@ -114,7 +114,7 @@ :OAuth2SecurityScheme rdf:type rdfs:Class, owl:Class ; rdfs:label "OAuth2SecurityScheme" ; rdfs:subClassOf :SecurityScheme ; - rdfs:comment "FIX - INCONSISTENT WITH BODY. OAuth 2.0 authentication security configuration for systems conformant with [[!RFC6749]], [[!RFC8252]] and (for the device flow) [[!RFC8628]], identified by the Vocabulary Term oauth2 (i.e., \"scheme\": \"oauth2\"). For the code flow both authorization and token MUST be included. For the client flow both authorization and token MUST be included. For the device flow both authorization and token MUST be included. If an OAuth 2.0 flow other than code, client or device needs to be specified an extension vocabulary MUST be used. This includes the password and implicit flows, which are no longer considered best practice. 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 scopes are defined in the SecurityScheme then they are considered to be empty.

"@en . + rdfs:comment "

OAuth 2.0 authentication security configuration for systems conformant with [[!RFC6749]], [[!RFC8252]] and (for the device flow) [[!RFC8628]], identified by the Vocabulary Term oauth2 (i.e., "scheme": "oauth2"). For the code flow both authorization and token MUST be included. For the client flow token MUST be included. For the client flow authorization MUST NOT be included. For the device flow both authorization and token MUST be included. In the case of the device flow the value provided for authorization refers to the device authorization endpoint defined in [[!RFC8628]]. The mandatory elements for each flow are summarized in the following table:
Elementcodeclientdevice
authorizationmandatoryomitmandatory; refers to device authorization endpoint
tokenmandatorymandatorymandatory
refreshoptionaloptionaloptional

Note that the table below lists these elements as "optional". In fact whether they are mandatory or not depends on the flow. The token 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.

If multiple flows are available (for example, multiple OAuth 2.0 security schemes with different flows are given for a Form) then only one may be selected for use by a Consumer. If an OAuth 2.0 flow other than code, client or device needs to be specified an extension vocabulary MUST be used. This includes the password and implicit 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 scopes are defined in the SecurityScheme then they are considered to be empty.

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 device 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, device_authorization, which MUST be included for the device flow (and then the regular authorization endpoint then MUST NOT be used).

"@en . :PSKSecurityScheme rdf:type rdfs:Class, owl:Class ; rdfs:label "PSKSecurityScheme" ;