Proxy Service Configuration

Introduction

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 set up in front like with an external reverse proxy.

See the Developer Documentation for details if you want to write your own extensions and need to change or add routes to endpoints.

Default Values

  • The proxy listens on port 9200 by default.

Authentication

The following request authentication schemes are implemented:

  • Basic Auth (Only use in development, never in production setups!)

  • OpenID Connect

  • Signed URL

  • Public Share Token

Automatic Quota Assignments

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>

Automatic Role Assignments

When users log in, they 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) selects which mechanism to use for the automatic role assignment.

  • When PROXY_ROLE_ASSIGNMENT_DRIVER is set to default, all users that do not have a role assigned at the time of their 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 claim ocisRoles and so on.

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

    An 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 log in.

    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

Recommendations for Production Deployments

  • The proxy service is the only service communicating to the outside and therefore needs the usual protection 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.

  • In a production deployment, you want to have basic authentication (PROXY_ENABLE_BASIC_AUTH) disabled which is the default state. You should also set up 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.

Caching

Important, also see section Presigned Urls below.

The proxy service can use a configured store via the global OCIS_CACHE_STORE environment variable.

Note that for each global environment variable, a service-based one might be available additionally. For precedences see Environment Variable Notes. Check the configuration section below. Supported stores are:

Store Type Description

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

(deprecated) Advanced in-memory store allowing max size.

redis

(deprecated) Stores data in a configured Redis cluster.

etcd

(deprecated) Stores data in a configured etcd cluster.

nats-js

(deprecated) Stores data using the key-value-store feature of NATS JetStream.

Other store types may work but are currently not supported.

The proxy service can only be scaled if not using the memory store and the stores are configured identically over all instances!
If you have used one of the deprecated stores of a former version, you should reconfigure to use 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.

    • Authentication can be added, if configured, via OCIS_CACHE_AUTH_USERNAME and OCIS_CACHE_AUTH_PASSWORD.

    • It is possible to set OCIS_CACHE_DISABLE_PERSISTENCE to instruct nats to not persist cache data on disc.

Presigned Urls

Important, also see section caching above.

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

The following stores can be configured via the OCS_PRESIGNEDURL_SIGNING_KEYS_STORE environment variable:

  • 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 deprecated Infinite Scale store service.
    Requires setting OCS_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 proxy service.

Store specific notes:

  • When using redis-sentinel
    The Redis master to use is configured via e.g. OCS_PRESIGNEDURL_SIGNING_KEYS_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 PROXY_PRESIGNEDURL_SIGNING_KEYS_STORE_NODES to the same value as OCS_PRESIGNEDURL_SIGNING_KEYS_STORE_NODES. That way the proxy service uses the same nats instance as the ocs service.

  • When using ocisstoreservice
    The OCS_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.

Special Settings

When using the Infinite Scale IDP service instead of an external IDP:

  • Use the environment variable OCIS_URL to define how Infinite Scale can be accessed; mandatory is the use of 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 Infinite Scale is not secured. If set to true, you must provide certificates.

Metrics

For details on monitoring see the Metrics for Prometheus documentation.

Configuration

Environment Variables

The proxy service is configured via the following environment variables. Read the Environment Variable Types documentation for important details.

  • master

Environment variables for the proxy service
Name Type Default Value Description

OCIS_TRACING_ENABLED
PROXY_TRACING_ENABLED

bool

false

Activates tracing.

OCIS_TRACING_TYPE
PROXY_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
PROXY_TRACING_ENDPOINT

string

The endpoint of the tracing agent.

OCIS_TRACING_COLLECTOR
PROXY_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
PROXY_LOG_LEVEL

string

The log level. Valid values are: 'panic', 'fatal', 'error', 'warn', 'info', 'debug', 'trace'.

OCIS_LOG_PRETTY
PROXY_LOG_PRETTY

bool

false

Activates pretty log output.

OCIS_LOG_COLOR
PROXY_LOG_COLOR

bool

false

Activates colorized log output.

OCIS_LOG_FILE
PROXY_LOG_FILE

string

The path to the log file. Activates logging to this file if set.

PROXY_DEBUG_ADDR

string

127.0.0.1:9205

Bind address of the debug server, where metrics, health, config and debug endpoints will be exposed.

PROXY_DEBUG_TOKEN

string

Token to secure the metrics endpoint.

PROXY_DEBUG_PPROF

bool

false

Enables pprof, which can be used for profiling.

PROXY_DEBUG_ZPAGES

bool

false

Enables zpages, which can be used for collecting and viewing in-memory traces.

PROXY_HTTP_ADDR

string

0.0.0.0:9200

The bind address of the HTTP service.

PROXY_HTTP_ROOT

string

/

Subdirectory that serves as the root for this HTTP service.

PROXY_TRANSPORT_TLS_CERT

string

/var/lib/ocis/proxy/server.crt

Path/File name of the TLS server certificate (in PEM format) for the external http services. If not defined, the root directory derives from $OCIS_BASE_DATA_PATH:/proxy.

PROXY_TRANSPORT_TLS_KEY

string

/var/lib/ocis/proxy/server.key

Path/File name for the TLS certificate key (in PEM format) for the server certificate to use for the external http services. If not defined, the root directory derives from $OCIS_BASE_DATA_PATH:/proxy.

PROXY_TLS

bool

true

Enable/Disable HTTPS for external HTTP services. Must be set to 'true' if the built-in IDP service an no reverse proxy is used. See the text description for details.

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.

OCIS_URL
OCIS_OIDC_ISSUER
PROXY_OIDC_ISSUER

string

https://localhost:9200

URL of the OIDC issuer. It defaults to URL of the builtin IDP.

OCIS_INSECURE
PROXY_OIDC_INSECURE

bool

false

Disable TLS certificate validation for connections to the IDP. Note that this is not recommended for production environments.

PROXY_OIDC_ACCESS_TOKEN_VERIFY_METHOD

string

jwt

Sets how OIDC access tokens should be verified. Possible values are 'none' and 'jwt'. When using 'none', no special validation apart from using it for accessing the IPD’s userinfo endpoint will be done. When using 'jwt', it tries to parse the access token as a jwt token and verifies the signature using the keys published on the IDP’s 'jwks_uri'.

PROXY_OIDC_SKIP_USER_INFO

bool

false

Do not look up user claims at the userinfo endpoint and directly read them from the access token. Incompatible with 'PROXY_OIDC_ACCESS_TOKEN_VERIFY_METHOD=none'.

OCIS_CACHE_STORE
PROXY_OIDC_USERINFO_CACHE_STORE

string

memory

The type of the cache store. Supported values are: 'memory', 'redis-sentinel', 'nats-js-kv', 'noop'. See the text description for details.

OCIS_CACHE_STORE_NODES
PROXY_OIDC_USERINFO_CACHE_STORE_NODES

[]string

[127.0.0.1:9233]

A list of nodes to access the configured store. This has no effect when 'memory' or 'ocmem' stores are configured. Note that the behaviour how nodes are used is dependent on the library of the configured store. See the Environment Variable Types description for more details.

OCIS_CACHE_DATABASE

string

cache-userinfo

The database name the configured store should use.

PROXY_OIDC_USERINFO_CACHE_TABLE

string

The database table the store should use.

OCIS_CACHE_TTL
PROXY_OIDC_USERINFO_CACHE_TTL

Duration

10s

Default time to live for user info in the user info cache. Only applied when access tokens has no expiration. See the Environment Variable Types description for more details.

OCIS_CACHE_SIZE
PROXY_OIDC_USERINFO_CACHE_SIZE

int

0

The maximum quantity of items in the user info cache. Only applies when store type 'ocmem' is configured. Defaults to 512 which is derived from the ocmem package though not explicitly set as default.

OCIS_CACHE_DISABLE_PERSISTENCE
PROXY_OIDC_USERINFO_CACHE_DISABLE_PERSISTENCE

bool

false

Disables persistence of the cache. Only applies when store type 'nats-js-kv' is configured. Defaults to false.

OCIS_CACHE_AUTH_USERNAME
PROXY_OIDC_USERINFO_CACHE_AUTH_USERNAME

string

The username to authenticate with the cache. Only applies when store type 'nats-js-kv' is configured.

OCIS_CACHE_AUTH_PASSWORD
PROXY_OIDC_USERINFO_CACHE_AUTH_PASSWORD

string

The password to authenticate with the cache. Only applies when store type 'nats-js-kv' is configured.

PROXY_OIDC_JWKS_REFRESH_INTERVAL

uint64

60

The interval for refreshing the JWKS (JSON Web Key Set) in minutes in the background via a new HTTP request to the IDP.

PROXY_OIDC_JWKS_REFRESH_TIMEOUT

uint64

10

The timeout in seconds for an outgoing JWKS request.

PROXY_OIDC_JWKS_REFRESH_RATE_LIMIT

uint64

60

Limits the rate in seconds at which refresh requests are performed for unknown keys. This is used to prevent malicious clients from imposing high network load on the IDP via ocis.

PROXY_OIDC_JWKS_REFRESH_UNKNOWN_KID

bool

true

If set to 'true', the JWKS refresh request will occur every time an unknown KEY ID (KID) is seen. Always set a 'refresh_limit' when enabling this.

PROXY_OIDC_REWRITE_WELLKNOWN

bool

false

Enables rewriting the /.well-known/openid-configuration to the configured OIDC issuer. Needed by the Desktop Client, Android Client and iOS Client to discover the OIDC provider.

OCIS_SERVICE_ACCOUNT_ID
PROXY_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
PROXY_SERVICE_ACCOUNT_SECRET

string

The service account secret.

PROXY_ROLE_ASSIGNMENT_DRIVER

string

default

The mechanism that should be used to assign roles to user upon login. Supported values: 'default' or 'oidc'. 'default' will assign the role 'user' to users which don’t have a role assigned at the time they login. 'oidc' will assign the role based on the value of a claim (configured via PROXY_ROLE_ASSIGNMENT_OIDC_CLAIM) from the users OIDC claims.

PROXY_ROLE_ASSIGNMENT_OIDC_CLAIM

string

roles

The OIDC claim used to create the users role assignment.

PROXY_ENABLE_PRESIGNEDURLS

bool

true

Allow OCS to get a signing key to sign requests.

OCIS_CACHE_STORE
PROXY_PRESIGNEDURL_SIGNING_KEYS_STORE

string

nats-js-kv

The type of the signing key store. Supported values are: 'redis-sentinel', 'nats-js-kv' and 'ocisstoreservice' (deprecated). See the text description for details.

OCIS_CACHE_STORE_NODES
PROXY_PRESIGNEDURL_SIGNING_KEYS_STORE_NODES

[]string

[127.0.0.1:9233]

A list of nodes to access the configured store. Note that the behaviour how nodes are used is dependent on the library of the configured store. See the Environment Variable Types description for more details.

OCIS_CACHE_TTL
PROXY_PRESIGNEDURL_SIGNING_KEYS_STORE_TTL

Duration

12h0m0s

Default time to live for signing keys. See the Environment Variable Types description for more details.

OCIS_CACHE_DISABLE_PERSISTENCE
PROXY_PRESIGNEDURL_SIGNING_KEYS_STORE_DISABLE_PERSISTENCE

bool

true

Disables persistence of the store. Only applies when store type 'nats-js-kv' is configured. Defaults to true.

OCIS_CACHE_AUTH_USERNAME
PROXY_PRESIGNEDURL_SIGNING_KEYS_STORE_AUTH_USERNAME

string

The username to authenticate with the store. Only applies when store type 'nats-js-kv' is configured.

OCIS_CACHE_AUTH_PASSWORD
PROXY_PRESIGNEDURL_SIGNING_KEYS_STORE_AUTH_PASSWORD

string

The password to authenticate with the store. Only applies when store type 'nats-js-kv' is configured.

PROXY_ACCOUNT_BACKEND_TYPE

string

cs3

Account backend the PROXY service should use. Currently only 'cs3' is possible here.

PROXY_USER_OIDC_CLAIM

string

preferred_username

The name of an OpenID Connect claim that is used for resolving users with the account backend. The value of the claim must hold a per user unique, stable and non re-assignable identifier. The availability of claims depends on your Identity Provider. There are common claims available for most Identity providers like 'email' or 'preferred_username' but you can also add your own claim.

PROXY_USER_CS3_CLAIM

string

username

The name of a CS3 user attribute (claim) that should be mapped to the 'user_oidc_claim'. Supported values are 'username', 'mail' and 'userid'.

OCIS_MACHINE_AUTH_API_KEY
PROXY_MACHINE_AUTH_API_KEY

string

Machine auth API key used to validate internal requests necessary to access resources from other services.

PROXY_AUTOPROVISION_ACCOUNTS

bool

false

Set this to 'true' to automatically provision users that do not yet exist in the users service on-demand upon first sign-in. To use this a write-enabled libregraph user backend needs to be setup an running.

PROXY_ENABLE_BASIC_AUTH

bool

false

Set this to true to enable 'basic authentication' (username/password).

PROXY_INSECURE_BACKENDS

bool

false

Disable TLS certificate validation for all HTTP backend connections.

PROXY_HTTPS_CACERT

string

Path/File for the root CA certificate used to validate the server’s TLS certificate for https enabled backend services.

PROXY_POLICIES_QUERY

string

Defines the 'Complete Rules' variable defined in the rego rule set this step uses for its evaluation. Rules default to deny if the variable was not found.

YAML Example

  • master

# 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: ""