Internet-Draft SCIM Device Schema Extensions October 2022
Shahzad, et al. Expires 27 April 2023 [Page]
Workgroup:
Network Working Group
Internet-Draft:
draft-shahzad-scim-device-model-00
Published:
Intended Status:
Standards Track
Expires:
Authors:
M. Shahzad
North Carolina State University
H. Iqbal
North Carolina State University
E. Lear
Cisco Systems

Device Schema Extensions to the SCIM model

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 27 April 2023.

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

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

1.2. 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.3. 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.

2. The Device Schema

The device schema is a base schema upon which specific onboarding technology schemas are built. It is described below.

<CODE BEGINS>
{
    "urn:ietf:params:scim:schemas:extension:Endpoints:2.0:Device":{
        "type": "object",
        "$id": "urn:ietf:params:scim:schemas:extension:endpoints:2.0:Device",
        "title": "Endpoints extension schema for partner application",
        "description": "Endpoint schema contains URLs and root certificates for the partner application and URLs for enterprise endpoints.",
        "required": [
          "onboarding",
          "deviceControl",
          "dataReceiver"
        ],

        "properties": {

          "onboarding": {
            "type": "object",
            "$id": "#/properties/onboarding",
            "title": "Onboarding",
            "description": "Onboarding application attributes.",

            "required": [
              "onboardingAppUrl",
              "onboardingAppRootCertificate",
                    "onboardingEnterpriseEndpoint"
            ],

            "properties": {
              "onboardingAppUrl": {
                "$id": "#/properties/onboardingAppUrl",
                "type": "string",
                "format": "iri-reference",
                "title": "Onboarding application URL",
                "description": "The URL of the onboarding application which can be used to access the application. This attribute is provided by the onboarding application when it creates the SCIM object for the device.",
                "examples": ["https//example.com/onboardingapp/"]
              },
              "onboardingAppRootCertificate": {
                "$id": "#/properties/onboardingAppRootCertificate",
                "type": "string",
                "title": "The root certificate of onboarding application",
                "description": "This attribute comprises of the root certificate signed by the root CA. Onboarding application provides this attribute when it creates the SCIM object for the device."
              },
              "onboardingEnterpriseEndpoint": {
                "$id": "#/properties/onboardingEnterpriseEndpoint",
                "type": "string",
                "format": "iri-reference",
                "title": "Enterprise endpoint for onboarding app",
                "description": "The URL of the enterprise endpoint which oboarding app uses to reach enterprise network gateway. This attribute is already known to the onboarding app and adds it to the SCIM object, when it creates the SCIM object for the device.",
                "examples": ["https//enterprise.com/onboardingapp_endpoint/"]
              }
            }
          },

          "deviceControl": {
            "type": "object",
            "$id": "#/properties/deviceControl",
            "title": "Device Control",
            "description": "Device controll application attributes.",

            "required": [
              "deviceControlApps",
                    "deviceControlEnterpriseEndpoint"
            ],

            "properties": {

              "deviceControlApps": {
                "type": "array",
                "items": {
                  "type": "object"
                },
                "title": "Device control apps",
                "description": "The list of device control apps where each list entry contains i) URL and ii) root certificate for each device control app that can control the device.",
                "properties": {
                  "deviceControlAppUrl": {
                    "$id": "#/properties/deviceControlAppUrl",
                    "type": "string",
                    "format": "iri-reference",
                    "title": "Device control app url",
                    "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.",
                    "examples": ["https//example.com/device_control_app1/"]
                  },
                  "deviceControlAppRootCertificate": {
                    "$id": "#/properties/deviceControlAppRootCertificate",
                    "type": "string",
                    "title": "Device control root certificate",
                    "description": "This attribute comprises of the root certificate signed by the root CA. This attribute is already known to the onboarding app and adds it to the SCIM object, when it creates the SCIM object for the device."
                  }
                }
              },

              "deviceControlEnterpriseEndpoint": {
                "$id": "#/properties/deviceControlEnterpriseEndpoint",
                "type": "string",
                "format": "iri-reference",
                "title": "Device control enterprise endpoint",
                "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.",
                "examples": ["https//enterprise.com/device_control_endpoint/"]
              }
            }
          },

          "dataReceiver": {
            "type": "object",
            "$id": "#/properties/dataReceiver",
            "title": "Data Receiver",
            "description": "Data receiver application attributes.",

            "required": [
              "dataReceiverApps",
                    "dataReceiverEnterpriseEndpoint"
            ],

            "properties": {

              "dataReceiverApps": {
                "type": "array",
                "items": {
                  "type": "object"
                },
                "title": "Data receiver apps",
                "description": "The list of data receiver apps where each list entry contains i) URL and ii) root certificate for each of the data receiver app.",
                "properties": {
                  "dataReceiverAppUrl": {
                    "$id": "#/properties/dataReceiverAppUrl",
                    "type": "string",
                    "format": "iri-reference",
                    "title": "Data receiver app URL",
                    "description": "The URL of the data receiver application which can be used to access the application. This attribute is provided by the device control app when it communicates with the controller. Controller will add this in the SCIM object locally stored in the SCIM server.",
                    "examples": ["https//example.com/dataReceoiverapp1/"]
                  },
                  "dataReceiverAppRootCertificate": {
                    "$id": "#/properties/dataReceiverAppRootCertificate",
                    "type": "string",
                    "title": "Data receiver root certificate",
                    "description": "This attribute comprises of the root certificate signed by the root CA. This attribute is provided by the device control app when it communicates with the controller. Controller will add this in the SCIM object locally stored in the SCIM server."
                  }
                }
              },

              "dataReceiverEnterpriseEndpoint": {
                "$id": "#/properties/dataReceiverEnterpriseEndpoint",
                "type": "string",
                "format": "iri-reference",
                "title": "Data receiver enterprise endpoint",
                "description": "The URL of the enterprise endpoint which data receiver 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.",
                "examples": ["https//enterprise.com/data_receiver_endpoint/"]
              }
            }
          }
        }
    }
}}

<CODE ENDS>

3. The BLE Device Extension

This schema extends the Device schema to specify how the device is to be authenticated, as well as well as a URL to a control interface for the device.

<CODE BEGINS>
{
    "urn:ietf:params:scim:schemas:extension:Ble:2.0:Device":{
      "type": "object",
      "$id": "#/properties/urn:ietf:params:scim:schemas:extension:Ble:2.0:Device",
      "title": "Device extension schema for BLE",
      "description": "Extension schema for devices that support BLE. It contains the attributes that are specific BLE devices only.",

      "required": [
        "versionSupport",
        "deviceMacAddress",
        "addressType",
        "pairingMethods"
      ],

      "properties": {
        "versionSupport": {
          "$id": "#/properties/versionSupport",
          "type": "array",
          "items": {
            "type": "string"
          },
          "title": "Version support",
          "description": "Provides a list of all the BLE versions supported by the device.",
          "examples": ["4.1", "4.2", "5.0", "5.1", "5.2", "5.3"]
        },
        "deviceMacAddress": {
          "$id": "#/properties/deviceMacAddress",
          "type": "string",
          "title": "Device MAC address",
          "description": "It is the public MAC address assigned by the manufacturer. It is unique 48 bit value.",
          "examples": ["01:23:45:67:89:AB"],
          "pattern": "^[0-9A-Fa-f]{2}:[0-9A-Fa-f]{2}:[0-9A-Fa-f]{2}:[0-9A-Fa-f]{2}:[0-9A-Fa-f]{2}:[0-9A-Fa-f]{2}$"
        },
        "addressType": {
          "$id": "#/properties/addressType",
          "type": "boolean",
          "title": "Address type",
          "default": false,
          "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. "
        },
        "irk": {
          "$id": "#/properties/irk",
          "type": "string",
          "title": "Identity resolving key",
          "description": "Identity resolving key, which is unique for every device. It is used to resolve random address."
        },
        "pairingMethods": {
          "$id": "#/properties/pairingMethods",
          "type": "array",
          "item":{
            "type": "string"
          },
          "title": "Pairing methods",
          "examples": ["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": {
          "type": "null",
          "title": "Extension for null pairing method",
          "description": "This pairing method is for the BLE devices that do not use any pairing method and connects with the nearest device when powered up. There is no attribute for this method."
        },
        "urn:ietf:params:scim:schemas:extension:pairingJustWorks:2.0:Device": {
          "type": "object",
          "title": "Extension for just works pairing method.",
          "properties": {
            "key": {
              "type": "null",
              "title": "Key",
              "description": "Just works does not have any key value. For completeness, it is added with a key value 'null'."
            }
          }
        },
        "urn:ietf:params:scim:schemas:extension:pairingPassKey:2.0:Device": {
          "type": "object",
          "title": "Extension for pass key pairing method.",
          "properties": {
            "key": {
              "type": "integer",
              "title": "Key",
              "description": "A six digit passkey for ble device",
              "pattern": "^[0-9]{6}$"
            }
          }
        },
        "urn:ietf:params:scim:schemas:extension:pairingOOB:2.0:Device": {
          "type": "object",
          "title": "Extension for out of band pairing method.",
          "required": [
            "key",
            "randNumber"
          ],
          "properties": {
            "key": {
              "type": "string",
              "title": "Key",
              "description": "A key value retrieved from out of band source such as NFC."
            },
            "randNumber": {
              "type": "integer",
              "title": "Random number",
              "description": "Nonce added to the key."
            },
            "confirmationNumber": {
              "type": "integer",
              "title": "Confirmation number",
              "description": "Some solutions require confirmation number RESTful message exchange."
            }
          }
        }
      }
    }
}

<CODE ENDS>

4. Wifi EasyConnect Extension

This schema extends the device schema to enable Wifi EasyConnect (otherwise known as Device Provisioning Protocol).

<CODE BEGINS>
{
    "urn:ietf:params:scim:schemas:extension:Wifi:2.0:Device":{
      "type": "object",
      "$id": "urn:ietf:params:scim:schemas:extension:Wifi:2.0:Device",
      "title": "Device extension schema for WiFi",
      "description": "Extension schema for devices that support WiFi. It contains the attributes that are specific WiFi devices only.",

      "required": [
        "versionSupport",
        "bootstrapKey"
      ],

      "properties": {
        "versionSupport": {
          "$id": "#/properties/versionSupport",
          "type": "array",
          "items": {
            "type": "string"
          },
          "title": "Version support",
          "description": "Provides a list of all the WiFi versions supported by the device.",
          "examples": ["802.11ax"]
        },
        "bootstrappingMethod": {
          "$id": "#/properties/bootstrappingMethod",
          "type": "array",
          "items": {
            "type": "string"
          },
          "title": "Bootstrapping method",
          "description": "The list of all the bootstrapping methods available on the enrollee device.",
          "examples": ["QR", "NFC"]
        },
        "bootstrapKey": {
          "$id": "#/properties/bootstrapKey",
          "type": "string",
          "title": "Bootstrap key",
          "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.",
          "examples": ["MDkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDIgADURzxmttZoIRIPWGoQMV00XHWCAQIhXruVWOz0NjlkIA="]
        },
        "deviceMacAddress": {
          "$id": "#/properties/deviceMacAddress",
          "type": "string",
          "title": "Device MAC address",
          "description": "The MAC address assigned by the manufacturer. It is unique 48 bit value.",
          "examples": ["01:23:45:67:89:AB"],
          "pattern": "^[0-9A-Fa-f]{2}:[0-9A-Fa-f]{2}:[0-9A-Fa-f]{2}:[0-9A-Fa-f]{2}:[0-9A-Fa-f]{2}:[0-9A-Fa-f]{2}$"
        },
        "classChannel": {
          "$id": "#/properties/classChannel",
          "type": "array",
          "items": {
            "type": "string"
          },
          "title": "Class channel",
          "description": "A list of global operating class and channel shared as bootstrapping information. It is formatted as class/channel.",
          "examples": ["81/1", "115/36"]
        },
         "serialNumber": {
          "$id": "#/properties/serialNumber",
          "type": "string",
          "title": "Serial number",
          "description": "An alphanumeric serial number that may also be passed as bootstrapping information.",
          "examples": ["4774LH2b4044"]
        }
      }
    }
}

<CODE ENDS>

5. Zigbee Extension

This schema extends the device schema to enable provisioning of Zigbee devices.

{
    "urn:ietf:params:scim:schemas:extension:zigbee:2.0:Device":{
        "type": "object",
        "$id": "urn:ietf:params:scim:schemas:extension:zigbee:2.0:Device",
        "title": "Device extension schema for zigbee.",
        "description": "Extension schema for devices that support zigbee. It contains the attributes that are specific zigbee devices only.",

        "required": [
            "versionSupport",
            "deviceEui64Address"
        ],

        "properties": {
            "versionSupport": {
            "$id": "#/properties/versionSupport",
            "type": "array",
            "items": {
                "type": "string"
            },
            "title": "Version support",
            "description": "Provides a list of all the zigbee versions supported by the device.",
            "examples": ["3.0"]
            },
            "deviceEui64Address": {
            "$id": "#/properties/deviceEui64Address",
            "type": "string",
            "title": "EUI-64 address",
            "description": "The EUI-64 (Extended Unique Identifier) device address.",
            "examples": ["50325FFFFEE76728"],
            "pattern": "^[0-9A-Fa-f]{16}$"
            }
        }
    }
}

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

8. Changes from Earlier Versions

Draft -00:

  • Initial revision

9. References

9.1. Normative References

[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, , <https://www.ietf.org/archive/id/draft-bhutton-json-schema-01.txt>.
[RFC2119]
Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, , <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, , <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, , <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, , <https://www.rfc-editor.org/info/rfc8174>.

9.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, , <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
Hassan Iqbal
North Carolina State University
Department of Computer Science
890 Oval Drive
Campus Box 8206
Raleigh, NC, 27695-8206
United States of America
Eliot Lear
Cisco Systems
Richtistrasse 7
CH-8304 Wallisellen
Switzerland
Phone: +41 44 878 9200