This is required.

Validation of the document by the Working Group is expected by the end of June 2019.

Introduction

Axiomatization

Classes

APIKeySecurityScheme

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

API key authentication security configuration identified by the term 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 ofwotsec:SecurityScheme
In the domain ofwotsec:in
wotsec:name

BasicSecurityScheme

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

Basic authentication security configuration identified by the term 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 ofwotsec:SecurityScheme
In the domain ofwotsec:in
wotsec:name

BearerSecurityScheme

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

Bearer token authentication security configuration identified by the term 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 ofwotsec:SecurityScheme
In the domain ofwotsec:alg
wotsec:authorization
wotsec:format
wotsec:in
wotsec:name

ComboSecurityScheme

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. Exactly one of either oneOf or allOf MUST be included. Only security scheme definitions which can be used together can be combined with 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 ofwotsec:SecurityScheme
In the domain ofwotsec:allOf
wotsec:oneOf

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

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"). 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 ofwotsec:SecurityScheme
In the domain ofwotsec:identity

SecurityScheme

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:
The parameter will be given in a header provided by the protocol, with the name of the header provided by the value of name.
query:
The parameter will be appended to the URI as a query parameter, with the name of the query parameter provided by name.
body:
The parameter will be provided in the body of the request payload, with the data schema element used provided by name. If name is not given, it is assumed the entire body is to be used as the security parameter.
cookie:
The parameter is stored in a cookie identified by the value of name.
uri:
The parameter is embedded in the URI itself, which is encoded in the relevant interaction using a URI template variable defined by the value of 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.
If multiple parameters are needed for a security scheme, repeat the security scheme definition for each parameter and combine them using a 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.

Super-class ofwotsec:APIKeySecurityScheme
wotsec:BasicSecurityScheme
wotsec:BearerSecurityScheme
wotsec:ComboSecurityScheme
wotsec:DigestSecurityScheme
wotsec:NoSecurityScheme
wotsec:OAuth2SecurityScheme
wotsec:PSKSecurityScheme
In the domain ofwotsec:proxy

Object Properties

allOf

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

Array of two or more strings identifying other named security scheme definitions, all of which must be satisfied for access.
Domain includeswotsec:ComboSecurityScheme

authorization

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

URI of the authorization server.
Domain includeswotsec:BearerSecurityScheme
wotsec:OAuth2SecurityScheme

oneOf

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

Array of two or more strings identifying other named security scheme definitions, any one of which, when satisfied, will allow access. Only one may be chosen for use.
Domain includeswotsec:ComboSecurityScheme

proxy

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

URI of the proxy server this security configuration provides access to. If not given, the corresponding security configuration is for the endpoint.
This feature is at risk.
Domain includeswotsec:SecurityScheme

refresh

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

URI of the refresh server.
Domain includeswotsec:OAuth2SecurityScheme

token

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

URI of the token server.
Domain includeswotsec:OAuth2SecurityScheme

Datatype Properties

alg

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

Encoding, encryption, or digest algorithm.
Domain includeswotsec:BearerSecurityScheme

flow

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

Authorization flow.
Domain includeswotsec:OAuth2SecurityScheme

format

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

Specifies format of security authentication information.
Domain includeswotsec:BearerSecurityScheme
wotsec:PoPSecurityScheme

identity

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

Identifier providing information which can be used for selection or confirmation.
Domain includeswotsec:PSKSecurityScheme

in

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

Specifies the location of security authentication information.
Domain includeswotsec:APIKeySecurityScheme
wotsec:BasicSecurityScheme
wotsec:BearerSecurityScheme
wotsec:DigestSecurityScheme
wotsec:PoPSecurityScheme

name

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

Name for query, header, cookie, or uri parameters.
Domain includeswotsec:APIKeySecurityScheme
wotsec:BasicSecurityScheme
wotsec:BearerSecurityScheme
wotsec:DigestSecurityScheme
wotsec:PoPSecurityScheme

qop

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

Quality of protection.
This feature is at risk.
Domain includeswotsec:DigestSecurityScheme

scopes

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

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 OAuth2SecurityScheme active on that form.
This feature is at risk.
Domain includeswotsec:OAuth2SecurityScheme

Usage Examples

Extended Configuration