Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
62 changes: 62 additions & 0 deletions docs/_static/env-vars/auth-guest.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,62 @@
# Autogenerated
# Filename: auth-guest.yaml

loglevel: error
debug:
addr: 127.0.0.1:9267
token: ""
pprof: false
zpages: false
events:
disabled: false
endpoint: 127.0.0.1:9233
cluster: opencloud-cluster
tls_insecure: false
tls_root_ca_certificate: ""
enable_tls: false
username: ""
password: ""
reva_gateway: eu.opencloud.api.gateway
grpc_client_tls: null
grpc:
addr: 127.0.0.1:9268
tls: null
protocol: tcp
http:
disabled: false
addr: 127.0.0.1:9266
root: /graph
cors:
allow_origins:
- '*'
allow_methods:
- GET
- POST
- PUT
- PATCH
- DELETE
allow_headers:
- Authorization
- Origin
- Content-Type
- Accept
- X-Requested-With
- X-Request-Id
- Ocs-Apirequest
allow_credentials: true
tls:
enabled: false
cert: ""
key: ""
storage:
root_directory: /var/lib/opencloud/auth-guest
token_manager:
jwt_secret: ""
jwt:
secret: ""
cookie_name: __Host-oc_guest_session
ttl: 24h0m0s
service_account:
service_account_id: ""
service_account_secret: ""
num_consumers: 1
38 changes: 38 additions & 0 deletions docs/_static/env-vars/auth-guest_configvars.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,38 @@
## Environment variables for the **auth-guest** service

| Name | Introduction Version | Type | Description | Default Value |
|---|---|---|---|:---|
|`OC_LOG_LEVEL`<br/>`AUTH_GUEST_LOG_LEVEL`| next |string|`The log level. Valid values are: 'panic', 'fatal', 'error', 'warn', 'info', 'debug', 'trace'.`|`"error"`|
|`AUTH_GUEST_DEBUG_ADDR`| next |string|`Bind address of the debug server, where metrics, health, config and debug endpoints will be exposed.`|`"127.0.0.1:9267"`|
|`AUTH_GUEST_DEBUG_TOKEN`| next |string|`Token to secure the metrics endpoint.`|`""`|
|`AUTH_GUEST_DEBUG_PPROF`| next |bool|`Enables pprof, which can be used for profiling.`|`"false"`|
|`AUTH_GUEST_DEBUG_ZPAGES`| next |bool|`Enables zpages, which can be used for collecting and viewing in-memory traces.`|`"false"`|
|`AUTH_GUEST_EVENTS_DISABLED`| next |bool|`Disables listening for events. Set this to true if the service should only handle HTTP requests.`|`"false"`|
|`OC_EVENTS_ENDPOINT`| next |string|`The address of the event system. The event system is the message queuing service. It is used as message broker for the microservice architecture.`|`"127.0.0.1:9233"`|
|`OC_EVENTS_CLUSTER`| next |string|`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.`|`"opencloud-cluster"`|
|`OC_INSECURE`<br/>`OC_EVENTS_TLS_INSECURE`| next |bool|`Whether to verify the server TLS certificates.`|`"false"`|
|`OC_EVENTS_TLS_ROOT_CA_CERTIFICATE`| next |string|`The root CA certificate used to validate the server's TLS certificate. If provided AUTH_GUEST_EVENTS_TLS_INSECURE will be seen as false.`|`""`|
|`OC_EVENTS_ENABLE_TLS`| next |bool|`Enable TLS for the connection to the events broker. The events broker is the OpenCloud service which receives and delivers events between the services.`|`"false"`|
|`OC_EVENTS_AUTH_USERNAME`| next |string|`The username to authenticate with the events broker. The events broker is the OpenCloud service which receives and delivers events between the services.`|`""`|
|`OC_EVENTS_AUTH_PASSWORD`| next |string|`The password to authenticate with the events broker. The events broker is the OpenCloud service which receives and delivers events between the services.`|`""`|
|`OC_REVA_GATEWAY`| next |string|`CS3 gateway used to look up user metadata`|`"eu.opencloud.api.gateway"`|
|`AUTH_GUEST_GRPC_ADDR`| next |string|`The bind address of the GRPC service.`|`"127.0.0.1:9268"`|
|`OC_GRPC_PROTOCOL`<br/>`AUTH_GUEST_GRPC_PROTOCOL`| next |string|`The transport protocol of the GRPC service.`|`"tcp"`|
|`AUTH_GUEST_HTTP_DISABLED`| next |bool|`Disables the HTTP service. Set this to true if the service should only handle events.`|`"false"`|
|`AUTH_GUEST_HTTP_ADDR`| next |string|`The bind address of the HTTP service.`|`"127.0.0.1:9266"`|
|`AUTH_GUEST_HTTP_ROOT`| next |string|`Subdirectory that serves as the root for this HTTP service.`|`"/graph"`|
|`OC_CORS_ALLOW_ORIGINS`<br/>`AUTH_GUEST_CORS_ALLOW_ORIGINS`| next |[]string|`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.`|`"[*]"`|
|`OC_CORS_ALLOW_METHODS`<br/>`AUTH_GUEST_CORS_ALLOW_METHODS`| next |[]string|`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.`|`"[GET POST PUT PATCH DELETE]"`|
|`OC_CORS_ALLOW_HEADERS`<br/>`AUTH_GUEST_CORS_ALLOW_HEADERS`| next |[]string|`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.`|`"[Authorization Origin Content-Type Accept X-Requested-With X-Request-Id Ocs-Apirequest]"`|
|`OC_CORS_ALLOW_CREDENTIALS`<br/>`AUTH_GUEST_CORS_ALLOW_CREDENTIALS`| next |bool|`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.`|`"true"`|
|`OC_HTTP_TLS_ENABLED`| 1.0.0 |bool|`Activates TLS for the http based services using the server certifcate and key configured via OC_HTTP_TLS_CERTIFICATE and OC_HTTP_TLS_KEY. If OC_HTTP_TLS_CERTIFICATE is not set a temporary server certificate is generated - to be used with PROXY_INSECURE_BACKEND=true.`|`"false"`|
|`OC_HTTP_TLS_CERTIFICATE`| 1.0.0 |string|`Path/File name of the TLS server certificate (in PEM format) for the http services.`|`""`|
|`OC_HTTP_TLS_KEY`| 1.0.0 |string|`Path/File name for the TLS certificate key (in PEM format) for the server certificate to use for the http services.`|`""`|
|`AUTH_GUEST_TOKENS_STORAGE_ROOT`| next |string|`The directory where the guest share tokens are stored. If not defined, the root directory derives from $OC_BASE_DATA_PATH/auth-guest.`|`"/var/lib/opencloud/auth-guest"`|
|`OC_JWT_SECRET`<br/>`AUTH_GUEST_JWT_SECRET`| next |string|`The secret to mint and validate jwt tokens.`|`""`|
|`AUTH_GUEST_SESSION_JWT_SECRET`| next |string|`The secret used to sign and validate guest session tokens. It must differ from OC_JWT_SECRET.`|`""`|
|`AUTH_GUEST_JWT_COOKIE_NAME`| next |string|`The name of the session cookie set when a guest token is redeemed.`|`"__Host-oc_guest_session"`|
|`AUTH_GUEST_JWT_TTL`| next |Duration|`The lifetime of a redeemed guest session token.`|`"24h0m0s"`|
|`OC_SERVICE_ACCOUNT_ID`<br/>`AUTH_GUEST_SERVICE_ACCOUNT_ID`| next |string|`The ID of the service account the service should use. See the 'auth-service' service description for more details.`|`""`|
|`OC_SERVICE_ACCOUNT_SECRET`<br/>`AUTH_GUEST_SERVICE_ACCOUNT_SECRET`| next |string|`The service account secret.`|`""`|
|`AUTH_GUEST_NUM_CONSUMERS`| next |int|`The amount of concurrent event consumers to start. Event consumers are used for processing events. Multiple consumers increase parallelisation, but will also increase CPU and memory demands.`|`"1"`|
Empty file.
114 changes: 114 additions & 0 deletions docs/_static/env-vars/auth-guest_readme.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,114 @@
<!-- Do not edit this file, it is autogenerated. Edit the service README.md instead -->

## Abstract


The `auth-guest` service gives guest users access to a share without a full
OpenCloud account. When a share is created for a user of type
`USER_TYPE_GUEST`, the service issues a one-time guest link token; redeeming
that token exchanges it for a signed session cookie that authenticates the
guest.

It is disabled by default. Set `OC_ENABLE_GUEST_LINKS=true` to enable the guest
links feature and start the service.


## Table of Contents

* [Overview](#overview)
* [Guest links flow](#guest-links-flow)
* [Token lifecycle](#token-lifecycle)
* [Configuration](#configuration)

## Overview

- **Consumes** the share lifecycle events `ShareCreated`, `ShareRemoved` and
`ShareExpired`.
- **Publishes** the `GuestTokenCreated` event carrying the guest link token,
so the link can be delivered to the guest.
- Exposes an unauthenticated endpoint that redeems the token and sets a
session cookie.
- Stores only hashes of the token and deletes the stored record when the share
is removed or expires.

## Guest links flow

The following sequence diagram describes the guest links flow:

```mermaid
sequenceDiagram
autonumber
actor User as Guest user
participant Web as Web client
participant Redeem as Redeem endpoint
participant Proxy as OpenCloud proxy
participant Graph as Graph / sharedWithMe
participant DAV as WebDAV
participant Reva as Reva

User->>Web: Open guest link with valid token
Web->>+Redeem: Redeem Token
Note right of Redeem: Validate Token
Redeem->>+Reva: Get Share
Reva->>-Redeem: Share
Note right of Redeem: Validate Share, Mark Token used
Redeem->>-Web: Set Cookie, return shareid
Note right of Web: HTTP only cookie with signed JWT (JWT lifetime 24h)
Web->>+Proxy: "/graph/me/drives/sharedWithMe"
Proxy->>+Reva: validate token extracted from JWT
Note right of Reva: Sign Reva Token for Guest User
Reva->>-Proxy: Authenticated
Proxy->>+Graph: "/graph/me/drives/sharedWithMe"
Note right of Proxy: Using Reva Token
Graph->>+Reva: Requests to ShareProvider
Reva->>-Graph: Shares
Graph->>-Proxy: driveItems (all shares for the Guest User)
Proxy->>-Web: driveItems
Note right of Web: Extracts driveItem for the specific share
Web->>+Proxy: PROPFIND (resource id extracted from driveItem)
Note right of Web: Using Cookie
Proxy->>+Reva: validate token extracted from JWT
Note right of Reva: Sign Reva Token for Guest User
Reva->>-Proxy: Authenticated
Proxy->>+DAV: PROPFIND
Note right of Proxy: Using Reva Token
DAV->>+Reva: Requests to StorageProvider
Reva->>-DAV: StorageProvider Responses
DAV->>-Proxy: PROPFIND Response
Proxy->>-Web: PROPFIND Response
```

## Token lifecycle

1. **Issue** — on the consumed `ShareCreated` event, where the grantee is a
guest, the service generates a random secret and stores a record keyed by
the hash of the share id. It then publishes the `GuestTokenCreated` event
with the token.
2. **Redeem** — the guest posts the token to
`POST /graph/v1beta1/extensions/org.libregraph/guestLinks/redeem`.
The service validates the token and the share, marks the token as used
and returns a signed JWT session token in a cookie plus the share's
`permissionId` in the response body. Tokens are single-use.
3. **Cleanup** — on the consumed `ShareRemoved` or `ShareExpired` event, the
stored record is deleted.

## Configuration

The service is configured via `AUTH_GUEST_*` environment variables or a
`auth-guest.yaml` file.

To run only the HTTP part, set `AUTH_GUEST_EVENTS_DISABLED=true`. To run only
the event consumer, set `AUTH_GUEST_HTTP_DISABLED=true`.

Relevant options:

- `AUTH_GUEST_SESSION_JWT_SECRET` — secret used to sign guest session tokens.
It must differ from `OC_JWT_SECRET`.
- `AUTH_GUEST_JWT_COOKIE_NAME`, `AUTH_GUEST_JWT_TTL` — session cookie name and
lifetime.
- `AUTH_GUEST_TOKENS_STORAGE_ROOT` — where guest link token records are stored.
- `AUTH_GUEST_SERVICE_ACCOUNT_ID`, `AUTH_GUEST_SERVICE_ACCOUNT_SECRET` — service
account used to query the gateway for share metadata.
- `AUTH_GUEST_NUM_CONSUMERS` — number of concurrent event consumers.
- `OC_REVA_GATEWAY` — CS3 gateway used to look up shares.

4 changes: 4 additions & 0 deletions docs/_static/env-vars/collaboration.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -12,9 +12,11 @@ app:
disable: false
duration: 12h
licensecheckenable: false
product_edition: ""
font:
asset_path: /var/lib/opencloud/collaboration/fonts
preview_text: OpenCloud
base_url: ""
store:
store: nats-js-kv
nodes:
Expand Down Expand Up @@ -45,6 +47,8 @@ wopi:
proxy_url: ""
proxy_secret: ""
short_tokens: false
enable_mobile: false
disabled_extensions: []
cs3api:
gateway:
name: eu.opencloud.api.gateway
Expand Down
4 changes: 4 additions & 0 deletions docs/_static/env-vars/collaboration_configvars.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,8 +12,10 @@
|`COLLABORATION_APP_PROOF_DISABLE`| 1.0.0 |bool|`Disable the proof keys verification`|`"false"`|
|`COLLABORATION_APP_PROOF_DURATION`| 1.0.0 |string|`Duration for the proof keys to be cached in memory, using time.ParseDuration format. If the duration can't be parsed, we'll use the default 12h as duration`|`"12h"`|
|`COLLABORATION_APP_LICENSE_CHECK_ENABLE`| 1.0.0 |bool|`Enable license checking to edit files. Needs to be enabled when using Microsoft365 with the business flow.`|`"false"`|
|`COLLABORATION_APP_PRODUCT_EDITION`| 8.1.0 |string|`The edition of the WebOffice app, it decides which features the app offers. Only used for EuroOffice, where 'ce', 'de' and 'ee' are supported and an empty value is the same as 'ce'.`|`""`|
|`COLLABORATION_FONT_ASSET_PATH`| 7.3.0 |string|`Serve fonts from a path on the filesystem instead of the builtin assets. If not defined, the root directory derives from $OC_BASE_DATA_PATH/collaboration/fonts`|`"/var/lib/opencloud/collaboration/fonts"`|
|`COLLABORATION_FONT_PREVIEW_TEXT`| 7.3.0 |string|`The text that will be displayed in the font preview.`|`"OpenCloud"`|
|`COLLABORATION_FONT_BASE_URL`| 7.3.0 |string|`The base URL under which the font files are served. It must match the URL configured in the remote_font_config of the office suite. If not set, it defaults to $OC_URL/collaboration/fonts`|`""`|
|`OC_PERSISTENT_STORE`<br/>`COLLABORATION_STORE`| 1.0.0 |string|`The type of the store. Supported values are: 'memory', 'nats-js-kv', 'redis-sentinel', 'noop'. See the text description for details.`|`"nats-js-kv"`|
|`OC_PERSISTENT_STORE_NODES`<br/>`COLLABORATION_STORE_NODES`| 1.0.0 |[]string|`A list of nodes to access the configured store. This has no effect when 'memory' store is 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.`|`"[127.0.0.1:9233]"`|
|`COLLABORATION_STORE_DATABASE`| 1.0.0 |string|`The database name the configured store should use.`|`"collaboration"`|
Expand All @@ -37,6 +39,8 @@
|`COLLABORATION_WOPI_PROXY_URL`| 1.0.0 |string|`The URL to the OpenCloud WOPI proxy. Optional. To use this feature, you need an office365 proxy subscription. If you become part of the Microsoft CSP program (\https://learn.microsoft.com/en-us/partner-center/enroll/csp-overview), you can use WebOffice without a proxy.`|`""`|
|`COLLABORATION_WOPI_PROXY_SECRET`| 1.0.0 |string|`Optional, the secret to authenticate against the OpenCloud WOPI proxy. This secret can be obtained from OpenCloud via the office365 proxy subscription.`|`""`|
|`COLLABORATION_WOPI_SHORTTOKENS`| 1.0.0 |bool|`Use short access tokens for WOPI access. This is useful for office packages, like Microsoft Office Online, which have URL length restrictions. If enabled, a persistent store must be configured.`|`"false"`|
|`COLLABORATION_WOPI_ENABLE_MOBILE`| 8.1.0 |bool|`Enable the mobile web view of the office web frontend. This feature applies to EuroOffice, where the product edition decides whether it covers editing as well.`|`"false"`|
|`COLLABORATION_WOPI_DISABLED_EXTENSIONS`| 8.1.0 |[]string|`A comma separated list of file extensions the office web frontend must not offer, for example 'docx,xlsx'. Extensions are matched case-insensitively, with or without the leading dot.`|`"[]"`|
|`OC_REVA_GATEWAY`| 1.0.0 |string|`CS3 gateway used to look up user metadata.`|`"eu.opencloud.api.gateway"`|
|`COLLABORATION_CS3API_DATAGATEWAY_INSECURE`| 1.0.0 |bool|`Connect to the CS3API data gateway insecurely.`|`"false"`|
|`COLLABORATION_CS3API_APP_REGISTRATION_INTERVAL`| 4.0.0 |Duration|`The interval at which the app provider registers itself.`|`"30s"`|
Expand Down
11 changes: 11 additions & 0 deletions docs/_static/env-vars/collaboration_readme.md
Original file line number Diff line number Diff line change
Expand Up @@ -42,6 +42,9 @@ There are a few variables that you need to set:
The product name of the connected WebOffice app, which can be one of the following:\
`Collabora`, `OnlyOffice`, `Microsoft365` or `MicrosoftOfficeOnline`. This is used to internally control the behavior according to the different features of the used products.

* `COLLABORATION_APP_PRODUCT_EDITION`:\
The edition of the connected WebOffice app, it decides which features the app offers. Only used for EuroOffice, which supports `ce` (community edition), `de` (developer edition) and `ee` (enterprise edition). An empty value is the same as `ce`.

* `COLLABORATION_APP_ADDR`:\
The URL of the collaborative editing app (onlyoffice, collabora, etc).\
For example: `https://office.example.com`.
Expand All @@ -56,6 +59,14 @@ There are a few variables that you need to set:
* `COLLABORATION_WOPI_SHORTTOKENS`:\
Needs to be set if the office application like `Microsoft Office Online` complains about the URL is too long (which contains the access token) and refuses to work. If enabled, a store must be configured.

* `COLLABORATION_WOPI_ENABLE_MOBILE`:\
Enables the mobile web view of the office web frontend. Only applies to EuroOffice. `ce` offers the mobile view for reading only, `de` and `ee` also for editing, so set `COLLABORATION_APP_PRODUCT_EDITION` accordingly.

* `COLLABORATION_WOPI_DISABLED_EXTENSIONS`:\
A comma separated list of file extensions the app must not offer, even though the document server announces them.\
The webUI offers no editor of this app for them and opening such a file with it fails.\
For example: `COLLABORATION_WOPI_DISABLED_EXTENSIONS=docx,xlsx,pptx`.

The application can be customized further by changing the `COLLABORATION_APP_*` options to better describe the application.

## Storing
Expand Down
2 changes: 1 addition & 1 deletion docs/_static/env-vars/frontend_configvars.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@

2026-09-17-06-05-59
2026-10-07-00-08-40

## Deprecation Notice

Expand Down
5 changes: 0 additions & 5 deletions docs/_static/env-vars/frontend_readme.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,6 @@ The frontend service translates various OpenCloud related HTTP APIs to CS3 reque
* [Scalability](#scalability)
* [Define Read-Only Attributes](#define-readonly-attributes)
* [Caching](#caching)
* [Auto-Accept Shares](#autoaccept-shares)
* [Passwords](#passwords)
* [The Password Policy](#the-password-policy)
* [The Password Policy Capability](#the-password-policy-capability)
Expand Down Expand Up @@ -86,10 +85,6 @@ Store specific notes:
- When using `nats-js-kv` it is recommended to set `OC_CACHE_STORE_NODES` to the same value as `OC_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 `OC_CACHE_DISABLE_PERSISTENCE` to instruct nats to not persist cache data on disc.

### Auto-Accept Shares

When setting the `SHARING_AUTO_ACCEPT_SHARES` to `true` (sharing service), all incoming shares will be accepted automatically. Users can overwrite this setting individually in their profile. The deprecated `FRONTEND_AUTO_ACCEPT_SHARES` is still supported for backwards compatibility.

## Passwords

### The Password Policy
Expand Down
1 change: 1 addition & 0 deletions docs/_static/env-vars/gateway.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -55,6 +55,7 @@ auth_basic_endpoint: eu.opencloud.api.auth-basic
auth_bearer_endpoint: ""
auth_machine_endpoint: eu.opencloud.api.auth-machine
auth_service_endpoint: eu.opencloud.api.auth-service
auth_guestlinks_endpoint: eu.opencloud.api.auth-guest
storage_public_link_endpoint: eu.opencloud.api.storage-publiclink
storage_users_endpoint: eu.opencloud.api.storage-users
storage_shares_endpoint: eu.opencloud.api.storage-shares
Expand Down
Loading
Loading