Device Schema Extensions to the SCIM model

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? ]]

BLE Extension This schema extends the device schema to represent the devices supporting BLE. The attributes are as follows:

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:

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.

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.

BLE Pairing Method Extensions The details on pairing methods and their associated attributes are in section 2.3 of . 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:

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.

BLE Extension JSON Representation

[ { "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" } } ]

]]>


BLE Device Object Example


{
  "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"
  }
}

]]>


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 . The attributes are as follows:

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:



serialNumber

An alphanumeric serial number may also be passed as bootstrapping information.


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'].


DPP Extension JSON Representation


{  
    "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"
    }
  }

]]>



DPP Device Object Example


{
        "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"
        }
}

]]>




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:

Singular Attribute

deviceEui64Address

this attribute is an EUI-64 (Extended Unique Identifier) device
address. The regex pattern is as follows:




Multivalued Attribute

versionSupport

This attribute provides an array of all the Zigbee versions supported by the
device. For example, [3.0].


Zigbee Extension JSON Representation


{  
  "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"
  }
}

]]>



Zigbee Device Object Example


{
  "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"
  }
}

]]>




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:

"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:

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.


"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:


  a multi-valued attribute called "client-tokens".
  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.


Endpoint Extension JSON Representation


{  
  "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"
  }
}}

]]>



Endpoints Device Object Example
This example object below presents a BLE device along with the application endpoints.


{
  "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"
  }
}}

]]>