Proxy

The proxy service is an API-Gateway for the ownCloud Infinite Scale microservices. Every HTTP request goes through this service. Authentication, logging and other preprocessing of requests also happens here. Mechanisms like request rate limiting or intrusion prevention are not included in the proxy service and must be setup in front like with an external reverse proxy.

The proxy service is the only service communicating to the outside and needs therefore usual protections against DDOS, Slow Loris or other attack vectors. All other services are not exposed to the outside, but also need protective measures when it comes to distributed setups like when using container orchestration over various physical servers.

• Authentication
• Configuring Routes
• Automatic Quota Assignments
• Automatic Role Assignments
• Recommendations for Production Deployments
• Caching
• Presigned Urls
• Special Settings
• Metrics
  • 1) Single Process Mode-single-process-mode)
  • 2) Standalone Mode-standalone-mode)
  • Available Metrics
  • Prometheus Configuration
• Example Yaml Config

The following request authentication schemes are implemented:

• Basic Auth (Only use in development, never in production setups!)
• OpenID Connect
• Signed URL
• Public Share Token

The proxy handles routing to all endpoints that ocis offers. The currently availabe default routes can be found in the code. Changing or adding routes can be necessary when writing own ocis extensions.

Due to the complexity when defining routes, these can only be defined in the yaml file but not via environment variables.

For overwriting default routes, use the following yaml example:

policies:
  - name: ocis
    routes:
      - endpoint: /
        service: com.owncloud.web.web
      - endpoint: /dav/
        service: com.owncloud.web.ocdav

For adding additional routes to the default routes use:

additional_policies:
  - name: ocis
    routes:
      - endpoint: /custom/endpoint
        service: com.owncloud.custom.custom

A route has the following configurable parameters:

endpoint: ""       # the url that should be routed
service: ""        # the service the url should be routed to
unprotected: false # with false (default), calling the endpoint requires authorization.
                   # with true, anyone can call the endpoint without authorisation.

It is possible to automatically assign a specific quota to new users depending on their role. To do this, you need to configure a mapping between roles defined by their ID and the quota in bytes. The assignment can only be done via a yaml configuration and not via environment variables. See the following proxy.yaml config snippet for a configuration example.

role_quotas:
    <role ID1>: <quota1>
    <role ID2>: <quota2>

When users login, they do automatically get a role assigned. The automatic role assignment can be configured in different ways. The PROXY_ROLE_ASSIGNMENT_DRIVER environment variable (or the driver setting in the role_assignment section of the configuration file select which mechanism to use for the automatic role assignment.

When set to default, all users which do not have a role assigned at the time for the first login will get the role ‘user’ assigned. (This is also the default behavior if PROXY_ROLE_ASSIGNMENT_DRIVER is unset.

When PROXY_ROLE_ASSIGNMENT_DRIVER is set to oidc the role assignment for a user will happen based on the values of an OpenID Connect Claim of that user. The name of the OpenID Connect Claim to be used for the role assignment can be configured via the PROXY_ROLE_ASSIGNMENT_OIDC_CLAIM environment variable. It is also possible to define a mapping of claim values to role names defined in ownCloud Infinite Scale via a yaml configuration. See the following proxy.yaml snippet for an example.

role_assignment:
    driver: oidc
    oidc_role_mapper:
        role_claim: ocisRoles
        role_mapping:
            - role_name: admin
              claim_value: myAdminRole
            - role_name: spaceadmin
              claim_value: mySpaceAdminRole
            - role_name: user
              claim_value: myUserRole
            - role_name: guest
              claim_value: myGuestRole

This would assign the role admin to users with the value myAdminRole in the claim ocisRoles. The role user to users with the values myUserRole in the claims ocisRoles and so on.

Claim values that are not mapped to a specific ownCloud Infinite Scale role will be ignored.

Note: An ownCloud Infinite Scale user can only have a single role assigned. If the configured role_mapping and a user’s claim values result in multiple possible roles for a user, the order in which the role mappings are defined in the configuration is important. The first role in the role_mappings where the claim_value matches a value from the user’s roles claim will be assigned to the user. So if e.g. a user’s ocisRoles claim has the values myUserRole and mySpaceAdminRole that user will get the ocis role spaceadmin assigned (because spaceadmin appears before user in the above sample configuration).

If a user’s claim values don’t match any of the configured role mappings an error will be logged and the user will not be able to login.

The default role_claim (or PROXY_ROLE_ASSIGNMENT_OIDC_CLAIM) is roles. The default role_mapping is:

- role_name: admin
  claim_value: ocisAdmin
- role_name: spaceadmin
  claim_value: ocisSpaceAdmin
- role_name: user
  claim_value: ocisUser
- role_name: guest
  claim_value: ocisGuest

In a production deployment, you want to have basic authentication (PROXY_ENABLE_BASIC_AUTH) disabled which is the default state. You also want to setup a firewall to only allow requests to the proxy service or the reverse proxy if you have one. Requests to the other services should be blocked by the firewall.

The proxy service can use a configured store via PROXY_OIDC_USERINFO_CACHE_STORE. Possible stores are:

• memory: Basic in-memory store and the default.
• redis-sentinel: Stores data in a configured Redis Sentinel cluster.
• nats-js-kv: Stores data using key-value-store feature of nats jetstream
• noop: Stores nothing. Useful for testing. Not recommended in production environments.
• ocmem: Advanced in-memory store allowing max size. (deprecated)
• redis: Stores data in a configured Redis cluster. (deprecated)
• etcd: Stores data in a configured etcd cluster. (deprecated)
• nats-js: Stores data using object-store feature of nats jetstream (deprecated)

Other store types may work but are not supported currently.

Note: The service can only be scaled if not using memory store and the stores are configured identically over all instances!

Note that if you have used one of the deprecated stores, you should reconfigure to one of the supported ones as the deprecated stores will be removed in a later version.

Store specific notes:

• When using redis-sentinel, the Redis master to use is configured via e.g. OCIS_CACHE_STORE_NODES in the form of <sentinel-host>:<sentinel-port>/<redis-master> like 10.10.0.200:26379/mymaster.
• When using nats-js-kv it is recommended to set OCIS_CACHE_STORE_NODES to the same value as OCIS_EVENTS_ENDPOINT. That way the cache uses the same nats instance as the event bus.
• When using the nats-js-kv store, it is possible to set OCIS_CACHE_DISABLE_PERSISTENCE to instruct nats to not persist cache data on disc.

To authenticate presigned URLs the proxy service needs to read signing keys from a store that is populated by the ocs service. Possible stores are:

• nats-js-kv: Stores data using key-value-store feature of nats jetstream
• redis-sentinel: Stores data in a configured Redis Sentinel cluster.
• ocisstoreservice: Stores data in the legacy ocis store service. Requires setting PROXY_PRESIGNEDURL_SIGNING_KEYS_STORE_NODES to com.owncloud.api.store.

The memory or ocmem stores cannot be used as they do not share the memory from the ocs service signing key memory store, even in a single process.

Make sure to configure the same store in the ocs service.

Store specific notes:

• When using redis-sentinel, the Redis master to use is configured via e.g. OCIS_CACHE_STORE_NODES in the form of <sentinel-host>:<sentinel-port>/<redis-master> like 10.10.0.200:26379/mymaster.
• When using nats-js-kv it is recommended to set OCS_PRESIGNEDURL_SIGNING_KEYS_STORE_NODES to the same value as PROXY_PRESIGNEDURL_SIGNING_KEYS_STORE_NODES. That way the ocs uses the same nats instance as the proxy service.
• When using the nats-js-kv store, it is possible to set PROXY_PRESIGNEDURL_SIGNING_KEYS_STORE_DISABLE_PERSISTENCE to instruct nats to not persist signing key data on disc.
• When using ocisstoreservice the PROXY_PRESIGNEDURL_SIGNING_KEYS_STORE_NODES must be set to the service name com.owncloud.api.store. It does not support TTL and stores the presigning keys indefinitely. Also, the store service needs to be started.

When using the ocis IDP service instead of an external IDP:

• Use the environment variable OCIS_URL to define how ocis can be accessed, mandatory use https as protocol for the URL.
• If no reverse proxy is set up, the PROXY_TLS environment variable must be set to true because the embedded libreConnect shipped with the IDP service has a hard check if the connection is on TLS and uses the HTTPS protocol. If this mismatches, an error will be logged and no connection from the client can be established.
• PROXY_TLS can be set to false if a reverse proxy is used and the https connection is terminated at the reverse proxy. When setting to false, the communication between the reverse proxy and ocis is not secured. If set to true, you must provide certificates.

The proxy service in ocis has the ability to expose metrics in the prometheus format. The metrics are exposed on the /metrics endpoint. There are two ways to run the ocis proxy service which has an impact on the number of metrics exposed.

In the single process mode, all ocis services are running inside a single process. This is the default mode when using the ocis server command to start the services. In this mode, the proxy service exposes metrics about the proxy service itself and about the ocis services it is proxying. This is due to the nature of the prometheus registry which is a singleton. The metrics exposed by the proxy service itself are prefixed with ocis_proxy_ and the metrics exposed by other ocis services are prefixed with ocis_<service-name>_.

In this mode, the proxy service only exposes its own metrics. The metrics of the other ocis services are exposed on their own metrics endpoints.

The following metrics are exposed by the proxy service:

The following is an example prometheus configuration for the single process mode. It assumes that the proxy debug address is configured to bind on all interfaces PROXY_DEBUG_ADDR=0.0.0.0:9205 and that the proxy is available via the ocis service name (typically in docker-compose). The prometheus service detects the /metrics endpoint automatically and scrapes it every 15 seconds.

global:
  scrape_interval: 15s
scrape_configs:
  - job_name: ocis_proxy
    static_configs:
    - targets: ["ocis:9205"]

  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
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182

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

tracing:
  enabled: false
  type: ""
  endpoint: ""
  collector: ""
log:
  level: ""
  pretty: false
  color: false
  file: ""
debug:
  addr: 127.0.0.1:9205
  token: ""
  pprof: false
  zpages: false
http:
  addr: 0.0.0.0:9200
  root: /
  tls_cert: /var/lib/ocis/proxy/server.crt
  tls_key: /var/lib/ocis/proxy/server.key
  tls: true
reva:
  address: com.owncloud.api.gateway
  tls:
    mode: ""
    cacert: ""
grpc_client_tls: null
role_quotas: {}
policies:
- name: ocis
  routes:
  - endpoint: /
    service: com.owncloud.web.web
    unprotected: true
  - endpoint: /.well-known/webfinger
    service: com.owncloud.web.webfinger
    unprotected: true
  - endpoint: /.well-known/openid-configuration
    service: com.owncloud.web.idp
    unprotected: true
  - endpoint: /branding/logo
    service: com.owncloud.web.web
  - endpoint: /konnect/
    service: com.owncloud.web.idp
    unprotected: true
  - endpoint: /signin/
    service: com.owncloud.web.idp
    unprotected: true
  - endpoint: /archiver
    service: com.owncloud.web.frontend
  - endpoint: /ocs/v2.php/apps/notifications/api/v1/notifications/sse
    service: com.owncloud.sse.sse
  - endpoint: /ocs/v2.php/apps/notifications/api/v1/notifications
    service: com.owncloud.userlog.userlog
  - type: regex
    endpoint: /ocs/v[12].php/cloud/user/signing-key
    service: com.owncloud.web.ocs
  - type: regex
    endpoint: /ocs/v[12].php/config
    service: com.owncloud.web.frontend
    unprotected: true
  - endpoint: /sciencemesh/
    service: com.owncloud.web.ocm
  - endpoint: /ocm/
    service: com.owncloud.web.ocm
  - endpoint: /ocs/
    service: com.owncloud.web.frontend
  - type: query
    endpoint: /remote.php/?preview=1
    service: com.owncloud.web.webdav
  - type: regex
    method: REPORT
    endpoint: (/remote.php)?/(web)?dav
    service: com.owncloud.web.webdav
  - type: query
    endpoint: /dav/?preview=1
    service: com.owncloud.web.webdav
  - type: query
    endpoint: /webdav/?preview=1
    service: com.owncloud.web.webdav
  - endpoint: /remote.php/
    service: com.owncloud.web.ocdav
  - endpoint: /dav/
    service: com.owncloud.web.ocdav
  - endpoint: /webdav/
    service: com.owncloud.web.ocdav
  - endpoint: /status
    service: com.owncloud.web.ocdav
    unprotected: true
  - endpoint: /status.php
    service: com.owncloud.web.ocdav
    unprotected: true
  - endpoint: /index.php/
    service: com.owncloud.web.ocdav
  - endpoint: /apps/
    service: com.owncloud.web.ocdav
  - endpoint: /data
    service: com.owncloud.web.frontend
    unprotected: true
  - endpoint: /app/list
    service: com.owncloud.web.frontend
    unprotected: true
  - endpoint: /app/
    service: com.owncloud.web.frontend
  - endpoint: /graph/v1.0/invitations
    service: com.owncloud.graph.invitations
  - endpoint: /graph/
    service: com.owncloud.graph.graph
  - endpoint: /api/v0/settings
    service: com.owncloud.web.settings
additional_policies: []
oidc:
  issuer: https://localhost:9200
  insecure: false
  access_token_verify_method: jwt
  skip_user_info: false
  user_info_cache:
    store: memory
    addresses:
    - 127.0.0.1:9233
    database: cache-userinfo
    table: ""
    ttl: 10s
    size: 0
    disable_persistence: false
    username: ""
    password: ""
  jwks:
    refresh_interval: 60
    refresh_timeout: 10
    refresh_limit: 60
    refresh_unknown_kid: true
  rewrite_well_known: false
service_account:
  service_account_id: ""
  service_account_secret: ""
role_assignment:
  driver: default
  oidc_role_mapper:
    role_claim: roles
    role_mapping:
    - role_name: admin
      claim_value: ocisAdmin
    - role_name: spaceadmin
      claim_value: ocisSpaceAdmin
    - role_name: user
      claim_value: ocisUser
    - role_name: user-light
      claim_value: ocisGuest
policy_selector:
  static:
    policy: ocis
  claims: null
  regex: null
pre_signed_url:
  allowed_http_methods:
  - GET
  enabled: true
  signing_keys:
    store: nats-js-kv
    addresses:
    - 127.0.0.1:9233
    ttl: 12h0m0s
    disable_persistence: true
    username: ""
    password: ""
account_backend: cs3
user_oidc_claim: preferred_username
user_cs3_claim: username
machine_auth_api_key: ""
auto_provision_accounts: false
enable_basic_auth: false
insecure_backends: false
backend_https_cacert: ""
auth_middleware:
  credentials_by_user_agent: {}
policies_middleware:
  query: ""
csp_config_file_location: ""