Site Tools


coapnativecloud

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision
Previous revision
coapnativecloud [2018/08/09 08:12]
ondrej.tomcik
coapnativecloud [2018/08/09 08:28] (current)
ondrej.tomcik
Line 145: Line 145:
 ==== Domain definitions ==== ==== Domain definitions ====
 //The following list defines the key domain-related terms.// //The following list defines the key domain-related terms.//
-**Client** is a logical entity that accesses a Resource on a Server. +  * **Client** is a logical entity that accesses a Resource on a Server. 
-**Resource** is an object with a type, associated data, relationship to other Resources, and a set of methods that operate on it. It is hosted by the Server. +  ​* ​**Resource** is an object with a type, associated data, relationship to other Resources, and a set of methods that operate on it. It is hosted by the Server. 
-**Resource Directory** is a set of descriptions of Resources where the actual Resources are held on Servers external to the Device hosting the Resource Directory, allowing look-ups to be performed for those Resources. +  ​* ​**Resource Directory** is a set of descriptions of Resources where the actual Resources are held on Servers external to the Device hosting the Resource Directory, allowing look-ups to be performed for those Resources. 
-**Resource Shadow** is the latest state of the Resource stored directly in the OCF Native Cloud, which is eventually consistent with the state on the device. +  ​* ​**Resource Shadow** is the latest state of the Resource stored directly in the OCF Native Cloud, which is eventually consistent with the state on the device. 
-**Resource Type** is a uniquely named definition of a class of Resource Properties and the interactions that are supported by that class +  ​* ​**Resource Type** is a uniquely named definition of a class of Resource Properties and the interactions that are supported by that class 
-**Server** is a Device with the role of providing resource state information and facilitating remote interaction with its Resources.+  ​* ​**Server** is a Device with the role of providing resource state information and facilitating remote interaction with its Resources.
  
 ==== Requirements for working with resources ==== ==== Requirements for working with resources ====
Line 173: Line 173:
  
 === Interactions === === Interactions ===
-**OCF Server / Client** are OCF actors communicating over CoAP through the OCF CoAP Gateway. +  * **OCF Server / Client** are OCF actors communicating over CoAP through the OCF CoAP Gateway. 
-**OCF CoAP Gateway** is the component which takes care of translation of CoAP requests to commands accepted by an OCF Native Cloud reference implementation. +  ​* ​**OCF CoAP Gateway** is the component which takes care of translation of CoAP requests to commands accepted by an OCF Native Cloud reference implementation. 
-**Resource Directory** is the read model containing resource descriptions and up-to-date representations,​ built with events from the aggregate.+  ​* ​**Resource Directory** is the read model containing resource descriptions and up-to-date representations,​ built with events from the aggregate.
  
 <WRAP center round info 90%> <WRAP center round info 90%>
Line 239: Line 239:
 //The following list defines the key domain-related terms.// //The following list defines the key domain-related terms.//
  
-**Client** is a logical entity that accesses a Resource on a Server. +  * **Client** is a logical entity that accesses a Resource on a Server. 
-**OAuth Server** is a server providing a mechanism for standardized access delegation. +  ​* ​**OAuth Server** is a server providing a mechanism for standardized access delegation. 
-Onboarding process of authenticating and authorizing the Server / Client to communication with the OCF Native Cloud. +  ​* ​Onboarding process of authenticating and authorizing the Server / Client to communication with the OCF Native Cloud. 
-**Permission** is the action of granting someone their request. +  ​* ​**Permission** is the action of granting someone their request. 
-**Server** is a Device with the role of providing resource state information and facilitating remote interaction with its resources. +  ​* ​**Server** is a Device with the role of providing resource state information and facilitating remote interaction with its resources. 
-**Security Identifier** (SID) is a unique value of variable length used to identify a trustee. Each account has a unique SID issued by an authority, such as a Windows domain controller, and is stored in a security database. +  ​* ​**Security Identifier** (SID) is a unique value of variable length used to identify a trustee. Each account has a unique SID issued by an authority, such as a Windows domain controller, and is stored in a security database. 
-**User / Device Management** is the component holding information on who has access to what. +  ​* ​**User / Device Management** is the component holding information on who has access to what. 
-**User** is an authenticated entity, authorized to onboard devices.+  ​* ​**User** is an authenticated entity, authorized to onboard devices.
  
 ==== Requirements for working with authorization ==== ==== Requirements for working with authorization ====
Line 288: Line 288:
 ==== Remarks ==== ==== Remarks ====
   * The Account Server, in the way it is implemented in IoTivity v1.3.0 is forcing users to use a very specific data model for authorization. The proposed solution is instead driven by the user, not forcing them to map it to an existing model.   * The Account Server, in the way it is implemented in IoTivity v1.3.0 is forcing users to use a very specific data model for authorization. The proposed solution is instead driven by the user, not forcing them to map it to an existing model.
-    * Current implementation in the IoTivity SDK provides OCAccountManager,​ through which you can control access management. This is very user specific and does not belong in the device SDK. The cloud should stay separate as well as the authorization model inside the cloud API.  In the new design, this is completely up to the user and shouldn'​t be exposed to the device.+    * Current implementation in the IoTivity SDK provides ​[[https://​github.com/​iotivity/​iotivity/​blob/​1a7e693057120130de252e5a26a62c407d28093a/​resource/​include/​OCAccountManager.h|OCAccountManager]], through which you can control access management. This is very user specific and does not belong in the device SDK. The cloud should stay separate as well as the authorization model inside the cloud API.  In the new design, this is completely up to the user and shouldn'​t be exposed to the device. 
 + 
 +===== OCF CoAP Gateway ===== 
 +OCF Servers / Clients communicate over TCP / UDP using the CoAP application protocol. Communication within the OCF Native Cloud shouldn'​t be restricted to the CoAP protocol, implementation should allow the use of whatever protocol might be introduced in the future. That's why the gateway is the access point for CoAP over TCP, and further communication is OCF Native Cloud specific. 
 + 
 +TCP connection to the OCF Native Cloud is by its nature stateful. The OCF CoAP Gateway is therefore also stateful, keeping open connections to the OCF Servers / Clients. ​ The goal of the Gateway is to translate between the OCF Servers / Clients (CoAP) and the protocol of the OCF Native Cloud and communicate in an asynchronous way. 
 + 
 +==== Validation ==== 
 +  * OCF CoAP Gateway can accept requests from the OCF Client / Server only after a successful sign-in  
 +  * OCF CoAP Gateway can forward requests to the OCF Client / Server only after successful sign-in  
 +  * If sign-in was not issued within the configured amount of time or sign-in request failed, OCF Native Cloud will forcibly close the TCP connection 
 +  * OCF CoAP Gateway sends command to update device core resource with its status. 
 +    * Online when the device was successfully signed-in and communication lock released 
 +    * Offline when the device was disconnected or signed-out 
 +  * Access Token from a successful sign-in must be locally persisted in the OCF CoAP Gateway and linked with an opened TCP channel 
 +  * Access Token linked with the opened TCP channel has to be included in each command issued to other OCF Native Cloud components 
 +  * OCF CoAP Gateway processes only those commands, which are designated for a device which the Gateway has an opened TCP channel to 
 +  * OCF CoAP Gateway is observing each resource published to the resource directory and publishes an event for every change 
 +  * OCF CoAP Gateway retrieves each published resource and updates Resources 
 +  * OCF CoAP Gateway has to expose the coap ping-pong + retry count configuration,​ which can be configured during the deployment 
 +  * OCF CoAP Gateway has to ping the device in the configured time, if pong is not received after the configured number of retries, then the connection with the device is closed and device is set as offline 
 +  * OCF CoAP Gateway processes events from Resources, by issuing a proper CoAP request to the device and raising an event with the response 
 +  * OCF CoAP Gateway has to process a waiting request within the configured time, or set the device as offline 
 + 
 +==== Load balancing ==== 
 +In case of a deployment with many OCF Clients / Servers, a single instance of the OCF CoAP Gateway is not enough. Scaling and load balancing of connections is required. More options are available:​ 
 + 
 +  * Proxy 
 +    * L3/4 (transport layer) 
 +    * L7 (application layer) 
 +  * Client side 
 +    * Thick Client 
 +    * Lookaside 
 + 
 +As load balancing can be very user specific (e.g. OCF CoAP Gateway per tenant), OCF Native Cloud will not include this functionality. ​ Users may already have a preferred solution in their infrastructure to handle load balancing or their needs may be excessively complicated (high performance,​ low lantency, many clients, etc.). ​ That is why this topic is out of scope and will not be solved by OCF Native Cloud. 
 + 
 +==== Implementation details ==== 
 +=== Interactions === 
 +  * **OCF Server / Client** are OCF actors communicating over CoAP through the OCF CoAP Gateway. 
 +  * **OCF CoAP Gateway** is the component which handles translation of CoAP requests to commands accepted by an OCF Native Cloud reference implementation. 
 +  * **Resources** is the bounded context 
 +  * **Authorization** is the bounded context 
 + 
 +{{:​gw_1.png}} 
 +{{:​gw_2.png}} 
 + 
 +==== Remarks ==== 
 +  * In the current design, the OCF CoAP Gateway also acts as a process manager. This might change in the future, mainly when a different gateway protocol is required. Due to the fact that: 
 +    * We want to re-use the stateless nature of the OCF CoAP Gateway component 
 +    * Validate the design and need for change during implementation 
 + 
 +===== Sample Usage ===== 
 +The market is missing a remote system allowing OCF enabled devices to be connected so a device owner can see their state and control them. There are multiple use-cases for such a system (e.g. smart home, processing plants, hospitals, universities). Companies developing such systems want to support as many devices as possible without need for protocol adapters and device specific implementation,​ which might be provided by the OCF standard in the future. OCF Native Cloud should be open enough to allow companies who want to introduce such a system to do it without limitations,​ not forcing them to use specific technologies,​ but leave it up to them as much as possible. Integration with their existing system will become easier, resulting in a growth of users and increasing the number OCF enabled devices. ​  
 + 
 +A company integrating the OCF Native Cloud based on the new design is not forced to use CoAP for communication with the OCF Native Cloud. OCF Devices are currently communicating with the OCF Native Cloud over CoAP, but that's a limitation to be overcome. To build a business case with OCF enabled devices and Native Cloud, user services have to be introduced and should be able to communicate with the OCF Native Cloud. As mentioned before, with no need for the use of CoAP. Services within the same deployment should effectively communicate in the same way the OCF CoAP Gateway is communicating with the rest of the system - Resource and Authorization bounded contexts. 
 + 
 +Let's assume a company is already providing simple device management for their devices, but would also like to support an OCF enabled system which will guarantee more customers for their software. Their Device Management (DM) service exposes a REST API and allows users to configure them and see current readings of sensors attached to those devices. The company already has an OAuth based authorization server and User Management. What would the integration look like? 
 + 
 +==== Integration details ==== 
 +  * Authorization bounded context of the OCF Native Cloud is their OAuth Server and User Management 
 +    * Command Handler for commands coming from the OCF Native Cloud have to be implemented for their service 
 +  * Device Management contains a view of their devices 
 +    * Device Management has to query the Resource Directory / Resource Shadow when the DM user requests device information 
 +  * User making requests through their REST API uses bearer token issued by their Authorization Server 
 +    * This token has to be forwarded in the query to the Resource Directory / Resource Shadow to authorize the request 
 + 
 +{{:​sample_1.png}} 
coapnativecloud.1533802375.txt.gz · Last modified: 2018/08/09 08:12 by ondrej.tomcik