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.

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

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.

Configuration

Environment Variables

The proxy extension is configured via the following environment variables:

  • latest

  • 2.0.0

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

~/.ocis/proxy/server.crt

Path/File name of the TLS server certificate (in PEM format) for the external http services.

PROXY_TRANSPORT_TLS_KEY

string

~/.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.

PROXY_TLS

bool

true

Enable/Disable HTTPS for the external HTTP services.

REVA_GATEWAY

string

127.0.0.1:9142

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 to use transport security, but disables certificate verification (to be used with the autogenerated self-signed certificates). 'on' enables transport security, including server ceritificate 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_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 to use transport security, but disables certificate verification (to be used with the autogenerated self-signed certificates). 'on' enables transport security, including server ceritificate 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_USERINFO_CACHE_SIZE

int

1024

Cache size for OIDC user info.

PROXY_OIDC_USERINFO_CACHE_TTL

int

10

Max TTL in seconds for the OIDC user info cache.

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_JWT_SECRET
PROXY_JWT_SECRET

string

The secret to mint and validate JWT tokens.

PROXY_ENABLE_PRESIGNEDURLS

bool

true

Allow OCS to get a signing key to sign requests.

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 should be used for resolving users with the account backend. Currently defaults to 'email'.

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.

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

~/.ocis/proxy/server.crt

Path/File name of the TLS server certificate (in PEM format) for the external http services.

PROXY_TRANSPORT_TLS_KEY

string

~/.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.

PROXY_TLS

bool

true

Enable/Disable HTTPS for the external HTTP services.

REVA_GATEWAY

string

127.0.0.1:9142

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 to use transport security, but disables certificate verification (to be used with the autogenerated self-signed certificates). 'on' enables transport security, including server ceritificate 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_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 to use transport security, but disables certificate verification (to be used with the autogenerated self-signed certificates). 'on' enables transport security, including server ceritificate 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_USERINFO_CACHE_SIZE

int

1024

Cache size for OIDC user info.

PROXY_OIDC_USERINFO_CACHE_TTL

int

10

Max TTL in seconds for the OIDC user info cache.

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_JWT_SECRET
PROXY_JWT_SECRET

string

The secret to mint and validate JWT tokens.

PROXY_ENABLE_PRESIGNEDURLS

bool

true

Allow OCS to get a signing key to sign requests.

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 should be used for resolving users with the account backend. Currently defaults to 'email'.

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.

YAML Example

  • latest

  • 2.0.0

# 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: ~/.ocis/proxy/server.crt
  tls_key: ~/.ocis/proxy/server.key
  tls: true
reva:
  address: 127.0.0.1:9142
  tls:
    mode: ""
    cacert: ""
grpc_client_tls:
  mode: ""
  cacert: ""
policies:
- name: ocis
  routes:
  - endpoint: /
    service: com.owncloud.web.web
    unprotected: true
  - endpoint: /.well-known/
    service: com.owncloud.web.idp
    unprotected: true
  - 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
  - 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: /ocs/
    service: com.owncloud.web.frontend
  - type: query
    endpoint: /remote.php/?preview=1
    service: com.owncloud.web.webdav
  - method: REPORT
    endpoint: /remote.php/dav/
    service: com.owncloud.web.webdav
  - method: REPORT
    endpoint: /remote.php/webdav
    service: com.owncloud.web.webdav
  - method: REPORT
    endpoint: /dav/spaces
    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/
    service: com.owncloud.graph.graph
  - endpoint: /api/v0/settings
    service: com.owncloud.web.settings
  - endpoint: /settings.js
    service: com.owncloud.web.settings
    unprotected: true
oidc:
  issuer: https://localhost:9200
  insecure: false
  access_token_verify_method: jwt
  user_info_cache:
    size: 1024
    ttl: 10
  jwks:
    refresh_interval: 60
    refresh_timeout: 10
    refresh_limit: 60
    refresh_unknown_kid: true
  rewrite_well_known: false
token_manager:
  jwt_secret: ""
policy_selector:
  static:
    policy: ocis
  claims: null
  regex: null
pre_signed_url:
  allowed_http_methods:
  - GET
  enabled: true
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: {}
# 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: ~/.ocis/proxy/server.crt
  tls_key: ~/.ocis/proxy/server.key
  tls: true
reva:
  address: 127.0.0.1:9142
  tls:
    mode: ""
    cacert: ""
grpc_client_tls:
  mode: ""
  cacert: ""
policies:
- name: ocis
  routes:
  - endpoint: /
    service: com.owncloud.web.web
    unprotected: true
  - endpoint: /.well-known/
    service: com.owncloud.web.idp
    unprotected: true
  - 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
  - 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: /ocs/
    service: com.owncloud.web.frontend
  - type: query
    endpoint: /remote.php/?preview=1
    service: com.owncloud.web.webdav
  - method: REPORT
    endpoint: /remote.php/dav/
    service: com.owncloud.web.webdav
  - method: REPORT
    endpoint: /remote.php/webdav
    service: com.owncloud.web.webdav
  - method: REPORT
    endpoint: /dav/spaces
    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/
    service: com.owncloud.graph.graph
  - endpoint: /api/v0/settings
    service: com.owncloud.web.settings
  - endpoint: /settings.js
    service: com.owncloud.web.settings
    unprotected: true
oidc:
  issuer: https://localhost:9200
  insecure: false
  access_token_verify_method: jwt
  user_info_cache:
    size: 1024
    ttl: 10
  jwks:
    refresh_interval: 60
    refresh_timeout: 10
    refresh_limit: 60
    refresh_unknown_kid: true
  rewrite_well_known: false
token_manager:
  jwt_secret: ""
policy_selector:
  static:
    policy: ocis
  claims: null
  regex: null
pre_signed_url:
  allowed_http_methods:
  - GET
  enabled: true
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: {}