Device Schema Extensions to the SCIM model
draft-shahzad-scim-device-model-02
The information below is for an old version of the document.
| Document | Type |
This is an older version of an Internet-Draft whose latest revision state is "Expired".
|
|
|---|---|---|---|
| Authors | Muhammad Shahzad , HASSAN IQBAL , Eliot Lear | ||
| Last updated | 2023-01-10 | ||
| RFC stream | (None) | ||
| Formats | |||
| Stream | Stream state | (No stream defined) | |
| Consensus boilerplate | Unknown | ||
| RFC Editor Note | (None) | ||
| IESG | IESG state | I-D Exists | |
| Telechat date | (None) | ||
| Responsible AD | (None) | ||
| Send notices to | (None) |
draft-shahzad-scim-device-model-02
Network Working Group M. Shahzad
Internet-Draft H. Iqbal
Intended status: Standards Track North Carolina State University
Expires: 14 July 2023 E. Lear
Cisco Systems
10 January 2023
Device Schema Extensions to the SCIM model
draft-shahzad-scim-device-model-02
Abstract
The initial core schema for SCIM (System for Cross Identity
Management) was designed for provisioning users. This memo specifies
schema extensions that enables provisioning of devices, using various
underlying bootstrapping systems, such as Wifi EasyConnect, RFC 8366
vouchers, and BLE passcodes.
Status of This Memo
This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet-
Drafts is at https://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress."
This Internet-Draft will expire on 14 July 2023.
Copyright Notice
Copyright (c) 2023 IETF Trust and the persons identified as the
document authors. All rights reserved.
Shahzad, et al. Expires 14 July 2023 [Page 1]
Internet-Draft SCIM Device Schema Extensions January 2023
This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents (https://trustee.ietf.org/
license-info) in effect on the date of publication of this document.
Please review these documents carefully, as they describe your rights
and restrictions with respect to this document. Code Components
extracted from this document must include Revised BSD License text as
described in Section 4.e of the Trust Legal Provisions and are
provided without warranty as described in the Revised BSD License.
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
1.1. Why SCIM for devices? . . . . . . . . . . . . . . . . . . 3
1.2. Protocol Participants . . . . . . . . . . . . . . . . . . 3
1.3. Schema Description . . . . . . . . . . . . . . . . . . . 4
1.4. Schema Representation . . . . . . . . . . . . . . . . . . 4
1.5. Terminology . . . . . . . . . . . . . . . . . . . . . . . 5
1.6. Device Grouping . . . . . . . . . . . . . . . . . . . . . 5
2. ResourceType Device . . . . . . . . . . . . . . . . . . . . . 5
3. SCIM Core Device Schema . . . . . . . . . . . . . . . . . . . 6
3.1. Common Attributes . . . . . . . . . . . . . . . . . . . . 6
3.2. Singular Attributes . . . . . . . . . . . . . . . . . . . 7
3.3. Device Schema JSON Representation . . . . . . . . . . . . 7
3.4. Device Object Example . . . . . . . . . . . . . . . . . . 9
4. SCIM Device Extensions . . . . . . . . . . . . . . . . . . . 9
4.1. BLE Extension . . . . . . . . . . . . . . . . . . . . . . 9
4.1.1. Singular Attributes . . . . . . . . . . . . . . . . . 9
4.1.2. Multivalued Attributes . . . . . . . . . . . . . . . 10
4.1.3. BLE Pairing Method Extensions . . . . . . . . . . . . 10
4.1.4. BLE Extension JSON Representation . . . . . . . . . . 11
4.1.5. BLE Device Object Example . . . . . . . . . . . . . . 14
4.2. DPP EasyConnect Extension . . . . . . . . . . . . . . . . 15
4.2.1. Singular Attributes . . . . . . . . . . . . . . . . . 16
4.2.2. Multivalued Attributes . . . . . . . . . . . . . . . 16
4.2.3. DPP Extension JSON Representation . . . . . . . . . . 16
4.2.4. DPP Device Object Example . . . . . . . . . . . . . . 18
4.3. Zigbee Extension . . . . . . . . . . . . . . . . . . . . 19
4.3.1. Singular Attribute . . . . . . . . . . . . . . . . . 19
4.3.2. Multivalued Attribute . . . . . . . . . . . . . . . . 19
4.3.3. Zigbee Extension JSON Representation . . . . . . . . 20
4.3.4. Zigbee Device Object Example . . . . . . . . . . . . 20
4.4. The Endpoint Applications Extension Schema . . . . . . . 21
4.4.1. "deviceControl" Complex Attribute . . . . . . . . . . 21
4.4.2. "dataReceiver" Complex Attribute . . . . . . . . . . 22
4.4.3. Endpoint Extension JSON Representation . . . . . . . 22
4.4.4. Endpoints Device Object Example . . . . . . . . . . . 24
5. Security Considerations . . . . . . . . . . . . . . . . . . . 26
6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 26
Shahzad, et al. Expires 14 July 2023 [Page 2]
Internet-Draft SCIM Device Schema Extensions January 2023
7. Changes from Earlier Versions . . . . . . . . . . . . . . . . 26
8. References . . . . . . . . . . . . . . . . . . . . . . . . . 26
8.1. Normative References . . . . . . . . . . . . . . . . . . 26
8.2. Informative References . . . . . . . . . . . . . . . . . 27
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 27
1. Introduction
The Internet of Things presents a management challenge in many
dimensions. One of them is the ability to onboard and manage large
number of devices. There are many models for bootstrapping trust
between devices and network deployments. Indeed it is expected that
different manufacturers will make use of different methods.
SCIM (System for Cross Identity Management) [RFC7643] [RFC7644]
defines a protocol and a schema for provisioning of users. However,
it can easily be extended to provision devices. The protocol and
core schema were designed to permit just such extensions. Bulk
operations are supported. This is good because often devices are
procured in bulk.
1.1. Why SCIM for devices?
Some might ask why SCIM is well suited for this purpose and not, for
example, NETCONF or RESTCONF with YANG. After all, there are all
sorts of existing models available. The answer is that the only
information being passed about the device is neither state nor device
configuration information, but only information necessary to
bootstrap trust so that the device may establish connectivity.
1.2. Protocol Participants
In the normal SCIM model, it was presumed that large federated
deployments would be SCIM clients who provision and remove employees
and contractors as they are enter and depart those deployments, and
federated services such as sales, payment, or conferencing services
would be the servers.
In the device model, the roles are reversed, and may be somewhat more
varied. A deployment network management system gateway (NMS gateway)
plays the role of the server, receiving information about devices
that are expected to be connected to its network. That server will
apply appropriate local policies regarding whether/how the device
should be connected.
The client may be one of a number of entities:
Shahzad, et al. Expires 14 July 2023 [Page 3]
Internet-Draft SCIM Device Schema Extensions January 2023
* A vendor who is authorized to add devices to a network as part of
a sales transaction. This is similar to the sales integration
sometimes envisioned by Bootstrapping Remote Key Infrastructure
(BRSKI) [RFC8995].
* A client application that administrators or employees use to add,
remove, or get information about devices. An example might be an
tablet or phone app that scans Easyconnect QR codes.
+-----------------------------------+
| |
+-----------+ Request | +---------+ |
| onboarding|------------->| SCIM | |
| app |<-------------| Server | |
+-----------+ Ctrl Endpt +---------+ |
| |
+-----------+ | +------------+ +-------+ |
| Control |...........|..| ALG |.........|device | |
| App | | +------------+ +-------+ |
+-----------+ | |
| |
+-----------------------------------+
Figure 1: Basic Architecture
In Figure 1, the onboarding app provides the device particulars. As
part of the response, the SCIM server might provide additional
information, especially in the case of non-IP devices, where an
application-layer gateway may need to be used to communicate with the
device. The control endpoint is one among a number of objects that
may be returned.
1.3. Schema Description
RFC 7643 does not prescribe a language to describe a schema. We have
chosen the JSON schema language [I-D.bhutton-json-schema] for this
purpose. This implies that use of XML for this device extension is
not supported.
Several additional schemas specify specific onboarding mechanisms,
such as BLE and Wifi Easy Connect.
1.4. Schema Representation
Attributes defined in the device core schema and extensions comprise
characteristics and SCIM datatypes defined in Sections 2.2 and 2.3 of
the [RFC7643]. This RFC does not define new characteristics and
datatypes for the SCIM attributes.
Shahzad, et al. Expires 14 July 2023 [Page 4]
Internet-Draft SCIM Device Schema Extensions January 2023
1.5. Terminology
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
"OPTIONAL" 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.
1.6. Device Grouping
Device grouping occurs using the core SCIM group object, as defined
in [RFC7643] Section 4.2.
2. ResourceType Device
This section defines a new resource type, 'Device'. The
"ResourceType" schema specifies the metadata about a resource type
(see section 6 of [RFC7643]). The resource "Devices" comprises a
core device schema and several extension schemas. The core schema
provides a minimal resource representation, whereas extension schemas
extend the core schema depending on the device's capability.
<CODE BEGINS>
[
{
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:ResourceType"],
"id": "Device",
"name": "Device",
"endpoint": "/Device",
"description": "Device Account",
"schema": "urn:ietf:params:scim:schemas:core:2.0:Device",
"schemaExtensions": [
{
"schema": "urn:ietf:params:scim:schemas:extension:ble:2.0:Device",
"required": false
},
{
"schema": "urn:ietf:params:scim:schemas:extension:dpp:2.0:Device",
"required": false
},
{
"schema": "urn:ietf:params:scim:schemas:extension:zigbee:2.0:Device",
"required": false
},
{
"schema": "urn:ietf:params:scim:schemas:extension:endpointApps:2.0:Device",
"required": false
},
Shahzad, et al. Expires 14 July 2023 [Page 5]
Internet-Draft SCIM Device Schema Extensions January 2023
{
"schema": "urn:ietf:params:scim:schemas:extension:pairingNull:2.0:Device",
"required": false
},
{
"schema": "urn:ietf:params:scim:schemas:extension:pairingJustWorks:2.0:Device",
"required": false
},
{
"schema": "urn:ietf:params:scim:schemas:extension:pairingPassKey:2.0:Device",
"required": false
},
{
"schema": "urn:ietf:params:scim:schemas:extension:pairingOOB:2.0:Device",
"required": false
}
],
"meta": {
"location": "https://example.com/v2/ResourceTypes/Device",
"resourceType": "ResourceType"
}
}
]
<CODE ENDS>
3. SCIM Core Device Schema
The core device schema provides the minimal representation of a
resource "Device". It contains only those attributes that any device
may need. Not all attributes are optional. The core schema for
"Device" is identified using the schema URI:
"urn:ietf:params:scim:schemas:core:2.0:Device". The following
attributes are defined in the device core schema, and details of
their characteristics are presented in Section 3.3.
3.1. Common Attributes
The Device schema contains three common attributes as defined in the
[RFC7643].
id
An id is a required and unique attribute of the device core schema
(see section 3.1 of [RFC7643]).
externalID
Shahzad, et al. Expires 14 July 2023 [Page 6]
Internet-Draft SCIM Device Schema Extensions January 2023
An externalID is an optional attribute (see section 3.1 of
[RFC7643]).
meta
Meta is a complex attribute and is required (see section 3.1 of
[RFC7643]).
3.2. Singular Attributes
deviceDisplayName
This is a human-readable device name suitable for displaying to end-
users. It is a mutable, non-unique, and not required string value.
For example, "BLE Heart Monitor".
adminState
This is a required mutable boolean value indicating the device's
administrative status. If this variable is set to True, then the
device is expected to be accessible. Note that the SCIM server may
apply whatever policy it may to establish and control this state.
mudUrl
A URL to the MUD file of the device. When present, the mudUrl may be
associated with this device, and used as described in [RFC8520].
3.3. Device Schema JSON Representation
Following is the JSON representation of the Device core schema.
Common attributes such as "id" and "externalID" are not presented
below.
Shahzad, et al. Expires 14 July 2023 [Page 7]
Internet-Draft SCIM Device Schema Extensions January 2023
<CODE BEGINS>
{
"id": "urn:ietf:params:scim:schemas:core:2.0:Device",
"name": "Device",
"description": "Device account",
"attributes" : [
{
"name": "deviceDisplayName",
"type": "string",
"description": "Human readable name of the device, suitable for displaying to end-users. For example, 'BLE Heart Monitor' etc.",
"multivalues": false,
"required": false,
"caseExact": true,
"mutability": "readWrite",
"returned": "default",
"uniqueness": "none"
},
{
"name": "adminState",
"type": "boolean",
"description": "A mutable boolean value indicating the device administrative status. If set TRUE, the commands (such as connect, disconnect, subscribe) that control app sends to the controller for the devices will be processeed by the controller. If set FALSE, any command comming from the control app for the device will be rejected by the controller.",
"multivalues": false,
"required": true,
"caseExact": false,
"mutability": "readWrite",
"returned": "default",
"uniqueness": "none"
},
{
"name": "mudUrl",
"type": "reference",
"description": "A URL to MUD file of the device (RFC 8520). It is added for future use. Current usage is not defined yet.",
"multivalues": false,
"required": false,
"caseExact": true,
"mutability": "readWrite",
"returned": "default",
"uniqueness": "none"
}
],
"meta" : {
"resourceType" : "Schema",
"location" :
"/v2/Schemas/urn:ietf:params:scim:schemas:core:2.0:Device"
}
}
<CODE ENDS>
Shahzad, et al. Expires 14 July 2023 [Page 8]
Internet-Draft SCIM Device Schema Extensions January 2023
3.4. Device Object Example
Following is the minimal example of a device object that does not
contain any extension representing the device's communication
capability.
<CODE BEGINS>
{
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:Device"],
"id": "e9e30dba-f08f-4109-8486-d5c6a3316111",
"deviceDisplayName": "BLE Heart Monitor",
"adminState": true,
"meta": {
"resourceType": "Device",
"created": "2022-01-23T04:56:22Z",
"lastModified": "2022-05-13T04:42:34Z",
"version": "W\/\"a330bc54f0671c9\"",
"location": "https://example.com/v2/Device/e9e30dba-f08f-4109-8486-d5c6a3316111"
}
}
<CODE ENDS>
4. SCIM Device Extensions
This section presents various extension schemas, their attributes,
JSON representation, and example object. These schemas extend the
core device schema based on the device's capability (communication
stack). This RFC presents an additional hierarchical level by
introducing extensions within an extension. See below for more
details.
[[ DISCUSS: Is this okay with the working group? ]]
4.1. BLE Extension
This schema extends the device schema to represent the devices
supporting BLE. The attributes are as follows:
4.1.1. Singular Attributes
deviceMacAddress
this is the public MAC address assigned by the manufacturer. It is a
unique 48-bit value. The regex pattern is the following:
^[0-9A-Fa-f]{2}(:[0-9A-Fa-f]{2}){5}
addressType
Shahzad, et al. Expires 14 July 2023 [Page 9]
Internet-Draft SCIM Device Schema Extensions January 2023
This flag is taken from the BLE core specification, 5.3. If FALSE,
the device is using a public MAC address. If TRUE, the device uses a
Random address resolved using IRK.
irk
Identity resolving key, which is unique for every device. It is used
to resolve the random address.
4.1.2. Multivalued Attributes
versionSupport
This field provides an array of all the BLE versions supported by the
device. For example, [4.1, 4.2, 5.0, 5.1, 5.2, 5.3].
pairingMethods
This attribute is the array of pairing methods associated with the
BLE device. The pairing methods may require sub-attributes, such as
key/password, for the device pairing process. To enable the
scalability of pairing methods in the future, they are represented as
extensions to incorporate various attributes that are part of the
respective pairing process. Pairing method extensions are nested
inside the BLE extension.
4.1.3. BLE Pairing Method Extensions
The details on pairing methods and their associated attributes are in
section 2.3 of [BLE53]. This memo defines extensions for four
pairing methods that are nested insided the BLE extension schema.
They are as follows.
urn:ietf:params:scim:schemas:extension:pairingNull:2.0:Device
This extension does not have any attribute. It allows pairing for
BLE devices that do not require a pairing method.
urn:ietf:params:scim:schemas:extension:pairingJustWorks:2.0:Device
Just works pairing method does not require a key to pair devices.
For completeness, the key value is set to 'null'.
urn:ietf:params:scim:schemas:extension:pairingPassKey:2.0:Device
The pass key pairing method requires a 6-digit key to pair devices.
This extension has one singular attribute, "key". The key pattern is
as follows:
Shahzad, et al. Expires 14 July 2023 [Page 10]
Internet-Draft SCIM Device Schema Extensions January 2023
^[0-9]{6}$
urn:ietf:params:scim:schemas:extension:pairingOOB:2.0:Device
The out-of-band pairing method includes three singular attributes,
i.e., key, randomNumber, and confirmationNumber. The key value is
required and received from out-of-bond sources such as NFC.
randomNumber is also a required attribute which is nounce added to
the key. confirmationNumber is a non-required attribute, which some
solutions require in RESTful message exchange.
4.1.4. BLE Extension JSON Representation
<CODE BEGINS>
[
{
"id": "urn:ietf:params:scim:schemas:extension:ble:2.0:Device",
"name": "bleExtension",
"description": "Ble extension for device account",
"attributes" : [
{
"name": "versionSupport",
"type": "string",
"description": "Provides a list of all the BLE versions supported by the device. For example, [4.1, 4.2, 5.0, 5.1, 5.2, 5.3].",
"multivalues": true,
"required": true,
"caseExact": false,
"mutability": "readWrite",
"returned": "default",
"uniqueness": "none"
},
{
"name": "deviceMacAddress",
"type": "string",
"description": "It is the public MAC address assigned by the manufacturer. It is unique 48 bit value. The regex pattern is ^[0-9A-Fa-f]{2}(:[0-9A-Fa-f]{2}){5}.",
"multivalues": false,
"required": true,
"caseExact": false,
"mutability": "readWrite",
"returned": "default",
"uniqueness": "Manufacturer"
},
{
"name": "addressType",
"type": "boolean",
"description": "AddressType flag is taken from the BLE core specifications 5.3. If FALSE, the device is using public MAC address. If TRUE, device is using Random address which is resolved using IRK.",
"multivalues": false,
"required": true,
Shahzad, et al. Expires 14 July 2023 [Page 11]
Internet-Draft SCIM Device Schema Extensions January 2023
"caseExact": false,
"mutability": "readWrite",
"returned": "default",
"uniqueness": "none"
},
{
"name": "irk",
"type": "string",
"description": "Identity resolving key, which is unique for every device. It is used to resolve random address.",
"multivalues": false,
"required": false,
"caseExact": false,
"mutability": "readWrite",
"returned": "default",
"uniqueness": "Manufacturer"
},
{
"name": "pairingMethods",
"type": "string",
"description": "List of pairing methods associated with the ble device, stored as schema URI.",
"multivalues": true,
"required": true,
"caseExact": true,
"mutability": "readWrite",
"returned": "default",
"uniqueness": "none"
}
],
"meta" : {
"resourceType" : "Schema",
"location" : "/v2/Schemas/urn:ietf:params:scim:schemas:extension:ble:2.0:Device"
}
},
{
"id": "urn:ietf:params:scim:schemas:extension:pairingNull:2.0:Device",
"name": "nullPairing",
"description": "Null pairing method for ble. It is included for the devices that do not have a pairing method.",
"meta" : {
"resourceType" : "Schema",
"location" : "/v2/Schemas/urn:ietf:params:scim:schemas:extension:pairingNull:2.0:Device"
}
},
{
"id": "urn:ietf:params:scim:schemas:extension:pairingJustWorks:2.0:Device",
"name": "pairingJustWorks",
"description": "Just works pairing method for ble.",
"attributes" : [
{
Shahzad, et al. Expires 14 July 2023 [Page 12]
Internet-Draft SCIM Device Schema Extensions January 2023
"name": "key",
"type": "integer",
"description": "Just works does not have any key value. For completeness, it is added with a key value 'null'.",
"multivalues": false,
"required": true,
"caseExact": false,
"mutability": "readWrite",
"returned": "default",
"uniqueness": "none"
}
],
"meta" : {
"resourceType" : "Schema",
"location" : "/v2/Schemas/urn:ietf:params:scim:schemas:extension:pairingJustWorks:2.0:Device"
}
},
{
"id": "urn:ietf:params:scim:schemas:extension:pairingPassKey:2.0:Device",
"name": "pairingPassKey",
"description": "Pass key pairing method for ble.",
"attributes" : [
{
"name": "key",
"type": "integer",
"description": "A six digit passkey for ble device. The pattern of key is ^[0-9]{6}$.",
"multivalues": false,
"required": true,
"caseExact": false,
"mutability": "readWrite",
"returned": "default",
"uniqueness": "none"
}
],
"meta" : {
"resourceType" : "Schema",
"location" : "/v2/Schemas/urn:ietf:params:scim:schemas:extension:pairingPassKey:2.0:Device"
}
},
{
"id": "urn:ietf:params:scim:schemas:extension:pairingOOB:2.0:Device",
"name": "pairingOOB",
"description": "Pass key pairing method for ble.",
"attributes" : [
{
"name": "key",
"type": "string",
"description": "A key value retrieved from out of band source such as NFC.",
"multivalues": false,
Shahzad, et al. Expires 14 July 2023 [Page 13]
Internet-Draft SCIM Device Schema Extensions January 2023
"required": true,
"caseExact": true,
"mutability": "readWrite",
"returned": "default",
"uniqueness": "none"
},
{
"name": "randomNumber",
"type": "integer",
"description": "Nonce added to the key.",
"multivalues": false,
"required": true,
"caseExact": false,
"mutability": "readWrite",
"returned": "default",
"uniqueness": "none"
},
{
"name": "confirmationNumber",
"type": "integer",
"description": "Some solutions require confirmation number in RESTful message exchange.",
"multivalues": false,
"required": false,
"caseExact": false,
"mutability": "readWrite",
"returned": "default",
"uniqueness": "none"
}
],
"meta" : {
"resourceType" : "Schema",
"location" : "/v2/Schemas/urn:ietf:params:scim:schemas:extension:pairingOOB:2.0:Device"
}
}
]
<CODE ENDS>
4.1.5. BLE Device Object Example
Shahzad, et al. Expires 14 July 2023 [Page 14]
Internet-Draft SCIM Device Schema Extensions January 2023
<CODE BEGINS>
{
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:Device",
"urn:ietf:params:scim:schemas:extension:ble:2.0:Device"],
"id": "e9e30dba-f08f-4109-8486-d5c6a3316111",
"deviceDisplayName": "BLE Heart Monitor",
"adminState": true,
"urn:ietf:params:scim:schemas:extension:ble:2.0:Device" : {
"versionSupport": ["5.3"],
"deviceMacAddress": "2C:54:91:88:C9:E2",
"addressType": false,
"pairingMethods": ["urn:ietf:params:scim:schemas:extension:pairingNull:2.0:Device",
"urn:ietf:params:scim:schemas:extension:pairingJustWorks:2.0:Device",
"urn:ietf:params:scim:schemas:extension:pairingPassKey:2.0:Device",
"urn:ietf:params:scim:schemas:extension:pairingOOB:2.0:Device"],
"urn:ietf:params:scim:schemas:extension:pairingNull:2.0:Device": null,
"urn:ietf:params:scim:schemas:extension:pairingJustWorks:2.0:Device": {
"key": null
},
"urn:ietf:params:scim:schemas:extension:pairingPassKey:2.0:Device" : {
"key": 123456
},
"urn:ietf:params:scim:schemas:extension:pairingOOB:2.0:Device": {
"key": "TheKeyvalueRetrievedFromOOB",
"randNumber": 238796813516896
}
},
"meta": {
"resourceType": "Device",
"created": "2022-01-23T04:56:22Z",
"lastModified": "2022-05-13T04:42:34Z",
"version": "W\/\"a330bc54f0671c9\"",
"location": "https://example.com/v2/Device/e9e30dba-f08f-4109-8486-d5c6a3316111"
}
}
<CODE ENDS>
4.2. DPP EasyConnect Extension
This schema extends the device schema to enable WiFi EasyConnect
(otherwise known as Device Provisioning Protocol). The attributes in
this extension are adopted from [DPP2]. The attributes are as
follows:
Shahzad, et al. Expires 14 July 2023 [Page 15]
Internet-Draft SCIM Device Schema Extensions January 2023
4.2.1. Singular Attributes
dppVersion This attribute represents the version of DPP the device
supports.
bootstrapKey
This key is Elliptic-Curve Diffie-Hellman (ECDH) public key. The
base64 encoded lengths for P-256, P-384, and P-521 are 80, 96, and
120 characters.
deviceMacAddress
The manufacturer assigns the MAC address. It is a unique 48-bit
value. The regex pattern is as follows:
^[0-9A-Fa-f]{2}(:[0-9A-Fa-f]{2}){5}.
serialNumber
An alphanumeric serial number may also be passed as bootstrapping
information.
4.2.2. Multivalued Attributes
bootstrappingMethod
It is the array of all the bootstrapping methods available on the
enrollee device. For example, [QR, NFC].
classChannel
This attribute is an array of global operating class and channel
shared as bootstrapping information. It is formatted as class/
channel. For example, ['81/1','115/36'].
4.2.3. DPP Extension JSON Representation
<CODE BEGINS>
{
"id": "urn:ietf:params:scim:schemas:extension:dpp:2.0:Device",
"name": "dppExtension",
"description": "Device extension schema for DPP",
"attributes" : [
{
"name": "dppVersion",
"type": "integer",
"description": "Version of DPP this device supports.",
Shahzad, et al. Expires 14 July 2023 [Page 16]
Internet-Draft SCIM Device Schema Extensions January 2023
"multivalues": false,
"required": true,
"caseExact": false,
"mutability": "readWrite",
"returned": "default",
"uniqueness": "none"
},
{
"name": "bootstrappingMethod",
"type": "string",
"description": "The list of all the bootstrapping methods available on the enrollee device. For example, [QR, NFC].",
"multivalues": true,
"required": false,
"caseExact": false,
"mutability": "readWrite",
"returned": "default",
"uniqueness": "none"
},
{
"name": "bootstrapKey",
"type": "string",
"description": "This key is Elliptic-Curve Diffie–Hellman (ECDH) public key. The base64 encoded length for P-256, P-384, and P-521 is 80, 96, and 120 characters.",
"multivalues": false,
"required": true,
"caseExact": true,
"mutability": "readWrite",
"returned": "default",
"uniqueness": "none"
},
{
"name": "deviceMacAddress",
"type": "string",
"description": "The MAC address assigned by the manufacturer. It is unique 48 bit value. The regex pattern is ^[0-9A-Fa-f]{2}(:[0-9A-Fa-f]{2}){5}.",
"multivalues": false,
"required": false,
"caseExact": false,
"mutability": "readWrite",
"returned": "default",
"uniqueness": "Manufacturer"
},
{
"name": "classChannel",
"type": "string",
"description": "A list of global operating class and channel shared as bootstrapping information. It is formatted as class/channel. For example, '81/1', '115/36'.",
"multivalues": true,
"required": false,
"caseExact": false,
"mutability": "readWrite",
Shahzad, et al. Expires 14 July 2023 [Page 17]
Internet-Draft SCIM Device Schema Extensions January 2023
"returned": "default",
"uniqueness": "none"
},
{
"name": "serialNumber",
"type": "string",
"description": "An alphanumeric serial number that may also be passed as bootstrapping information.",
"multivalues": false,
"required": false,
"caseExact": false,
"mutability": "readWrite",
"returned": "default",
"uniqueness": "none"
}
],
"meta" : {
"resourceType" : "Schema",
"location" : "/v2/Schemas/urn:ietf:params:scim:schemas:extension:dpp:2.0:Device"
}
}
<CODE ENDS>
4.2.4. DPP Device Object Example
Shahzad, et al. Expires 14 July 2023 [Page 18]
Internet-Draft SCIM Device Schema Extensions January 2023
<CODE BEGINS>
{
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:Device",
"urn:ietf:params:scim:schemas:extension:dpp:2.0:Device"],
"id": "e9e30dba-f08f-4109-8486-d5c6a3316111",
"displayName": "WiFi Heart Monitor",
"adminState": true,
"urn:ietf:params:scim:schemas:extension:dpp:2.0:Device" : {
"versionSupport": ["802.11ax"],
"bootstrappingMethod": ["QR"],
"bootstrapKey": "MDkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDIgADURzxmttZoIRIPWGoQMV00XHWCAQIhXruVWOz0NjlkIA=",
"deviceMacAddress": "2C:54:91:88:C9:F2",
"classChannel": ["81/1", "115/36"],
"serialNumber": "4774LH2b4044"
},
"meta": {
"resourceType": "Device",
"created": "2022-01-23T04:56:22Z",
"lastModified": "2022-05-13T04:42:34Z",
"version": "W\/\"a330bc54f0671c9\"",
"location": "https://example.com/v2/Device/e9e30dba-f08f-4109-8486-d5c6a3316111"
}
}
<CODE ENDS>
4.3. Zigbee Extension
This schema extends the device schema to enable the provisioning of
Zigbee devices. It has one singular attribute and one multivalued
attribute. The attributes are as follows:
4.3.1. Singular Attribute
deviceEui64Address
this attribute is an EUI-64 (Extended Unique Identifier) device
address. The regex pattern is as follows:
^[0-9A-Fa-f]{16}$
4.3.2. Multivalued Attribute
versionSupport
This attribute provides an array of all the Zigbee versions supported
by the device. For example, [3.0].
Shahzad, et al. Expires 14 July 2023 [Page 19]
Internet-Draft SCIM Device Schema Extensions January 2023
4.3.3. Zigbee Extension JSON Representation
<CODE BEGINS>
{
"id": "urn:ietf:params:scim:schemas:extension:zigbee:2.0:Device",
"name": "zigbeeExtension",
"description": "Device extension schema for zigbee.",
"attributes" : [
{
"name": "versionSupport",
"type": "string",
"description": "Provides a list of all the zigbee versions supported by the device. For example, [3.0].",
"multivalues": true,
"required": true,
"caseExact": false,
"mutability": "readWrite",
"returned": "default",
"uniqueness": "none"
},
{
"name": "deviceEui64Address",
"type": "string",
"description": "The EUI-64 (Extended Unique Identifier) device address. The regex pattern is ^[0-9A-Fa-f]{16}$.",
"multivalues": false,
"required": true,
"caseExact": false,
"mutability": "readWrite",
"returned": "default",
"uniqueness": "none"
}
],
"meta" : {
"resourceType" : "Schema",
"location" : "/v2/Schemas/urn:ietf:params:scim:schemas:extension:zigbee:2.0:Device"
}
}
<CODE ENDS>
4.3.4. Zigbee Device Object Example
Shahzad, et al. Expires 14 July 2023 [Page 20]
Internet-Draft SCIM Device Schema Extensions January 2023
<CODE BEGINS>
{
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:Device",
"urn:ietf:params:scim:schemas:extension:zigbee:2.0:Device"],
"id": "e9e30dba-f08f-4109-8486-d5c6a3316111",
"displayName": "Zigbee Heart Monitor",
"adminState": true,
"urn:ietf:params:scim:schemas:extension:zigbee:2.0:Device" : {
"versionSupport": ["3.0"],
"deviceEui64Address": "50325FFFFEE76728"
},
"meta": {
"resourceType": "Device",
"created": "2022-01-23T04:56:22Z",
"lastModified": "2022-05-13T04:42:34Z",
"version": "W\/\"a330bc54f0671c9\"",
"location": "https://example.com/v2/Device/e9e30dba-f08f-4109-8486-d5c6a3316111"
}
}
<CODE ENDS>
4.4. The Endpoint Applications Extension Schema
Sometimes non-IP devices such as those using BLE or Zigbe require an
application gateway interface to manage them. SCIM clients MUST NOT
specify this to describe native IP-based devices.
The device schema is a base schema upon which specific onboarding
technology schemas are built. This extension provides two complex
attributes deviceControl, and dataReceiver to represent two types of
partner endpoint applications, device control, and data receiver
applications, respectively. These complex attributes and their
respective sub-attributes are as follows:
4.4.1. "deviceControl" Complex Attribute
This complex attribute represents the application responsible for
controlling the device. Device control applications provide access
control for the device. It determines which other applications can
access the data from the device. Depending on the use case, there
can be more than one device control application.
"deviceControl" has two attributes: i) a multvalued client-tokens
attribute" and ii) a singular attribute called "enterpriseEndpoint".
Their details are as follows:
Shahzad, et al. Expires 14 July 2023 [Page 21]
Internet-Draft SCIM Device Schema Extensions January 2023
client-tokens
This attribute contains a list of tokens that the client will used to
authenticate itself. Each token may be a string up to 500 characters
in length.
[[ We probably need something better here. ]]
enterpriseEndpoint
Device control apps use the URL of the enterprise endpoint to reach
the network gateway. When the enterprise receives the SCIM object
from the onboarding app, it adds this attribute to it and sends it
back as a response to the onboarding app.
4.4.2. "dataReceiver" Complex Attribute
This complex attribute represents the application that receives data
from the device. Depending on the use case, there can be more than
one data receiver application.
"dataReceiver" has two attributes:
1. a multi-valued attribute called "client-tokens".
2. a singular attribute called "enterpriseEndpoint".
The complex attribute "apps" provides the URLs and root certificates
of the respective data receiver applications in an array. Their
details are as follows:
client-tokens
This attribute contains a list of tokens that the client will used to
authenticate itself. Each token may be a string up to 500 characters
in length.
[[ We probably need something better here. ]]
enterpriseEndpoint
Data receiver apps use the URL of the enterprise endpoint to reach
the network gateway. When the enterprise receives the SCIM object
from the onboarding app, it adds this attribute to it and sends it
back as a response to the onboarding app.
4.4.3. Endpoint Extension JSON Representation
Shahzad, et al. Expires 14 July 2023 [Page 22]
Internet-Draft SCIM Device Schema Extensions January 2023
<CODE BEGINS>
{
"id": "urn:ietf:params:scim:schemas:extension:endpointApps:2.0:Device",
"name": "endpointApps",
"description": "Extension for partner endpoint applications that can onboard, control, and communicate with the device.",
"attributes" : [
{
"name": "deviceControl",
"type": "complex",
"description": "Device control application attributes.",
"multivalues": false,
"required": true,
"caseExact": false,
"mutability": "readWrite",
"returned": "default",
"uniqueness": "none",
"subAttributes" : [
{
"name": "client-tokens",
"type": "reference",
"description": "The URL of the device control application which can be used to access the app. This attribute is provided by the onboarding application when it creates the SCIM object for the device.",
"multivalues": true,
"required": true,
"caseExact": true,
"mutability": "readWrite",
"returned": "default",
"uniqueness": "none"
},
{
"name": "enterpriseEndpoint",
"type": "reference",
"description": "The URL of the enterprise endpoint which device control apps uses to reach enterprise network gateway. When enterprise receives the SCIM object from onboarding app, it adds this attribute to the object and sends back the object as response back to the onboarding app.",
"multivalues": false,
"required": true,
"caseExact": true,
"mutability": "readWrite",
"returned": "default",
"uniqueness": "none"
}
]
},
{
"name": "dataReceiver",
"type": "complex",
"description": "Data receiver application attributes.",
"multivalues": false,
"required": true,
"caseExact": false,
Shahzad, et al. Expires 14 July 2023 [Page 23]
Internet-Draft SCIM Device Schema Extensions January 2023
"mutability": "readWrite",
"returned": "default",
"uniqueness": "none",
"subAttributes" : [
{
"name": "client-tokens",
"type": "reference",
"description": "The URL of the device control application which can be used to access the app. This attribute is provided by the onboarding application when it creates the SCIM object for the device.",
"multivalues": true,
"required": true,
"caseExact": true,
"mutability": "readWrite",
"returned": "default",
"uniqueness": "none"
},
{
"name": "enterpriseEndpoint",
"type": "reference",
"description": "The URL of the enterprise endpoint which device control apps uses to reach enterprise network gateway. When enterprise receives the SCIM object from onboarding app, it adds this attribute to the object and sends back the object as response back to the onboarding app.",
"multivalues": false,
"required": true,
"caseExact": true,
"mutability": "readWrite",
"returned": "default",
"uniqueness": "none"
}
]
}
],
"meta" : {
"resourceType" : "Schema",
"location" : "/v2/Schemas/urn:ietf:params:scim:schemas:extension:endpointApps:2.0:Device"
}
}}
<CODE ENDS>
4.4.4. Endpoints Device Object Example
This example object below presents a BLE device along with the
application endpoints.
<CODE BEGINS>
{
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:Device",
"urn:ietf:params:scim:schemas:extension:ble:2.0:Device",
"urn:ietf:params:scim:schemas:extension:endpointapps:2.0:Device"],
"id": "e9e30dba-f08f-4109-8486-d5c6a3316111",
Shahzad, et al. Expires 14 July 2023 [Page 24]
Internet-Draft SCIM Device Schema Extensions January 2023
"displayName": "BLE Heart Monitor",
"adminState": true,
"urn:ietf:params:scim:schemas:extension:ble:2.0:Device" :
{ "versionSupport": ["5.3"],
"deviceMacAddress": "2C:54:91:88:C9:E2",
"addressType": false,
"pairingMethods": [
"urn:ietf:params:scim:schemas:extension:pairingNull:2.0:Device",
"urn:ietf:params:scim:schemas:extension:pairingJustWorks:2.0:Device",
"urn:ietf:params:scim:schemas:extension:pairingPassKey:2.0:Device",
"urn:ietf:params:scim:schemas:extension:pairingOOB:2.0:Device"],
"urn:ietf:params:scim:schemas:extension:pairingNull:2.0:Device": null,
"urn:ietf:params:scim:schemas:extension:pairingJustWorks:2.0:Device": {
"key": null
},
"urn:ietf:params:scim:schemas:extension:pairingPassKey:2.0:Device" : {
"key": 123456
},
"urn:ietf:params:scim:schemas:extension:pairingOOB:2.0:Device": {
"key": "TheKeyvalueRetrievedFromOOB",
"randNumber": 238796813516896
}
},
"urn:ietf:params:scim:schemas:extension:endpointapps:2.0:Device": {
"onboarding": {
"appUrl": "https//example.com/onboardingapp/",
"rootCertificate": "Certificate for onboarding app",
"enterpriseEndpoint": "https//enterprise.com/onboardingapp_endpoint/"
},
"deviceControl": {
"client-tokens": [
"1293847109832471203984789383XXX"
],
"enterpriseEndpoint": "https//enterprise.com/device_control_endpoint/"
},
"dataReceiver": {
"client-tokens":[
"dlku23234sdui232393"
],
"enterpriseEndpoint": "https//enterprise.com/data_receiver_endpoint/"
}
},
"meta": {
Shahzad, et al. Expires 14 July 2023 [Page 25]
Internet-Draft SCIM Device Schema Extensions January 2023
"resourceType": "Device",
"created": "2022-01-23T04:56:22Z",
"lastModified": "2022-05-13T04:42:34Z",
"version": "W\/\"a330bc54f0671c9\"",
"location": "https://example.com/v2/Device/e9e30dba-f08f-4109-8486-d5c6a3316111"
}
}}
<CODE ENDS>
5. Security Considerations
Because provisioning operations are senstive, each client must be
appropriately authenticated. Certain objects may be read-only or not
visible based on who is connected.
[ More to be added here. ]
6. IANA Considerations
TBD
7. Changes from Earlier Versions
Draft -01:
* Doh! We forgot the core device schemea!
Draft -00:
* Initial revision
8. References
8.1. Normative References
[BLE53] Bluetooth SIG, "Bluetooth Core Specification, Version
5.3", 2021.
[DPP2] Wi-Fi Alliance, "Wi-Fi Easy Connect Specification, Version
2.0", 2020.
[I-D.bhutton-json-schema]
Wright, A., Andrews, H., Hutton, B., and G. Dennis, "JSON
Schema: A Media Type for Describing JSON Documents", Work
in Progress, Internet-Draft, draft-bhutton-json-schema-01,
10 June 2022, <https://www.ietf.org/archive/id/draft-
bhutton-json-schema-01.txt>.
Shahzad, et al. Expires 14 July 2023 [Page 26]
Internet-Draft SCIM Device Schema Extensions January 2023
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997,
<https://www.rfc-editor.org/info/rfc2119>.
[RFC7643] Hunt, P., Ed., Grizzle, K., Wahlstroem, E., and C.
Mortimore, "System for Cross-domain Identity Management:
Core Schema", RFC 7643, DOI 10.17487/RFC7643, September
2015, <https://www.rfc-editor.org/info/rfc7643>.
[RFC7644] Hunt, P., Ed., Grizzle, K., Ansari, M., Wahlstroem, E.,
and C. Mortimore, "System for Cross-domain Identity
Management: Protocol", RFC 7644, DOI 10.17487/RFC7644,
September 2015, <https://www.rfc-editor.org/info/rfc7644>.
[RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
May 2017, <https://www.rfc-editor.org/info/rfc8174>.
[RFC8520] Lear, E., Droms, R., and D. Romascanu, "Manufacturer Usage
Description Specification", RFC 8520,
DOI 10.17487/RFC8520, March 2019,
<https://www.rfc-editor.org/info/rfc8520>.
8.2. Informative References
[RFC8995] Pritikin, M., Richardson, M., Eckert, T., Behringer, M.,
and K. Watsen, "Bootstrapping Remote Secure Key
Infrastructure (BRSKI)", RFC 8995, DOI 10.17487/RFC8995,
May 2021, <https://www.rfc-editor.org/info/rfc8995>.
Authors' Addresses
Muhammad Shahzad
North Carolina State University
Department of Computer Science
890 Oval Drive
Campus Box 8206
Raleigh, NC, 27695-8206
United States of America
Email: mshahza@ncsu.edu
Shahzad, et al. Expires 14 July 2023 [Page 27]
Internet-Draft SCIM Device Schema Extensions January 2023
Hassan Iqbal
North Carolina State University
Department of Computer Science
890 Oval Drive
Campus Box 8206
Raleigh, NC, 27695-8206
United States of America
Email: hiqbal@ncsu.edu
Eliot Lear
Cisco Systems
Richtistrasse 7
CH-8304 Wallisellen
Switzerland
Phone: +41 44 878 9200
Email: lear@cisco.com
Shahzad, et al. Expires 14 July 2023 [Page 28]