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.
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 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:
admin: myAdminRole
user: myUserRole
spaceadmin: mySpaceAdminRole
guest: 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.
Note: 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, 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 role_mapping
is:
admin: ocisAdmin
user: ocisUser
spaceadmin: ocisSpaceAdmin
guest: 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.
Configuration
Environment Variables
The proxy
service is configured via the following environment variables:
Name | Type | Default Value | Description |
---|---|---|---|
|
bool |
false |
Activates tracing. |
|
string |
|
The type of tracing. Defaults to "", which is the same as "jaeger". Allowed tracing types are "jaeger" and "" as of now. |
|
string |
|
The endpoint of the tracing agent. |
|
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. |
|
string |
|
The log level. Valid values are: "panic", "fatal", "error", "warn", "info", "debug", "trace". |
|
bool |
false |
Activates pretty log output. |
|
bool |
false |
Activates colorized log output. |
|
string |
|
The path to the log file. Activates logging to this file if set. |
|
string |
127.0.0.1:9205 |
Bind address of the debug server, where metrics, health, config and debug endpoints will be exposed. |
|
string |
|
Token to secure the metrics endpoint. |
|
bool |
false |
Enables pprof, which can be used for profiling. |
|
bool |
false |
Enables zpages, which can be used for collecting and viewing in-memory traces. |
|
string |
0.0.0.0:9200 |
The bind address of the HTTP service. |
|
string |
/ |
Subdirectory that serves as the root for this HTTP service. |
|
string |
~/.ocis/proxy/server.crt |
Path/File name of the TLS server certificate (in PEM format) for the external http services. If not definied, the root directory derives from $OCIS_BASE_DATA_PATH:/proxy. |
|
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. If not definied, the root directory derives from $OCIS_BASE_DATA_PATH:/proxy. |
|
bool |
true |
Enable/Disable HTTPS for the external HTTP services. |
|
string |
127.0.0.1:9142 |
The CS3 gateway endpoint. |
|
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. |
|
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. |
|
string |
https://localhost:9200 |
URL of the OIDC issuer. It defaults to URL of the builtin IDP. |
|
bool |
false |
Disable TLS certificate validation for connections to the IDP. Note that this is not recommended for production environments. |
|
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'. |
|
string |
memory |
The type of the userinfo cache store. Supported values are: 'memory', 'ocmem', 'etcd', 'redis', 'redis-sentinel', 'nats-js', 'noop'. See the text description for details. |
|
[]string |
[] |
A comma separated list of nodes to access the configured store. This has no effect when 'in-memory' stores are configured. Note that the behaviour how nodes are used is dependent on the library of the configured store. |
|
string |
proxy |
The database name the configured store should use. |
|
string |
userinfo |
The database table the store should use. |
|
Duration |
10s |
Default time to live for user info in the user info cache. Only applied when access tokens has no expiration. The duration can be set as number followed by a unit identifier like s, m or h. Defaults to '10s' (10 seconds). |
|
int |
0 |
The maximum quantity of items in the user info cache. Only applies when store type 'ocmem' is configured. Defaults to 512. |
|
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. |
|
uint64 |
10 |
The timeout in seconds for an outgoing JWKS request. |
|
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. |
|
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. |
|
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. |
|
string |
|
The secret to mint and validate JWT tokens. |
|
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. |
|
string |
roles |
The OIDC claim used to create the users role assignment. |
|
bool |
true |
Allow OCS to get a signing key to sign requests. |
|
string |
cs3 |
Account backend the PROXY service should use. Currently only 'cs3' is possible here. |
|
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_user' but you can also add your own 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'. |
|
string |
|
Machine auth API key used to validate internal requests necessary to access resources from other services. |
|
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. |
|
bool |
false |
Set this to true to enable 'basic authentication' (username/password). |
|
bool |
false |
Disable TLS certificate validation for all HTTP backend connections. |
|
string |
|
Path/File for the root CA certificate used to validate the server’s TLS certificate for https enabled backend services. |
|
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. |
Name | Type | Default Value | Description |
---|---|---|---|
|
bool |
false |
Activates tracing. |
|
string |
|
The type of tracing. Defaults to "", which is the same as "jaeger". Allowed tracing types are "jaeger" and "" as of now. |
|
string |
|
The endpoint of the tracing agent. |
|
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. |
|
string |
|
The log level. Valid values are: "panic", "fatal", "error", "warn", "info", "debug", "trace". |
|
bool |
false |
Activates pretty log output. |
|
bool |
false |
Activates colorized log output. |
|
string |
|
The path to the log file. Activates logging to this file if set. |
|
string |
127.0.0.1:9205 |
Bind address of the debug server, where metrics, health, config and debug endpoints will be exposed. |
|
string |
|
Token to secure the metrics endpoint. |
|
bool |
false |
Enables pprof, which can be used for profiling. |
|
bool |
false |
Enables zpages, which can be used for collecting and viewing in-memory traces. |
|
string |
0.0.0.0:9200 |
The bind address of the HTTP service. |
|
string |
/ |
Subdirectory that serves as the root for this HTTP service. |
|
string |
~/.ocis/proxy/server.crt |
Path/File name of the TLS server certificate (in PEM format) for the external http services. If not definied, the root directory derives from $OCIS_BASE_DATA_PATH:/proxy. |
|
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. If not definied, the root directory derives from $OCIS_BASE_DATA_PATH:/proxy. |
|
bool |
true |
Enable/Disable HTTPS for the external HTTP services. |
|
string |
127.0.0.1:9142 |
The CS3 gateway endpoint. |
|
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. |
|
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. |
|
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. |
|
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. |
|
string |
https://localhost:9200 |
URL of the OIDC issuer. It defaults to URL of the builtin IDP. |
|
bool |
false |
Disable TLS certificate validation for connections to the IDP. Note that this is not recommended for production environments. |
|
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'. |
|
int |
1024 |
Cache size for OIDC user info. |
|
int |
10 |
Max TTL in seconds for the OIDC user info cache. |
|
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. |
|
uint64 |
10 |
The timeout in seconds for an outgoing JWKS request. |
|
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. |
|
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. |
|
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. |
|
string |
|
The secret to mint and validate JWT tokens. |
|
bool |
true |
Allow OCS to get a signing key to sign requests. |
|
string |
cs3 |
Account backend the PROXY service should use. Currently only 'cs3' is possible here. |
|
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_user' but you can also add your own 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'. |
|
string |
|
Machine auth API key used to validate internal requests necessary to access resources from other services. |
|
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. |
|
bool |
false |
Set this to true to enable 'basic authentication' (username/password). |
|
bool |
false |
Disable TLS certificate validation for all HTTP backend connections. |
|
string |
|
Path/File for the root CA certificate used to validate the server’s TLS certificate for https enabled backend services. |
YAML Example
Note that the filename shown below has been chosen on purpose.
See the Configuration File Naming for details when setting up your own configuration.
# 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: 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
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: /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
oidc:
issuer: https://localhost:9200
insecure: false
access_token_verify_method: jwt
user_info_cache:
store: memory
addresses: []
database: proxy
table: userinfo
ttl: 10s
size: 0
jwks:
refresh_interval: 60
refresh_timeout: 10
refresh_limit: 60
refresh_unknown_kid: true
rewrite_well_known: false
token_manager:
jwt_secret: ""
role_assignment:
driver: default
oidc_role_mapper:
role_claim: roles
role_mapping:
admin: ocisAdmin
guest: ocisGuest
spaceadmin: ocisSpaceAdmin
user: ocisUser
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: {}
policies_middleware:
query: ""
# 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: {}