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 07:24]
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 206: Line 206:
 </​WRAP>​ </​WRAP>​
  
 +===== Resource Directory =====
 +A frequently cited advantage of the CQRS pattern is that it enables you to scale the read side and write side of the application independently to support the different usage patterns. The Resource Aggregate, write side of the Resource Bounded Context is emitting events which are used for the building of the Resource Directory view model. The Resource Directory is therefore queried directly and can be scaled independent of the write side.
  
 +<WRAP center round important 90%>
 +As the Resource Directory is built from Resource Aggregate events, it is not immediately consistent, but will be in time.
 +</​WRAP>​
 +
 +<WRAP center round info 90%>
 +This approach also allows OCF Native Cloud users to build their own view model based on the Resource Aggregate events //(e.g. flat resource structure where a root element is a device)//, which might make more sense for their domain.
 +</​WRAP>​
 +
 +==== Security ====
 +The Command Handler for the Resource Directory Aggregate has the business invariant Authorization - which has to be validated within each issued command to the Resource Aggregate. Resource Directory, the read side has to return only those resources a user is authorized to receive. As each client / server is identified by the token, this token has to be used in the communication with the read side - Resource Directory.
 +
 +===== Resource Shadow =====
 +Within the OCF Native Cloud, the resource shadow provides the latest representation of resources, because it is in sync with the physical devices. ​ Through the use of the CQRS pattern, the resource shadow is the independently scaled, and the read side will eventually be consistent with the devices represented. ​ It is not immediately consistent, since it takes time for the Resource Aggregate events to be handled, which it is built from.
 +
 +<WRAP center round important 90%>
 +As the Resource Shadow is built from Resource Aggregate events, it is not immediately consistent, but will be in time.
 +</​WRAP>​
 +
 +<WRAP center round info 90%>
 +This approach also allows OCF Native Cloud users to build their own view model based on the Resource Aggregate events, and enrich it appropriate to their own domain.
 +</​WRAP>​
 +
 +==== Security ====
 +The Command Handler for the Resource Directory Aggregate has the business invariant Authorization,​ which has to be validated within each issued command to the Resource Aggregate.
 +
 +The read side of the Resource Shadow will return only those resources a user is authorized to receive. As each client / server pair is identified by a token, this token has to be used in the communication with the read side of the Resource Shadow.
 +
 +===== Authorization Bounded Context =====
 +//The following list defines the key domain-related terms.//
 +
 +  * **Client** is a logical entity that accesses a Resource on a Server.
 +  * **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.
 +  * **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.
 +  * **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** is an authenticated entity, authorized to onboard devices.
 +
 +==== Requirements for working with authorization ====
 +To be able to communicate through the OCF Native Cloud, an OCF Server / Client has to first sign-up and sign-in. The Sign-up //​(registration of the entity)//, to the OCF Native Cloud requires a unique, one-time-use authorization code which is issued by an OAuth Server for a logged-in OCF Native Cloud user and transferred to the device. //(The way the code is set on the device is not part of the OCF Native Cloud)//. The OCF Native Cloud will ask the OAuth server to verify the issued authorization code, if it is still valid and not yet used. After successful validation, the OAuth server returns an access token for further communication between the onboarded device and the OCF Native Cloud.
 +
 +<WRAP center round info 90%>
 +An access token is personalized,​ as it was issued by the subject //(OCF Native Cloud User)// for the specific device.
 +</​WRAP>​
 +
 +User/Device Management Component communicating with the OAuth Server //(might be one component)//​ assigns the device to the user who started the onboarding process - asked for authorization code and returns sign-in data back to the device as a response to the sign-up.
 +
 +<WRAP center round info 90%>
 +The OCF Native Cloud user who onboarded the device becomes the owner of this device.
 +</​WRAP>​
 +
 +When the OCF Server / Client is signed-up, it can continue with the sign-in process. A successfully signed-in device might publish its resources and be requested //(CRUDN)// through the OCF Native Cloud without limitation. The OCF Native Cloud itself is responsible for authorization requests from different OCF Servers / Clients. OCF Servers / Clients can communicate with each other, if they have the same owner //​(onboarded by the same user)//.
 +
 +<WRAP center round important 90%>
 +This is a simple default scenario, which will usually be modified by the companies using OCF Native Cloud. Management of users and devices is completely business specific and has to be modeled on your own.
 +</​WRAP>​
 +
 +Each request to a resource is validated with the Authorization Bounded Context and provides information,​ **//which user has permission to which OCF Client / Servers identified by the id.//**
 +
 +<WRAP center round info 90%>
 +Each request session must be backed by an access token, so the OCF Native Cloud can authorize that request. In case of the OCF Servers / Clients, a TCP session must be backed by the access token and validated through the sign-up process. Each command issued by the OCF CoAP Gateway is then backed by the validated token.
 +</​WRAP>​
 +
 +==== Validation ====
 +  * Server / Client has to be signed-up and signed-in to successfully communicate with the OCF Native Cloud
 +  * The user who onboarded the Server / Client has to be able to make requests to them through the OCF Native Cloud with his token
 +  * Servers and Clients onboarded by the same user have to be able to communicate with each other through the OCF Native Cloud, using the token received after the sign-up
 +
 +==== Implementation details ====
 +To be able to clearly identify if the OCF Native Cloud User or the OCF Server / Client onboarded by them is authorized to make a request to another OCF Server, a concrete claim from the token of the requester must be mapped with the requested server id in the component responsible for the User / Device Management.
 +
 +Candidate for the sample business invariant validation is the claim SID, which would identify an OCF Native Cloud User. The User / Device Management component would then provide information,​ which server IDs can be accessed by this user, identified by SID. As the OAuth Server would be most often provided by you, custom claims can be introduced and used for mapping with server IDs. For example, each OCF Native Cloud User belongs to a certain tenant, identified by a unique id. If the granularity of having devices accessible by tenants is enough for you, you're free to model it in this way and specify which claim should be used for validation inside the Command Handler of the Resource Bounded Context.
 +
 +{{:​auth_1.png}}
 +{{:​auth_2.png}}
 +
 +==== 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.
 +    * 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.1533799482.txt.gz · Last modified: 2018/08/09 07:24 by ondrej.tomcik