simplify domains

[cdupont]

As part of the documentation, the "domain" part of the URL embodies several concepts. It's structure is <service>-<subservice>, such as "waziup-farm1".

• The service is the FIWARE-Service in Orion
• The subservice is the FIWARE-ServicePath in Orion
• The service is also the realm in Keycloak
• The full domain is used as index name in Keycloak (for data analytics)
• The full domain is used as collection name in Mongo (for short historic)

This has several problems:

• It's not possible to move easily an entity from one ServicePath to another in Orion
• The api-server component is connected to one client realm in Keycloak, it's difficult to change realm based on the URL
• It's difficult for the user to understand the concept of domain, as it combines many things. For example a user can create a domain "waziup-farm1" but not "farm1" as this implicates the creation of another realm in KC.

[cdupont]

Proposed design is to simplify the domain. The domain will just correspond to a group of resources, for example "farm1". A group of resources can contain sensors, users, fields...

• Each entity in Orion will have a "domain" attribute containing its domain. This way it's easier to change it latter. FIWARE-ServicePath is not used.
• The FIWARE-Service used will not appear on the URL but in a configuration file.
• The Keycloak realm used will not appear on the URL but in a configuration file.
• The index name and collection name is not changed (service-servicePath)

Changes in the api-server:

• The api-server will support several configuration files. Each file represent one realm.
• Several instances of the "app" object in the api-server allows to listen to different ports for each realms.
• A different realm also corresponds to a different FIWARE-Service in Orion.
• The default domain is renamed "default" (instead of "waziup").

Configuration file change (config.js):

{
   // backend components are common for all realms
   backend: {
      keycloakUrl:      process.env.KEYCLOAK_URL || 'http://localhost:8080/auth',
      orionUrl:         process.env.ORION_URL || 'http://localhost:1026',
      elasticsearchUrl: process.env.ELASTICSEARCH_URL || 'http://localhost:9200',
      mongoDBUrl:       process.env.MONGODB_URL || 'mongodb://localhost:27017/waziup_history',
      socialsUrl:       process.env.SOCIALS_URL || 'http://localhost:9123',
   }
   //each client gets a different realm and FIWARE-Service
   clients: [
     {
        name: 'waziup'
        port: process.env.SERVER_PORT || 3000,
        serverUrl: process.env.SERVER_URL || `http://localhost:${process.env.SERVER_PORT || 3000}`,  
        realm: 'waziup',
        clientId: 'api-server',
        FIWAREService: 'waziup',
        MongoPrefix: 'waziup'
     }
   ]
};

In this configuration file, there can be several clients: for example 'waziup' and 'myBigCompany'.

For examples: Get all sensors in the default domain: GET www.waziup.io/api/v1/domains/default/sensors This will fetch sensors in the "waziup" FIWARE-Service and use "waziup" realm to verify the permissions.

We can configure another client in the api-server, to serve a completely different application, without sharing any users of resources. In this case, the api-server will serve the URL on another port. This port can be binded to another subdomain. For example: GET myBigCompany.waziup.io/api/v1/domains/default/sensors Will fetch the sensors in the myBigCompany Service in Orion and use user permissions from myBigCompany realm.

[cdupont]

Pro and cons of encoding the domain in the servicePath, vs encoding the domain in an attribute:

Domain in the servicePath:

Pro:

• Easy partitioning: Requesting an entity or an attribute value in that Service path will return only resources from that domain.

Cons:

• Hard to move an entity from one domain to another: it requires deleting the entity and re-creating it.
• requires to change the Gateway configuration in case the domain is changed by the user.

Domain in an attribute:

Pros:

• easy to move the entity: just need to change the attribute. Cons:
• hard to verify the domain when directly requesting an attribute (need to retrieve the entity as well).
• notifications doesn't have attributes

[cdupont]

Done: domain is stored as an attribute