Copyright © 2023 World Wide Web Consortium. W3C® liability, trademark and permissive document license rules apply.
This document introduces an RDF vocabulary for the security metadata definitions. This vocabulary provides a stable namespace IRI for security keywords, as well as simple axioms, defined against schema.org's meta-model. Examples on how to use the vocabulary are also introduced.
This section describes the status of this document at the time of its publication. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at https://www.w3.org/TR/.
This document was published by the Web of Things Working Group as an Editor's Draft.
Publication as an Editor's Draft does not imply endorsement by W3C and its Members.
This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.
This document was produced by a group operating under the W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.
This document is governed by the 03 November 2023 W3C Process Document.
This documents provides an ontology of a selection of well-established security mechanisms that are directly built into protocols eligible as Protocol Bindings for W3C WoT or are widely in use with those protocols. The current set of HTTP security schemes is partly based on OpenAPI 3.0.1 (see also [OPENAPI]). However while the HTTP security schemes, Vocabulary, and syntax given in this specification share many similarities with OpenAPI, they are not compatible.
Please note that the Turtle version of the ontology can be always obtained by doing content negotiation as explained in
Appendix D of the Thing Description Recommendation. You can
include Accept: text/turtle
in the request to
obtain the Turtle version of this ontology.
As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.
The key words MAY, MUST, MUST NOT, SHOULD, and SHOULD NOT in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.
The fundamental WoT terminology such as Thing, Consumer, Thing Description (TD), Interaction Model, Interaction Affordance, Property, Action, Event, Protocol Binding, Servient, etc. is defined in Section 3 of the WoT Architecture specification [WOT-ARCHITECTURE].
The Thing Description terminology such as TD Information Model, TD Document, Term (Vocabulary Term), TD Context Extension etc. is defined in Section 3 of the WoT Thing Description specification [WOT-THING-DESCRIPTION].
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#AutoSecurityScheme
auto
(i.e., "scheme":
"auto"
). This scheme indicates that the security
parameters are going to be negotiated by the underlying
protocols at runtime, subject to the respective
specifications for the protocol (e.g. [RFC8288] for Basic Authentication
when using HTTP).
Sub-class of | wotsec:SecurityScheme |
IRI:
https://www.w3.org/2019/wot/security#BasicSecurityScheme
basic
(i.e., "scheme":
"basic"
), using an unencrypted username and
password.
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. 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 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]
and [RFC8252], 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. The
mandatory elements for each flow are summarized in the
following table:
Element | code |
client |
---|---|---|
authorization |
mandatory | omit |
token |
mandatory | mandatory |
refresh |
optional | optional |
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 keys, passwords, or other sensitive information directly providing access MUST NOT be stored in the TD and should instead be shared and stored out-of-band via other mechanisms. 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.
Each security scheme object used in a TD defines a set of requirements to be met before access can be granted. We say a security scheme is satisfied when all its requirements are met. In some cases requirements from multiple security schemes will have to be met before access can be granted.
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
. 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.. For example, pointing to a key of a
Map where that key does not exist in the corresponding
Data Schema, the key and its value, which is the
credential, would be inserted to the Map at the specified
location during the operation execution. On the other
hand, pointing to an Array's item with a number as the
item index, that number should be outside the range of
the Array's already specified items in order to not alter
the strict sequence of items. 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
: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.auto
:auto
is set for the in
field of
a SecurityScheme
, then the name
field SHOULD NOT be set.
In this case, the application of the
SecurityScheme
is subject to the respective
specification for the given protocol (e.g.
[RFC8288]
when using the BasicSecurityScheme
with
HTTP).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#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#apikeyIn
Domain includes | wotsec:APIKeySecurityScheme |
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 |
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:BasicSecurityScheme wotsec:BearerSecurityScheme wotsec:DigestSecurityScheme |
IRI:
https://www.w3.org/2019/wot/security#name
Domain includes | wotsec:APIKeySecurityScheme wotsec:BasicSecurityScheme wotsec:BearerSecurityScheme wotsec:DigestSecurityScheme |
IRI:
https://www.w3.org/2019/wot/security#proxy
Domain includes | wotsec:SecurityScheme |
Range includes |
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 |
No AnnotationProperty found in the ontology.
Referenced in: