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.

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

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.

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