Security mechanisms for the Web of Things

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.

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.

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.

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.

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.

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.

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:

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

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.

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. When used in the context of a body security information location, the value of name MUST be in the form of a JSON pointer [[!RFC6901]] relative to the root of the input DataSchema for each interaction it is used with. Since this value is not a fragment identifier, and is not relative to the root of the TD but to whichever data schemas the security scheme is bound to, this value should not start with "#"; it is a "pure" JSON pointer. Since this value is not a fragment identifier, it also does not need to URL-encode special characters. The targeted element may or may not already exist at the specified location in the referenced data schema. If it does not, it will be inserted. This avoids having to duplicate definitions in the data schemas of every interaction. When an element of a data schema indicated by a JSON pointer indicated in a body locator does not already exist in the indicated schema, it MUST be possible to insert the indicated element at the location indicated by the pointer. The JSON pointer used in the body locator MAY use the "-" character to indicate a non-existent array element when it is necessary to insert an element after the last element of an existing array. The element referenced (or created) by a body security information location MUST be required and of type "string". 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.

The names of URI variables declared in a SecurityScheme MUST be distinct from all other URI variables declared in the TD.