This is required.
Validation of the document by the Working Group is expected by the end of June 2019.
IRI: https://www.w3.org/2019/wot/security#APIKeySecurityScheme
apikey
(i.e., "scheme": "apikey"
). This scheme is to be used when the access token is opaque, for example when a key in a proprietary format is provided by a cloud service provider. In this case the key may not be using a standard token format. This scheme indicates that the key provided by the service provider needs to be supplied as part of service requests using the mechanism indicated by the "in"
field.Sub-class of | wotsec:SecurityScheme |
In the domain of | wotsec:in wotsec:name |
IRI: https://www.w3.org/2019/wot/security#BasicSecurityScheme
basic
(i.e., "scheme": "basic"
), using an unencrypted username and password. This scheme should be used with some other security mechanism providing confidentiality, for example, TLS.Sub-class of | wotsec:SecurityScheme |
In the domain of | wotsec:in wotsec:name |
IRI: https://www.w3.org/2019/wot/security#BearerSecurityScheme
bearer
(i.e., "scheme": "bearer"
). This scheme is intended 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.Sub-class of | wotsec:SecurityScheme |
In the domain of | wotsec:alg wotsec:authorization wotsec:format wotsec:in wotsec:name |
IRI: https://www.w3.org/2019/wot/security#ComboSecurityScheme
A combination of other security schemes identified by the Vocabulary Term combo
(i.e., "scheme": "combo"
). Elements of this scheme define various ways in which other named schemes defined in securityDefinitions
, including other ComboSecurityScheme
definitions, are to be combined to create a new scheme definition. oneOf
or allOf
MUST be included.allOf
. For example, it is not possible in general to combine different OAuth 2.0 flows together using allOf
unless one applies to a proxy and one to the endpoint. Note that when multiple named security scheme definitions are listed in a security
field the same semantics apply as in an allOf
combination (and the same limitations on allowable combinations). The oneOf
combination is equivalent to using different security schemes on forms that are otherwise identical. In this sense a oneOf
scheme is not an essential feature but it does avoid redundancy in such cases.
Sub-class of | wotsec:SecurityScheme |
In the domain of | wotsec:allOf wotsec:oneOf |
IRI: https://www.w3.org/2019/wot/security#DigestSecurityScheme
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 of | wotsec:SecurityScheme |
In the domain of | wotsec:in wotsec:name wotsec:qop |
IRI: https://www.w3.org/2019/wot/security#NoSecurityScheme
nosec
(i.e., "scheme": "nosec"
), indicating there is no authentication or other mechanism required to access the resource.Sub-class of | wotsec:SecurityScheme |
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 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:
Element | code | client | device |
---|---|---|---|
authorization | mandatory | omit | mandatory; refers to device authorization endpoint |
token | mandatory | mandatory | mandatory |
refresh | optional | optional | optional |
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).
Sub-class of | wotsec:SecurityScheme |
In the domain of | wotsec:authorization wotsec:flow wotsec:refresh wotsec:scopes wotsec:token |
IRI: https://www.w3.org/2019/wot/security#PSKSecurityScheme
psk
(i.e., "scheme": "psk"
). This is meant to identify that a standard is used for pre-shared keys such as TLS-PSK [[rfc4279]], and that the ciphersuite used for keys will be established during protocol negotiation.Sub-class of | wotsec:SecurityScheme |
In the domain of | wotsec:identity |
IRI: https://www.w3.org/2019/wot/security#SecurityScheme
Metadata describing the configuration of a security mechanism. The value assigned to the name scheme
MUST be defined within a Vocabulary included in the Thing Description, either in the standard Vocabulary defined in § 5. TD Information Model or in a TD Context Extension.
For all security schemes, any private keys, passwords, or other sensitive information directly providing access should be shared and stored out-of-band and MUST NOT be stored in the TD. The purpose of a TD is to describe how to access a Thing if and only if a Consumer already has authorization, and is not meant be used to grant that authorization.
Security schemes generally may require additional authentication parameters, such as a password or key. The location of this information is indicated by the value associated with the name in
, often in combination with the value associated with name
. The in
name can take one of the following values:
header
:name
.query
:name
.body
:name
. If name
is not given, it is assumed the entire body is to be used as the security parameter. cookie
:name
. uri
:name
. This is more general than the query
mechanism but more complex. The value uri
SHOULD be specified for in
in a security scheme only if query
is not applicable. The URIs provided in interactions where a security scheme using uri
MUST be a URI template including the defined variable.combo
security scheme and allOf
. In some cases parameters may not actually be secret but a user may wish to leave them out of the TD to help protect privacy. As an example of this, some security mechanisms require both a client identifier and a secret key. In theory, the client identifier is public however it may be hard to update and pose a tracking risk. In such a case it can be provided as an additional security parameter so it does not appear in the TD.The names of URI variables declared in a SecurityScheme
MUST be distinct from all other URI variables declared in the TD.
IRI: https://www.w3.org/2019/wot/security#allOf
Domain includes | wotsec:ComboSecurityScheme |
IRI: https://www.w3.org/2019/wot/security#oneOf
Domain includes | wotsec:ComboSecurityScheme |
IRI: https://www.w3.org/2019/wot/security#proxy
Domain includes | wotsec:SecurityScheme |
IRI: https://www.w3.org/2019/wot/security#refresh
Domain includes | wotsec:OAuth2SecurityScheme |
IRI: https://www.w3.org/2019/wot/security#token
Domain includes | wotsec:OAuth2SecurityScheme |
IRI: https://www.w3.org/2019/wot/security#alg
Domain includes | wotsec:BearerSecurityScheme |
IRI: https://www.w3.org/2019/wot/security#flow
Domain includes | wotsec:OAuth2SecurityScheme |
IRI: https://www.w3.org/2019/wot/security#format
Domain includes | wotsec:BearerSecurityScheme wotsec:PoPSecurityScheme |
IRI: https://www.w3.org/2019/wot/security#identity
Domain includes | wotsec:PSKSecurityScheme |
IRI: https://www.w3.org/2019/wot/security#in
Domain includes | wotsec:APIKeySecurityScheme wotsec:BasicSecurityScheme wotsec:BearerSecurityScheme wotsec:DigestSecurityScheme wotsec:PoPSecurityScheme |
IRI: https://www.w3.org/2019/wot/security#name
Domain includes | wotsec:APIKeySecurityScheme wotsec:BasicSecurityScheme wotsec:BearerSecurityScheme wotsec:DigestSecurityScheme wotsec:PoPSecurityScheme |
IRI: https://www.w3.org/2019/wot/security#qop
Domain includes | wotsec:DigestSecurityScheme |
IRI: https://www.w3.org/2019/wot/security#scopes
OAuth2SecurityScheme
active on that form. Domain includes | wotsec:OAuth2SecurityScheme |