OCM

Abstract

The ocm service provides federated sharing functionality based on the sciencemesh and ocm HTTP APIs. Internally the ocm service consists of the following services and endpoints:

External HTTP APIs:

sciencemesh: serves the API for the invitation workflow
ocmd: serves the API for managing federated shares

Internal GRPC APIs:

ocmproviderauthorizer: manages the list of trusted providers and verifies requests
ocminvitemanager: manages the list and state of invite tokens
ocmshareprovider: manages ocm shares on the sharer
ocmcore: used for creating federated shares on the receiver side
authprovider: authenticates webdav requests using the ocm share tokens

Enable OCM
Trust Between Instances
Invitation Workflow
Creating Shares
Example Yaml Config

Enable OCM

To enable OpenCloudMesh, you have to set the following environment variable.

OCIS_ENABLE_OCM=true

Trust Between Instances

The ocm services implements an invitation workflow which needs to be followed before creating federated shares. Invitations are limited to trusted instances, however.

The list of trusted instances is managed by the ocmproviderauthorizer service. The only supported backend currently is json which stores the list in a json file on disk. Note that the ocmproviders.json file, which holds that configuration, is expected to be located in the root of the ocis config directory if not otherwise defined. See the OCM_OCM_PROVIDER_AUTHORIZER_PROVIDERS_FILE envvar for more details.

When all instances of a federation should trust each other, an ocmproviders.json file like this can be used for all instances:

[
    {
        "name": "oCIS Test",
        "full_name": "oCIS Test provider",
        "organization": "oCIS",
        "domain": "cloud.ocis.test",
        "homepage": "https://ocis.test",
        "description": "oCIS Example cloud storage",
        "services": [
            {
                "endpoint": {
                    "type": {
                        "name": "OCM",
                        "description": "cloud.ocis.test Open Cloud Mesh API"
                    },
                    "name": "cloud.ocis.test - OCM API",
                    "path": "https://cloud.ocis.test/ocm/",
                    "is_monitored": true
                },
                "api_version": "0.0.1",
                "host": "http://cloud.ocis.test"
            },
            {
                "endpoint": {
                    "type": {
                        "name": "Webdav",
                        "description": "cloud.ocis.test Webdav API"
                    },
                    "name": "cloud.ocis.test Example - Webdav API",
                    "path": "https://cloud.ocis.test/dav/",
                    "is_monitored": true
                },
                "api_version": "0.0.1",
                "host": "https://cloud.ocis.test/"
            }
        ]
    },
    {
        "name": "ownCloud Test",
        "full_name": "ownCloud Test provider",
        "organization": "ownCloud",
        "domain": "cloud.owncloud.test",
        "homepage": "https://owncloud.test",
        "description": "ownCloud Example cloud storage",
        "services": [
            {
                "endpoint": {
                    "type": {
                        "name": "OCM",
                        "description": "cloud.owncloud.test Open Cloud Mesh API"
                    },
                    "name": "cloud.owncloud.test - OCM API",
                    "path": "https://cloud.owncloud.test/ocm/",
                    "is_monitored": true
                },
                "api_version": "0.0.1",
                "host": "http://cloud.owncloud.test"
            },
            {
                "endpoint": {
                    "type": {
                        "name": "Webdav",
                        "description": "cloud.owncloud.test Webdav API"
                    },
                    "name": "cloud.owncloud.test Example - Webdav API",
                    "path": "https://cloud.owncloud.test/dav/",
                    "is_monitored": true
                },
                "api_version": "0.0.1",
                "host": "https://cloud.owncloud.test/"
            }
        ]
    }
]

Note: the domain must not contain the protocol as it has to match the GOCDB site object domain.

The above federation consists of two instances: cloud.owncloud.test and cloud.ocis.test that can use the Invitation workflow described below to generate, send and accept invitations.

Invitation Workflow

Before sharing a resource with a remote user this user has to be invited by the sharer.

In order to do so a POST request is sent to the generate-invite endpoint of the sciencemesh API. The generated token is passed on to the receiver, who will then use the accept-invite endpoint to accept the invitation. As a result remote users will be added to the ocminvitemanager on both sides. See invitation flow for the according sequence diagram.

The data backend of the ocminvitemanager is configurable. The only supported backend currently is json which stores the data in a json file on disk.

Creating Shares

The below info is outdated as we allow creating federated shares using the graph API. Clients can now discover the available sharing roles and invite federated users using the graph API.

OCM Shares are currently created using the ocs API, just like regular shares. The difference is the share type, which is 6 (ShareTypeFederatedCloudShare) in this case, and a few additional parameters required for identifying the remote user.

See Create share flow for the according sequence diagram.

The data backends of the ocmshareprovider and ocmcore services are configurable. The only supported backend currently is json which stores the data in a json file on disk.

Example Yaml Config

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116


# Autogenerated
# Filename: ocm-config-example.yaml

tracing:
  enabled: false
  type: ""
  endpoint: ""
  collector: ""
log:
  level: ""
  pretty: false
  color: false
  file: ""
debug:
  addr: 127.0.0.1:9281
  token: ""
  pprof: false
  zpages: false
http:
  addr: 127.0.0.1:9280
  protocol: tcp
  prefix: ""
  cors:
    allow_origins:
    - https://localhost:9200
    allow_methods:
    - OPTIONS
    - HEAD
    - GET
    - PUT
    - POST
    - DELETE
    - MKCOL
    - PROPFIND
    - PROPPATCH
    - MOVE
    - COPY
    - REPORT
    - SEARCH
    allow_headers:
    - Origin
    - Accept
    - Content-Type
    - Depth
    - Authorization
    - Ocs-Apirequest
    - If-None-Match
    - If-Match
    - Destination
    - Overwrite
    - X-Request-Id
    - X-Requested-With
    - Tus-Resumable
    - Tus-Checksum-Algorithm
    - Upload-Concat
    - Upload-Length
    - Upload-Metadata
    - Upload-Defer-Length
    - Upload-Expires
    - Upload-Checksum
    - Upload-Offset
    - X-HTTP-Method-Override
    - Cache-Control
    allow_credentials: false
middleware:
  auth:
    credentials_by_user_agent: {}
grpc:
  addr: 127.0.0.1:9282
  tls: null
  protocol: ""
grpc_client_tls: null
service_account:
  service_account_id: ""
  service_account_secret: ""
token_manager:
  jwt_secret: ""
reva:
  address: com.owncloud.api.gateway
  tls:
    mode: ""
    cacert: ""
ocmd:
  prefix: ocm
  expose_recipient_display_name: false
sciencemesh:
  prefix: sciencemesh
  science_mesh_directory_url: ""
ocm_invite_manager:
  driver: json
  drivers:
    json:
      file: /var/lib/ocis/storage/ocm/ocminvites.json
  token_expiration: 24h0m0s
  timeout: 30s
  insecure: false
ocm_provider_authorizer_driver: json
ocm_provider_authorizer_drivers:
  json:
    providers: /etc/ocis/ocmproviders.json
ocm_share_provider:
  driver: json
  drivers:
    json:
      file: /var/lib/ocis/storage/ocm/ocmshares.json
  insecure: false
  webapp_template: ""
ocm_core:
  driver: json
  drivers:
    json:
      file: /var/lib/ocis/storage/ocm/ocmshares.json
ocm_storage_provider:
  insecure: false
  storage_root: /var/lib/ocis/storage/ocm
  data_server_url: http://localhost:9280/data

Environment Variables

Name	Type	Default Value	Description
OCIS_TRACING_ENABLED OCM_TRACING_ENABLED	bool	false	Activates tracing.
OCIS_TRACING_TYPE OCM_TRACING_TYPE	string		The type of tracing. Defaults to ‘’, which is the same as ‘jaeger’. Allowed tracing types are ‘jaeger’ and ’’ as of now.
OCIS_TRACING_ENDPOINT OCM_TRACING_ENDPOINT	string		The endpoint of the tracing agent.
OCIS_TRACING_COLLECTOR OCM_TRACING_COLLECTOR	string		The HTTP endpoint for sending spans directly to a collector, i.e. http://jaeger-collector:14268/api/traces. Only used if the tracing endpoint is unset.
OCIS_LOG_LEVEL OCM_LOG_LEVEL	string		The log level. Valid values are: ‘panic’, ‘fatal’, ’error’, ‘warn’, ‘info’, ‘debug’, ’trace’.
OCIS_LOG_PRETTY OCM_LOG_PRETTY	bool	false	Activates pretty log output.
OCIS_LOG_COLOR OCM_LOG_COLOR	bool	false	Activates colorized log output.
OCIS_LOG_FILE OCM_LOG_FILE	string		The path to the log file. Activates logging to this file if set.
OCM_DEBUG_ADDR	string	127.0.0.1:9281	Bind address of the debug server, where metrics, health, config and debug endpoints will be exposed.
OCM_DEBUG_TOKEN	string		Token to secure the metrics endpoint.
OCM_DEBUG_PPROF	bool	false	Enables pprof, which can be used for profiling.
OCM_DEBUG_ZPAGES	bool	false	Enables zpages, which can be used for collecting and viewing in-memory traces.
OCM_HTTP_ADDR	string	127.0.0.1:9280	The bind address of the HTTP service.
OCM_HTTP_PROTOCOL	string	tcp	The transport protocol of the HTTP service.
OCM_HTTP_PREFIX	string		The path prefix where OCM can be accessed (defaults to /).
OCIS_CORS_ALLOW_ORIGINS OCM_CORS_ALLOW_ORIGINS	[]string	[https://localhost:9200]	A list of allowed CORS origins. See following chapter for more details: Access-Control-Allow-Origin at https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Allow-Origin. See the Environment Variable Types description for more details.
OCIS_CORS_ALLOW_METHODS OCM_CORS_ALLOW_METHODS	[]string	[OPTIONS HEAD GET PUT POST DELETE MKCOL PROPFIND PROPPATCH MOVE COPY REPORT SEARCH]	A list of allowed CORS methods. See following chapter for more details: Access-Control-Request-Method at https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Request-Method. See the Environment Variable Types description for more details.
OCIS_CORS_ALLOW_HEADERS OCM_CORS_ALLOW_HEADERS	[]string	[Origin Accept Content-Type Depth Authorization Ocs-Apirequest If-None-Match If-Match Destination Overwrite X-Request-Id X-Requested-With Tus-Resumable Tus-Checksum-Algorithm Upload-Concat Upload-Length Upload-Metadata Upload-Defer-Length Upload-Expires Upload-Checksum Upload-Offset X-HTTP-Method-Override Cache-Control]	A list of allowed CORS headers. See following chapter for more details: Access-Control-Request-Headers at https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Request-Headers. See the Environment Variable Types description for more details.
OCIS_CORS_ALLOW_CREDENTIALS OCM_CORS_ALLOW_CREDENTIALS	bool	false	Allow credentials for CORS.See following chapter for more details: Access-Control-Allow-Credentials at https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Allow-Credentials.
OCM_GRPC_ADDR	string	127.0.0.1:9282	The bind address of the GRPC service.
OCIS_GRPC_PROTOCOL OCM_GRPC_PROTOCOL	string		The transport protocol of the GRPC service.
OCIS_SERVICE_ACCOUNT_ID OCM_SERVICE_ACCOUNT_ID	string		The ID of the service account the service should use. See the ‘auth-service’ service description for more details.
OCIS_SERVICE_ACCOUNT_SECRET OCM_SERVICE_ACCOUNT_SECRET	string		The service account secret.
OCIS_EVENTS_ENDPOINT OCM_EVENTS_ENDPOINT	string	127.0.0.1:9233	The address of the event system. The event system is the message queuing service. It is used as message broker for the microservice architecture.
OCIS_EVENTS_CLUSTER OCM_EVENTS_CLUSTER	string	ocis-cluster	The clusterID of the event system. The event system is the message queuing service. It is used as message broker for the microservice architecture. Mandatory when using NATS as event system.
OCIS_INSECURE OCM_EVENTS_TLS_INSECURE	bool	false	Whether to verify the server TLS certificates.
OCIS_EVENTS_TLS_ROOT_CA_CERTIFICATE OCM_EVENTS_TLS_ROOT_CA_CERTIFICATE	string		The root CA certificate used to validate the server’s TLS certificate. If provided OCM_EVENTS_TLS_INSECURE will be seen as false.
OCIS_EVENTS_ENABLE_TLS OCM_EVENTS_ENABLE_TLS	bool	false	Enable TLS for the connection to the events broker. The events broker is the ocis service which receives and delivers events between the services.
OCIS_EVENTS_AUTH_USERNAME OCM_EVENTS_AUTH_USERNAME	string		The username to authenticate with the events broker. The events broker is the ocis service which receives and delivers events between the services.
OCIS_EVENTS_AUTH_PASSWORD OCM_EVENTS_AUTH_PASSWORD	string		The password to authenticate with the events broker. The events broker is the ocis service which receives and delivers events between the services.
OCIS_JWT_SECRET OCM_JWT_SECRET	string		The secret to mint and validate jwt tokens.
OCIS_REVA_GATEWAY	string	com.owncloud.api.gateway	The CS3 gateway endpoint.
OCIS_GRPC_CLIENT_TLS_MODE	string		TLS mode for grpc connection to the go-micro based grpc services. Possible values are ‘off’, ‘insecure’ and ‘on’. ‘off’: disables transport security for the clients. ‘insecure’ allows using transport security, but disables certificate verification (to be used with the autogenerated self-signed certificates). ‘on’ enables transport security, including server certificate verification.
OCIS_GRPC_CLIENT_TLS_CACERT	string		Path/File name for the root CA certificate (in PEM format) used to validate TLS server certificates of the go-micro based grpc services.
OCM_OCMD_PREFIX	string	ocm	URL path prefix for the OCMD service. Note that the string must not start with ‘/’.
OCM_OCMD_EXPOSE_RECIPIENT_DISPLAY_NAME	bool	false	Expose the display name of OCM share recipients.
OCM_SCIENCEMESH_PREFIX	string	sciencemesh	URL path prefix for the ScienceMesh service. Note that the string must not start with ‘/’.
OCM_MESH_DIRECTORY_URL	string		URL of the mesh directory service.
OCM_OCM_INVITE_MANAGER_DRIVER	string	json	Driver to be used to persist OCM invites. Supported value is only ‘json’.
OCM_OCM_INVITE_MANAGER_JSON_FILE	string	/var/lib/ocis/storage/ocm/ocminvites.json	Path to the JSON file where OCM invite data will be stored. This file is maintained by the instance and must not be changed manually. If not defined, the root directory derives from $OCIS_BASE_DATA_PATH/storage/ocm.
OCM_OCM_INVITE_MANAGER_TOKEN_EXPIRATION	Duration	24h0m0s	Expiry duration for invite tokens.
OCM_OCM_INVITE_MANAGER_TIMEOUT	Duration	30s	Timeout specifies a time limit for requests made to OCM endpoints.
OCM_OCM_INVITE_MANAGER_INSECURE	bool	false	Disable TLS certificate validation for the OCM connections. Do not set this in production environments.
SHARING_OCM_PROVIDER_AUTHORIZER_DRIVER	string	json	Driver to be used to persist ocm invites. Supported value is only ‘json’.
OCM_OCM_PROVIDER_AUTHORIZER_PROVIDERS_FILE	string	/etc/ocis/ocmproviders.json	Path to the JSON file where ocm invite data will be stored. Defaults to $OCIS_CONFIG_DIR/ocmproviders.json.
OCM_OCM_SHARE_PROVIDER_DRIVER	string	json	Driver to be used for the OCM share provider. Supported value is only ‘json’.
OCM_OCM_SHAREPROVIDER_JSON_FILE	string	/var/lib/ocis/storage/ocm/ocmshares.json	Path to the JSON file where OCM share data will be stored. If not defined, the root directory derives from $OCIS_BASE_DATA_PATH/storage.
OCM_OCM_SHARE_PROVIDER_INSECURE	bool	false	Disable TLS certificate validation for the OCM connections. Do not set this in production environments.
OCM_WEBAPP_TEMPLATE	string		Template for the webapp url.
OCM_OCM_CORE_DRIVER	string	json	Driver to be used for the OCM core. Supported value is only ‘json’.
OCM_OCM_CORE_JSON_FILE	string	/var/lib/ocis/storage/ocm/ocmshares.json	Path to the JSON file where OCM share data will be stored. If not defined, the root directory derives from $OCIS_BASE_DATA_PATH/storage.
OCM_OCM_STORAGE_PROVIDER_INSECURE	bool	false	Disable TLS certificate validation for the OCM connections. Do not set this in production environments.
OCM_OCM_STORAGE_PROVIDER_STORAGE_ROOT	string	/var/lib/ocis/storage/ocm	Directory where the ocm storage provider persists its data like tus upload info files.
OCM_OCM_STORAGE_DATA_SERVER_URL	string	http://localhost:9280/data	URL of the data server, needs to be reachable by the data gateway provided by the frontend service or the user if directly exposed.

OCM