| Internet-Draft | SCIM Device Schema Extensions | January 2023 |
| Shahzad, et al. | Expires 14 July 2023 | [Page] |
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.¶
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 (c) 2023 IETF Trust and the persons identified as the document authors. All rights reserved.¶
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.¶
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.¶
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.¶
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:¶
+-----------------------------------+
| |
+-----------+ Request | +---------+ |
| onboarding|------------->| SCIM | |
| app |<-------------| Server | |
+-----------+ Ctrl Endpt +---------+ |
| |
+-----------+ | +------------+ +-------+ |
| Control |...........|..| ALG |.........|device | |
| App | | +------------+ +-------+ |
+-----------+ | |
| |
+-----------------------------------+
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.¶
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.¶
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.¶
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.¶
Device grouping occurs using the core SCIM group object, as defined in [RFC7643] Section 4.2.¶
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
},
{
"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>¶
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.¶
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¶
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]).¶
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].¶
Following is the JSON representation of the Device core schema. Common attributes such as "id" and "externalID" are not presented below.¶
<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>¶
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>¶
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? ]]¶
This schema extends the device schema to represent the devices supporting BLE. The attributes are as follows:¶
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¶
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.¶
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.¶
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:¶
^[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.¶
<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,
"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" : [
{
"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,
"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>¶
<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>¶
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:¶
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.¶
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'].¶
<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.",
"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",
"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>¶
<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>¶
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:¶
deviceEui64Address¶
this attribute is an EUI-64 (Extended Unique Identifier) device address. The regex pattern is as follows:¶
^[0-9A-Fa-f]{16}$
¶
versionSupport¶
This attribute provides an array of all the Zigbee versions supported by the device. For example, [3.0].¶
<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>¶
<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>¶
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:¶
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:¶
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.¶
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:¶
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.¶
<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,
"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>¶
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",
"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": {
"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>¶
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. ]¶
Draft -01:¶
Draft -00:¶