OpenCloudMesh Summary

OpenCloudMesh is an established standard for sharing access to files and other resources. It's used in well known applications like Nextcloud, Owncloud, EOS and Seafile and proven by large scale deployments in organisations as Sciebo, GÉANT and CERN. While OpenCloudMesh is focused on file sharing, it is also capable of managing shares based on any other access protocol.

Establishing Trust

The operator of an OpenGeoMesh server can control which feature collections can be shared with which recipients. By using the optional OCM Invite Flow of OpenCloudMesh, sharing can be restricted to trusted partners.

  sequenceDiagram
    title OCM Invite Flow 
    actor Alice
    participant A as OCM Server A<br/>(Invite Sender)
    participant B as OCM Server B<br/>(Invite Receiver)
    actor Bob
    Alice ->> +A: Create Invite Message
    A -->> -Alice: Invite Message with token
    Alice ->> Bob: Invite Message, Out of Band, e.g. via Mail
    Bob ->> +B: Invite Acceptance Gesture
    B ->> +A: OCM API Discovery
    A -->> -B: API Info (e.g. Organisation Name)
    B ->> B: check trust policy
    B ->> +A: Invite Acceptance Request
    A ->> A: check trust policy
    A -->> B: Invite Acceptance Response
    A ->> -A: Add B to allowlist
    B ->> B: Add A to allowlist
    B -->> -Bob: Response

Creating a Share

Users of one organisation can create shares for users and groups from other organisations using the recipients OCM Address. OCM Addresses for users and groups are defined by the operator of the receiving server, e.g. user-id@feuerwehr-musterstadt.de, FFW-Musterstadt@situation-map-software.com or Einsatzleitung.FFW-Musterstadt@situation-map-software.com.

When creating a share, it must be first checked if the sending party is authorized to grant read or write access for the given feature collection to the receiving party.

  sequenceDiagram
    title OCM Create Share (Extended by OGM specific access checks)
    actor Alice as Alice<br/>(Sending Party)
    participant A as OCM Server A<br/>(Sending Server)
    participant A_ogc as OGC API Server A
    participant B as OCM Server B<br/>(Receiving Server)
    actor Bob as Bob<br/>(Receiving Party)
    Alice ->> +A: Sharing Gesture<br/>(Resource to be shared, Receiving Party's identifier, ...)
    A ->> A: check allowlist
    A ->> +A_ogc: Get Collection
    A_ogc -->> -A: Collection name, description, permissions
    A ->> A: check permissions
    A ->> B: OCM API Discovery<br/>(skipped when details are stored in allowlist)
    B -->> A: API Info (e.g. Organisation Name)
    A ->> A: Store new Share Info
    A ->> +B: Share Creation Notification</br>with protocol "ogcapi"
    B ->> B: check allowlist
    B ->> Bob: Receiving Party Notification
    Bob -->> B: Acceptance
    B ->> A: OCM API Discovery<br/>(skipped when details are available)
    A -->> B: API Info (e.g. Organisation Name)
    B ->> A: Share Acceptance Notification

Integration of OpenGeoMesh in OpenCloudMesh

While most implementations of OpenCloudMesh use WebDAV for file sharing, OpenCloudMesh is capable of exchanging shares for arbitrary protocols. OpenGeoMesh specifies additional protocol and resource identifiers to enable the exchange of shares of OGC API collections.

  ---
config:
  layout: elk
---
flowchart LR
 subgraph ocm_a["OpenCloudMesh"]
        P["Protocol<br>*opengeomesh*"]
  end
 subgraph a["Sending Server"]
        ocm_a
        R["Resource<br>*ogcapi*"]
  end
 subgraph b["Receiving Server"]
        ocm_b["OpenCloudMesh"]
        pc["Protocol Client"]
  end
    R --> P
    ocm_a -- send share --> ocm_b
    ocm_a -- Discovery --> ocm_b
    ocm_b -- protocol<br>properties --> pc
    P <== data access ==> pc

ResourceType ogcapi

OpenGeoMesh defines the new ResourceType "ogcapi" which represents an individual OGC API collection which can be shared.

Protocol opengeomesh

OpenGeoMesh defines the new Protocol "opengeomesh" for accessing a shared "ogcapi" resource. Shares with protocol "opengeomesh" will provide an URI for accessing the share, a shared secret which needs to be included in requests as "Authorization: Bearer" Header. The URI can be either absolute or relative to basepath advertised for opengeomesh in Discovery. Optionally an URI to an OpenAPI description for the shared collection can be provided, also requiring authorization via the shared secret.

Support for the opengeomesh protocol and ogcapi resources MUST be advertised via Discovery.

{
  "enabled": true,
  "apiVersion": "1.2.2",
  "endPoint": "https://receiving-server.example.org",
  "provider": "Freiwillige Feuerwehr Empfänger",
  "resourceTypes": [
    {
      "name": "ogcapi",
      "shareTypes": [
        "user"
      ],
      "protocols": {
        "opengeomesh": "/ogm"
      }
    }
  ],
  "capabilities": [
    "protocol-object"
  ],
  "criteria": [
    "http-request-signatures"
  ],
  "publicKey": {
    "keyId": "https://receiving-server.example.org/.well-known/ocm#signature",
    "publicKeyPem": "-----BEGIN PUBLIC KEY-----\nMCowBQYDK2VwAyEAYAl7r+4Dg9oXCRqsLmVzSYk90WXsd/9VWGCvtrgtToM=\n-----END PUBLIC KEY-----\n"
  }
}

OpenGeoMesh Shares can be sent to supporting OCM Servers as follows:

{
    "name": "Collection Title",
    "owner": "owner@sending-server.example.org",
    "protocol": {
        "name": "multi",
        "opengeomesh": {
            // Shared Secret
            "sharedSecret": "62t9uHwRuhu6AQRoNDLqsSEM6iAGniPf6",    
            // Share is accessible at https://sending-server.example.org/ogm/883fbc59-2dd8-4c12-b827-387e2d56c9f8
            "uri": "883fbc59-2dd8-4c12-b827-387e2d56c9f8",          
            // OpenAPI Spec is accessible at https://sending-server.example.org/ogm/883fbc59-2dd8-4c12-b827-387e2d56c9f8/api
            "service-desc": "883fbc59-2dd8-4c12-b827-387e2d56c9f8/api"
        },
    },
    "providerId": "883fbc59-2dd8-4c12-b827-387e2d56c9f8",
    "resourceType": "ogcapi",
    "sender": "sender@sending-server.example.org",
    "shareType": "user",
    "shareWith": "recipient@receiving-server.example.org",
}