From db0fbf34739ba93a457a67c8a80b1d3ac01a5fa4 Mon Sep 17 00:00:00 2001 From: openclouders Date: Wed, 14 Oct 2026 00:07:12 +0000 Subject: [PATCH] Update docs with latest env vars --- docs/_static/env-vars/auth-guest_readme.md | 157 ++++++++++++++++-- docs/_static/env-vars/frontend_configvars.md | 2 +- docs/_static/env-vars/global_configvars.md | 84 +++++----- .../env-vars/storage-users_configvars.md | 2 +- docs/_static/env-vars/web_configvars.md | 2 +- 5 files changed, 187 insertions(+), 60 deletions(-) diff --git a/docs/_static/env-vars/auth-guest_readme.md b/docs/_static/env-vars/auth-guest_readme.md index 5cf0c358..2b61d524 100755 --- a/docs/_static/env-vars/auth-guest_readme.md +++ b/docs/_static/env-vars/auth-guest_readme.md @@ -9,6 +9,10 @@ OpenCloud account. When a share is created for a user of type that token exchanges it for a signed session cookie that authenticates the guest. +When the session or the link token is no longer valid, the guest can *renew*: +the service issues a new link token together with a one-time PIN. The guest +then either redeems the new link or exchanges the PIN for a fresh session. + It is disabled by default. Set `OC_ENABLE_GUEST_LINKS=true` to enable the guest links feature and start the service. @@ -17,19 +21,24 @@ links feature and start the service. * [Overview](#overview) * [Guest links flow](#guest-links-flow) +* [Renewal and PIN flow](#renewal-and-pin-flow) * [Token lifecycle](#token-lifecycle) + * [Endpoints](#endpoints) + * [`POST .../guestLinks/verify/token`](#post-guestlinksverifytoken) + * [`POST .../guestLinks/renew`](#post-guestlinksrenew) + * [`POST .../guestLinks/verify/pin`](#post-guestlinksverifypin) * [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. +- **Publishes** the `GuestTokenCreated` event (initial token) and the + `GuestTokenRenewed` event (refresh, carrying the new token and the PIN). +- Exposes unauthenticated endpoints to redeem a token, renew it and verify a + PIN; redeeming a token or verifying a PIN sets a session cookie. +- Stores only hashes of the token secret and of the PIN and deletes the stored + record when the share is removed or expires. ## Guest links flow @@ -53,7 +62,7 @@ sequenceDiagram 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) + Note right of Web: HTTP only cookie with signed JWT (24h by default) Web->>+Proxy: "/graph/me/drives/sharedWithMe" Proxy->>+Reva: validate token extracted from JWT Note right of Reva: Sign Reva Token for Guest User @@ -78,6 +87,63 @@ sequenceDiagram Proxy->>-Web: PROPFIND Response ``` +## Renewal and PIN flow + +A guest session (signed JWT) is valid for 24 hours by default +(`AUTH_GUEST_JWT_TTL`); a link token is single-use and valid for 30 minutes. +Renewal starts from a *failed* attempt: + +- an authenticated request made with an expired session is rejected with `401`; + the browser still holds the (expired) session cookie; +- `redeem` on a link that was already used answers `409`, and on an expired + link `401`; the client still holds the link token. + +`renew` requires the share id (`permissionId`) and is authorized by either the +(possibly expired) session cookie or the previous link token, whichever the +client has; the credential must belong to the given share. It does not create a +session. It requires an existing token record for the share, validates the +share, generates a new link token and a 6-digit PIN (both valid for 30 minutes), +overwrites the stored token and PIN hashes (invalidating the previous link and +PIN), resets the redeemed flag so the new link can be redeemed, and publishes +`GuestTokenRenewed`. It answers `200`. This works whether the record is unused, +expired or already redeemed (the guest already redeemed an earlier link); if +publishing fails, the previous record is restored. + +To turn the new credentials into a session the guest either redeems the link +(`verify/token`) or enters the PIN (`verify/pin`); both return a session +cookie and the `permissionId`. `verify/pin` does not consume the link token. + +```mermaid +sequenceDiagram + autonumber + actor User as Guest user + participant Web as Web client + participant Renew as Renew endpoint + participant Redeem as Redeem endpoint + participant Pin as Verify PIN endpoint + participant Bus as Event bus + + Note over Web: Session expired / previous link used or expired + Web->>+Renew: POST renew { permissionId } (+ session cookie or link token) + Note right of Renew: Validate share, generate token + PIN, store hashes + Renew->>Bus: publish GuestTokenRenewed + Note right of Bus: External consumer delivers token + PIN (out of scope) + Renew->>-Web: 200 OK + + alt Guest opens the new link + User->>Web: Open link + Web->>+Redeem: POST redeem { token } + Note right of Redeem: Validate token + share, mark used + Redeem->>-Web: Set Cookie, return permissionId + else Guest enters the PIN + User->>Web: Enter PIN + Web->>+Pin: POST verify/pin { pin, permissionId } + Note right of Pin: Validate share, consume PIN (single-use) + Pin->>-Web: Set Cookie, return permissionId + end + Note over Web: HTTP only cookie, signed JWT (24h default) +``` + ## Token lifecycle 1. **Issue** — on the consumed `ShareCreated` event, where the grantee is a @@ -85,20 +151,81 @@ sequenceDiagram 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. + `POST /graph/v1beta1/extensions/org.libregraph/guestLinks/verify/token`. + 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 and valid for + 30 minutes; the session cookie lives for 24 hours by default + (`AUTH_GUEST_JWT_TTL`). +3. **Renew** — the guest posts the `permissionId` to + `POST /graph/v1beta1/extensions/org.libregraph/guestLinks/renew`, authorized + by either the previous link token (`{ "token": "" }`) or the (possibly + expired) session cookie, which must both belong to that share. An existing + record is required; otherwise the request fails with `tokenNotFound`. The + service validates the share, generates a new link token and a 6-digit PIN + (both valid for 30 minutes), overwrites the stored token and PIN hashes + (invalidating the previous link and PIN) and resets the redeemed flag so the + new link can be redeemed, then publishes the `GuestTokenRenewed` event. This + works whether the record is unused, expired or already redeemed. If + publishing fails, the previous record is restored. +4. **Verify PIN** — the guest posts the PIN and the `permissionId` to + `POST /graph/v1beta1/extensions/org.libregraph/guestLinks/verify/pin`. + The service validates the record and the share, compares the PIN against the + stored argon2id hash and, on success, clears the PIN (single-use) and + returns a signed JWT session token in a cookie plus the share's + `permissionId`. Verifying the PIN does not consume the magic link. + +### Endpoints + +All error responses have the body +`{ "errorType": "", "message": "", "permissionId": "" }`. + +#### `POST .../guestLinks/verify/token` + +- **Request body:** `{ "token": "" }` +- **Success:** `200`, session cookie, + `{ "permissionId": "" }` +- **Errors:** `400 invalidRequest`, `401 tokenInvalid`, + `401 tokenExpired`, `404 tokenNotFound`, `409 tokenAlreadyRedeemed`, + `404 shareNotFound`, `410 shareExpired`, `500 internalError` + +#### `POST .../guestLinks/renew` + +- **Request body:** + `{ "permissionId": "", "token": "" }` + (`token` optional when the session cookie is sent) +- **Authorization:** the share id is required; the body link token or the + session cookie must belong to it, the link token takes precedence +- **Success:** `200` (no session cookie; the new link/PIN are delivered out + of band) +- **Errors:** `400 invalidRequest`, `401 tokenInvalid`, `401 sessionInvalid`, + `404 tokenNotFound`, `404 shareNotFound`, `410 shareExpired`, + `409 tokenAlreadyRedeemed`, `503 serviceUnavailable`, `500 internalError` + +#### `POST .../guestLinks/verify/pin` + +- **Request body:** `{ "pin": "", "permissionId": "" }` +- **Success:** `200`, session cookie, + `{ "permissionId": "" }` +- **Errors:** `400 invalidRequest`, `401 pinInvalid`, `401 pinExpired`, + `404 shareNotFound`, `410 shareExpired`, `500 internalError` ## 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`. +Both transports are enabled by default: the service consumes and publishes +events and serves the HTTP endpoints. Either transport can be disabled: + +- `AUTH_GUEST_EVENTS_DISABLED=true` — the service does not consume events + (no tokens are created or cleaned up) and `renew` cannot publish its event, + so it responds with `503 serviceUnavailable`. +- `AUTH_GUEST_HTTP_DISABLED=true` — the service does not serve the HTTP + endpoints (`verify/token`, `renew`, `verify/pin`). + +The token and PIN lifetimes are fixed (30 minutes each) and are not +configurable. Relevant options: diff --git a/docs/_static/env-vars/frontend_configvars.md b/docs/_static/env-vars/frontend_configvars.md index 0b1c1f90..6001be5c 100644 --- a/docs/_static/env-vars/frontend_configvars.md +++ b/docs/_static/env-vars/frontend_configvars.md @@ -1,5 +1,5 @@ -2026-10-13-00-11-11 +2026-10-14-00-06-59 ## Deprecation Notice diff --git a/docs/_static/env-vars/global_configvars.md b/docs/_static/env-vars/global_configvars.md index f922883f..900753cd 100644 --- a/docs/_static/env-vars/global_configvars.md +++ b/docs/_static/env-vars/global_configvars.md @@ -7,84 +7,84 @@ | `IDM_CREATE_DEMO_USERS` | 1.0.0 | bool | The default role assignments the demo users should be setup. | "false" | | `OC_ADMIN_USER_ID` | 1.0.0 | string | ID of the user who collects all necessary information for deletion. Consider that the UUID can be encoded in some LDAP deployment configurations like in .ldif files. These need to be decoded beforehand. | "" | | `OC_ASYNC_UPLOADS` | 1.0.0 | bool | Enable asynchronous file uploads. | "true" | -| `OC_CACHE_AUTH_PASSWORD` | 1.0.0 | string | The password to authenticate with the cache store. Only applies when store type 'nats-js-kv' is configured. | "" | -| `OC_CACHE_AUTH_USERNAME` | 1.0.0 | string | The username to authenticate with the cache store. Only applies when store type 'nats-js-kv' is configured. | "" | -| `OC_CACHE_DATABASE` | 1.0.0 | string | The database name the configured store should use. | "storage-users" | -| `OC_CACHE_DISABLE_PERSISTENCE` | 1.0.0 | bool | Disables persistence of the cache. Only applies when store type 'nats-js-kv' is configured. Defaults to false. | "false" | +| `OC_CACHE_AUTH_PASSWORD` | 1.0.0 | string | The password to use for authentication. Only applies when store type 'nats-js-kv' is configured. | "" | +| `OC_CACHE_AUTH_USERNAME` | 1.0.0 | string | The username to use for authentication. Only applies when store type 'nats-js-kv' is configured. | "" | +| `OC_CACHE_DATABASE` | 1.0.0 | string | The database name the configured store should use. | "cache-providers" | +| `OC_CACHE_DISABLE_PERSISTENCE` | 1.0.0 | bool | Disables persistence of the provider cache. Only applies when store type 'nats-js-kv' is configured. Defaults to false. | "false" | | `OC_CACHE_ENABLE_TLS` | 7.3.0 | bool | Enable TLS for the connection to file metadata cache. | "false" | -| `OC_CACHE_STORE` | 1.0.0 | string | The type of the cache store. Supported values are: 'memory', 'redis-sentinel', 'nats-js-kv', 'noop'. See the text description for details. | "memory" | +| `OC_CACHE_STORE` | 1.0.0 | string | The type of the cache store. Supported values are: 'memory', 'redis-sentinel', 'nats-js-kv', 'noop'. See the text description for details. | "noop" | | `OC_CACHE_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]" | | `OC_CACHE_TLS_INSECURE` | 7.3.0 | bool | Whether to verify the server TLS certificates. | "false" | -| `OC_CACHE_TLS_ROOT_CA_CERTIFICATE` | 7.3.0 | string | The root CA certificate used to validate the server's TLS certificate. If provided STORAGE_USERS_FILEMETADATA_CACHE_TLS_INSECURE will be seen as false. | "" | -| `OC_CACHE_TTL` | 1.0.0 | Duration | 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. | "24h0m0s" | +| `OC_CACHE_TLS_ROOT_CA_CERTIFICATE` | 7.3.0 | string | The root CA certificate used to validate the server's TLS certificate. If provided GATEWAY_PROVIDER_CACHE_TLS_INSECURE will be seen as false. | "" | +| `OC_CACHE_TTL` | 1.0.0 | Duration | Default time to live for user info in the cache. Only applied when access tokens has no expiration. See the Environment Variable Types description for more details. | "5m0s" | | `OC_CORS_ALLOW_CREDENTIALS` | 1.0.0 | 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. | "false" | -| `OC_CORS_ALLOW_HEADERS` | 1.0.0 | []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. | "[]" | -| `OC_CORS_ALLOW_METHODS` | 1.0.0 | []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. | "[]" | +| `OC_CORS_ALLOW_HEADERS` | 1.0.0 | []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 X-Requested-With X-Request-Id X-HTTP-Method-Override Content-Type Upload-Length Upload-Offset Tus-Resumable Upload-Metadata Upload-Defer-Length Upload-Concat Upload-Complete Upload-Incomplete Upload-Draft-Interop-Version]" | +| `OC_CORS_ALLOW_METHODS` | 1.0.0 | []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. | "[POST HEAD PATCH OPTIONS GET DELETE]" | | `OC_CORS_ALLOW_ORIGINS` | 1.0.0 | []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. | "[https://localhost:9200]" | | `OC_DECOMPOSEDFS_PROPAGATOR` | 1.0.0 | string | The propagator used for decomposedfs. At the moment, only 'sync' is fully supported, 'async' is available as an experimental option. | "sync" | | `OC_DEFAULT_LANGUAGE` | 1.0.0 | string | The default language used by services and the WebUI. If not defined, English will be used as default. See the documentation for more details. | "" | | `OC_DISABLE_VERSIONING` | 1.0.0 | bool | Disables versioning of files. When set to true, new uploads with the same filename will overwrite existing files instead of creating a new version. | "false" | -| `OC_ENABLE_OCM` | 1.0.0 | bool | Changing this value is NOT supported. Enables support for incoming federated sharing for clients. The backend behaviour is not changed. | "false" | +| `OC_ENABLE_OCM` | 1.0.0 | bool | Include OCM sharees when listing users. | "false" | | `OC_EVENTS_AUTH_PASSWORD` | 1.0.0 | 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_EVENTS_AUTH_USERNAME` | 1.0.0 | 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_CLUSTER` | 1.0.0 | 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_EVENTS_ENABLE_TLS` | 1.0.0 | 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_ENDPOINT` | 1.0.0 | 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_TLS_INSECURE` | 1.0.0 | bool | Whether the OpenCloud server should skip the client certificate verification during the TLS handshake. | "false" | -| `OC_EVENTS_TLS_ROOT_CA_CERTIFICATE` | 1.0.0 | string | The root CA certificate used to validate the server's TLS certificate. If provided POSTPROCESSING_EVENTS_TLS_INSECURE will be seen as false. | "" | -| `OC_GATEWAY_GRPC_ADDR` | 1.0.0 | string | The bind address of the gateway GRPC address. | "127.0.0.1:9142" | +| `OC_EVENTS_TLS_INSECURE` | 1.0.0 | bool | Whether the server should skip the client certificate verification during the TLS handshake. | "false" | +| `OC_EVENTS_TLS_ROOT_CA_CERTIFICATE` | 1.0.0 | string | The root CA certificate used to validate the server's TLS certificate. If provided POLICIES_EVENTS_TLS_INSECURE will be seen as false. | "" | +| `OC_GATEWAY_GRPC_ADDR` | 1.0.0 | string | The bind address of the GRPC service. | "127.0.0.1:9142" | | `OC_GRPC_CLIENT_TLS_CACERT` | 1.0.0 | 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. | "" | | `OC_GRPC_CLIENT_TLS_MODE` | 1.0.0 | 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. | "" | -| `OC_GRPC_PROTOCOL` | 1.0.0 | string | The transport protocol of the GPRC service. | "tcp" | +| `OC_GRPC_PROTOCOL` | 1.0.0 | string | The transport protocol of the GRPC service. | "tcp" | | `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_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_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. | "" | | `OC_INSECURE` | 7.3.0 | bool | Whether to verify the server TLS certificates. | "false" | | `OC_JWT_SECRET` | 1.0.0 | string | The secret to mint and validate jwt tokens. | "" | | `OC_KEYCLOAK_BASE_PATH` | 1.0.0 | string | The URL to access keycloak. | "" | -| `OC_KEYCLOAK_CLIENT_ID` | 1.0.0 | string | The client ID to authenticate with keycloak. | "" | +| `OC_KEYCLOAK_CLIENT_ID` | 1.0.0 | string | The client id to authenticate with keycloak. | "" | | `OC_KEYCLOAK_CLIENT_REALM` | 1.0.0 | string | The realm the client is defined in. | "" | | `OC_KEYCLOAK_CLIENT_SECRET` | 1.0.0 | string | The client secret to use in authentication. | "" | | `OC_KEYCLOAK_INSECURE_SKIP_VERIFY` | 1.0.0 | bool | Disable TLS certificate validation for Keycloak connections. Do not set this in production environments. | "false" | | `OC_KEYCLOAK_USER_REALM` | 1.0.0 | string | The realm users are defined. | "" | -| `OC_LDAP_BIND_DN` | 1.0.0 | string | LDAP DN to use for simple bind authentication with the target LDAP server. | "uid=idp,ou=sysusers,o=libregraph-idm" | +| `OC_LDAP_BIND_DN` | 1.0.0 | string | LDAP DN to use for simple bind authentication with the target LDAP server. | "uid=reva,ou=sysusers,o=libregraph-idm" | | `OC_LDAP_BIND_PASSWORD` | 1.0.0 | string | Password to use for authenticating the 'bind_dn'. | "" | -| `OC_LDAP_CACERT` | 1.0.0 | string | Path/File name for the root CA certificate (in PEM format) used to validate TLS server certificates of the LDAP service. If not defined, the root directory derives from $OC_BASE_DATA_PATH/idp. | "" | +| `OC_LDAP_CACERT` | 1.0.0 | string | Path/File name for the root CA certificate (in PEM format) used to validate TLS server certificates of the LDAP service. If not defined, the root directory derives from $OC_BASE_DATA_PATH/idm. | "" | | `OC_LDAP_DISABLED_USERS_GROUP_DN` | 1.0.0 | string | The distinguished name of the group to which added users will be classified as disabled when 'disable_user_mechanism' is set to 'group'. | "cn=DisabledUsersGroup,ou=groups,o=libregraph-idm" | | `OC_LDAP_DISABLE_USER_MECHANISM` | 1.0.0 | string | An option to control the behavior for disabling users. Valid options are 'none', 'attribute' and 'group'. If set to 'group', disabling a user via API will add the user to the configured group for disabled users, if set to 'attribute' this will be done in the ldap user entry, if set to 'none' the disable request is not processed. | "attribute" | | `OC_LDAP_GROUP_BASE_DN` | 1.0.0 | string | Search base DN for looking up LDAP groups. | "ou=groups,o=libregraph-idm" | | `OC_LDAP_GROUP_FILTER` | 1.0.0 | string | LDAP filter to add to the default filters for group searches. | "" | -| `OC_LDAP_GROUP_OBJECTCLASS` | 1.0.0 | string | The object class to use for groups in the default group search filter like 'groupOfNames'. | "groupOfNames" | +| `OC_LDAP_GROUP_OBJECTCLASS` | 1.0.0 | string | The object class to use for groups in the default group search filter ('groupOfNames'). | "groupOfNames" | | `OC_LDAP_GROUP_SCHEMA_DISPLAYNAME` | 1.0.0 | string | LDAP Attribute to use for the displayname of groups (often the same as groupname attribute). | "cn" | | `OC_LDAP_GROUP_SCHEMA_GROUPNAME` | 1.0.0 | string | LDAP Attribute to use for the name of groups. | "cn" | -| `OC_LDAP_GROUP_SCHEMA_ID` | 1.0.0 | string | LDAP Attribute to use as the unique ID for groups. This should be a stable globally unique ID like a UUID. | "openclouduuid" | +| `OC_LDAP_GROUP_SCHEMA_ID` | 1.0.0 | string | LDAP Attribute to use as the unique id for groups. This should be a stable globally unique ID like a UUID. | "openCloudUUID" | | `OC_LDAP_GROUP_SCHEMA_ID_IS_OCTETSTRING` | 1.0.0 | bool | Set this to true if the defined 'id' attribute for groups is of the 'OCTETSTRING' syntax. This is e.g. required when using the 'objectGUID' attribute of Active Directory for the group ID's. | "false" | | `OC_LDAP_GROUP_SCHEMA_MAIL` | 1.0.0 | string | LDAP Attribute to use for the email address of groups (can be empty). | "mail" | | `OC_LDAP_GROUP_SCHEMA_MEMBER` | 1.0.0 | string | LDAP Attribute that is used for group members. | "member" | -| `OC_LDAP_GROUP_SCOPE` | 1.0.0 | string | LDAP search scope to use when looking up groups. Supported values are 'base', 'one' and 'sub'. | "sub" | +| `OC_LDAP_GROUP_SCOPE` | 1.0.0 | string | LDAP search scope to use when looking up groups. Supported scopes are 'base', 'one' and 'sub'. | "sub" | | `OC_LDAP_INSECURE` | 1.0.0 | bool | Disable TLS certificate validation for the LDAP connections. Do not set this in production environments. | "false" | | `OC_LDAP_LOOKUP_CACHE_TTL` | 7.5.0 | Duration | The time to live for the in-memory cache of LDAP lookups. This cache is used to reduce the number of LDAP queries for user and group lookups. | "10s" | | `OC_LDAP_SERVER_WRITE_ENABLED` | 1.0.0 | bool | Allow creating, modifying and deleting LDAP users via the GRAPH API. This can only be set to 'true' when keeping default settings for the LDAP user and group attribute types (the 'OC_LDAP_USER_SCHEMA_* and 'OC_LDAP_GROUP_SCHEMA_* variables). | "true" | -| `OC_LDAP_URI` | 1.0.0 | string | Url of the LDAP service to use as IDP. | "ldap://localhost:9236" | +| `OC_LDAP_URI` | 1.0.0 | string | URI of the LDAP Server to connect to. Supported URI schemes are 'ldaps://' and 'ldap://' | "ldap://localhost:9236" | | `OC_LDAP_USER_BASE_DN` | 1.0.0 | string | Search base DN for looking up LDAP users. | "ou=users,o=libregraph-idm" | -| `OC_LDAP_USER_ENABLED_ATTRIBUTE` | 1.0.0 | string | LDAP Attribute to use as a flag telling if the user is enabled or disabled. | "openCloudUserEnabled" | +| `OC_LDAP_USER_ENABLED_ATTRIBUTE` | 1.0.0 | string | LDAP attribute to use as a flag telling if the user is enabled or disabled. | "openCloudUserEnabled" | | `OC_LDAP_USER_FILTER` | 1.0.0 | string | LDAP filter to add to the default filters for user search like '(objectclass=openCloudUser)'. | "" | -| `OC_LDAP_USER_OBJECTCLASS` | 1.0.0 | string | LDAP User ObjectClass like 'inetOrgPerson'. | "inetOrgPerson" | +| `OC_LDAP_USER_OBJECTCLASS` | 1.0.0 | string | The object class to use for users in the default user search filter ('inetOrgPerson'). | "inetOrgPerson" | | `OC_LDAP_USER_SCHEMA_DISPLAYNAME` | 1.0.0 | string | LDAP Attribute to use for the displayname of users. | "displayname" | -| `OC_LDAP_USER_SCHEMA_ID` | 1.0.0 | string | LDAP User UUID attribute like 'uid'. | "openCloudUUID" | +| `OC_LDAP_USER_SCHEMA_ID` | 1.0.0 | string | LDAP Attribute to use as the unique id for users. This should be a stable globally unique id like a UUID. | "openCloudUUID" | | `OC_LDAP_USER_SCHEMA_ID_IS_OCTETSTRING` | 1.0.0 | bool | Set this to true if the defined 'ID' attribute for users is of the 'OCTETSTRING' syntax. This is e.g. required when using the 'objectGUID' attribute of Active Directory for the user ID's. | "false" | -| `OC_LDAP_USER_SCHEMA_MAIL` | 1.0.0 | string | LDAP User email attribute like 'mail'. | "mail" | +| `OC_LDAP_USER_SCHEMA_MAIL` | 1.0.0 | string | LDAP Attribute to use for the email address of users. | "mail" | | `OC_LDAP_USER_SCHEMA_TENANT_ID` | 4.0.0 | string | LDAP Attribute to use for the tenant ID of users. This is used to identify the tenant of a user in a multi-tenant environment. | "" | -| `OC_LDAP_USER_SCHEMA_USERNAME` | 1.0.0 | string | LDAP User name attribute like 'displayName'. | "displayName" | +| `OC_LDAP_USER_SCHEMA_USERNAME` | 1.0.0 | string | LDAP Attribute to use for username of users. | "uid" | | `OC_LDAP_USER_SCHEMA_USER_TYPE` | 1.0.0 | string | LDAP Attribute to distinguish between 'Member' and 'Guest' users. Default is 'openCloudUserType'. | "openCloudUserType" | | `OC_LDAP_USER_SCOPE` | 1.0.0 | string | LDAP search scope to use when looking up users. Supported scopes are 'base', 'one' and 'sub'. | "sub" | | `OC_LOG_LEVEL` | 1.0.0 | string | The log level. Valid values are: 'panic', 'fatal', 'error', 'warn', 'info', 'debug', 'trace'. | "error" | | `OC_MACHINE_AUTH_API_KEY` | 1.0.0 | string | Machine auth API key used to validate internal requests necessary for the access to resources from other services. | "" | | `OC_MAX_CONCURRENCY` | 1.0.0 | int | Maximum number of concurrent go-routines. Higher values can potentially get work done faster but will also cause more load on the system. Values of 0 or below will be ignored and the default value will be used. | "5" | | `OC_METADATA_PREFIX` | next | string | The attribute key prefix of the metadata on disk. Defaults to the native 'user.oc.' prefix. It applies to all storage drivers of the instance, they must share the prefix because it is set process wide. | "" | -| `OC_OIDC_CLIENT_ID` | 6.0.0 | string | The OIDC client ID for Android app. | "OpenCloudAndroid" | +| `OC_OIDC_CLIENT_ID` | 1.0.0 | string | The OIDC client ID which OpenCloud Web uses. This client needs to be set up in your IDP. Note that this setting has no effect when using the builtin IDP. | "web" | | `OC_OIDC_CLIENT_SCOPES` | 6.0.0 | []string | The OIDC client scopes the Android app should request. | "[openid profile email offline_access]" | -| `OC_OIDC_ISSUER` | 1.0.0 | string | The OIDC issuer URL to use. | "https://localhost:9200" | +| `OC_OIDC_ISSUER` | 1.0.0 | string | The identity provider value to set in the group IDs of the CS3 group objects for groups returned by this group provider. | "https://localhost:9200" | | `OC_PASSWORD_POLICY_BANNED_PASSWORDS_LIST` | 1.0.0 | string | Path to the 'banned passwords list' file. This only impacts public link password validation. See the documentation for more details. | "" | | `OC_PASSWORD_POLICY_DISABLED` | 1.0.0 | bool | Disable the password policy. Defaults to false if not set. | "false" | | `OC_PASSWORD_POLICY_MIN_CHARACTERS` | 1.0.0 | int | Define the minimum password length. Defaults to 8 if not set. | "8" | @@ -92,14 +92,14 @@ | `OC_PASSWORD_POLICY_MIN_LOWERCASE_CHARACTERS` | 1.0.0 | int | Define the minimum number of uppercase letters. Defaults to 1 if not set. | "1" | | `OC_PASSWORD_POLICY_MIN_SPECIAL_CHARACTERS` | 1.0.0 | int | Define the minimum number of characters from the special characters list to be present. Defaults to 1 if not set. | "1" | | `OC_PASSWORD_POLICY_MIN_UPPERCASE_CHARACTERS` | 1.0.0 | int | Define the minimum number of lowercase letters. Defaults to 1 if not set. | "1" | -| `OC_PERSISTENT_STORE` | 1.0.0 | string | The type of the store. Supported values are: 'memory', 'redis-sentinel', 'nats-js-kv', 'noop'. See the text description for details. | "nats-js-kv" | -| `OC_PERSISTENT_STORE_AUTH_PASSWORD` | 1.0.0 | string | The password to authenticate with the store. Only applies when store type 'nats-js-kv' is configured. | "" | -| `OC_PERSISTENT_STORE_AUTH_USERNAME` | 1.0.0 | string | The username to authenticate with the store. Only applies when store type 'nats-js-kv' is configured. | "" | -| `OC_PERSISTENT_STORE_ENABLE_TLS` | 7.3.0 | bool | Enable TLS for the connection to the store. Only applies when store type 'nats-js-kv' is configured. | "false" | -| `OC_PERSISTENT_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]" | -| `OC_PERSISTENT_STORE_TLS_INSECURE` | 7.3.0 | bool | Whether to verify the server TLS certificates. | "false" | -| `OC_PERSISTENT_STORE_TLS_ROOT_CA_CERTIFICATE` | 7.3.0 | string | The root CA certificate used to validate the server's TLS certificate. If provided POSTPROCESSING_STORE_TLS_INSECURE will be seen as false. | "" | -| `OC_PERSISTENT_STORE_TTL` | 1.0.0 | Duration | Time to live for events in the store. See the Environment Variable Types description for more details. | "168h0m0s" | +| `OC_PERSISTENT_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_AUTH_PASSWORD` | 7.4.0 | string | The password to authenticate with the store. | "" | +| `OC_PERSISTENT_STORE_AUTH_USERNAME` | 7.4.0 | string | The username to authenticate with the store. | "" | +| `OC_PERSISTENT_STORE_ENABLE_TLS` | 7.4.0 | bool | Enable TLS for the connection to the store. | "false" | +| `OC_PERSISTENT_STORE_NODES` | 7.4.0 | []string | A list of nodes to access the NATS JetStream store. See the Environment Variable Types description for more details. | "[127.0.0.1:9233]" | +| `OC_PERSISTENT_STORE_TLS_INSECURE` | 7.4.0 | bool | Whether to verify the server TLS certificates. | "false" | +| `OC_PERSISTENT_STORE_TLS_ROOT_CA_CERTIFICATE` | 7.4.0 | string | The root CA certificate used to validate the server's TLS certificate. If provided WEB_STORE_TLS_INSECURE will be seen as false. | "" | +| `OC_PERSISTENT_STORE_TTL` | 1.0.0 | Duration | Time to live for events in the store. Defaults to '30m' (30 minutes). See the Environment Variable Types description for more details. | "30m0s" | | `OC_REVA_GATEWAY` | 1.0.0 | string | The CS3 gateway endpoint. | "eu.opencloud.api.gateway" | | `OC_SERVICE_ACCOUNT_ID` | 1.0.0 | string | The ID of the service account the service should use. See the 'auth-service' service description for more details. | "" | | `OC_SERVICE_ACCOUNT_SECRET` | 1.0.0 | string | The service account secret. | "" | @@ -107,12 +107,12 @@ | `OC_SHARING_PUBLIC_WRITEABLE_SHARE_MUST_HAVE_PASSWORD` | 1.0.0 | bool | Set this to true if you want to enforce passwords on Uploader, Editor or Contributor shares. If not using the global OC_SHARING_PUBLIC_WRITEABLE_SHARE_MUST_HAVE_PASSWORD, you must define the FRONTEND_OCS_PUBLIC_WRITEABLE_SHARE_MUST_HAVE_PASSWORD (deprecated) in the frontend service. | "false" | | `OC_SHOW_USER_EMAIL_IN_RESULTS` | 1.0.0 | bool | Include user email addresses in responses. If absent or set to false emails will be omitted from results. Please note that admin users can always see all email addresses. | "false" | | `OC_SPACES_MAX_QUOTA` | 1.0.0 | uint64 | Set a global max quota for spaces in bytes. A value of 0 equals unlimited. If not using the global OC_SPACES_MAX_QUOTA, you must define the FRONTEND_MAX_QUOTA in the frontend service. | "0" | -| `OC_SYSTEM_USER_API_KEY` | 4.0.0 | string | API key for the STORAGE-SYSTEM system user. | "" | -| `OC_SYSTEM_USER_ID` | 4.0.0 | string | ID of the OpenCloud STORAGE-SYSTEM system user. Admins need to set the ID for the STORAGE-SYSTEM system user in this config option which is then used to reference the user. Any reasonable long string is possible, preferably this would be an UUIDv4 format. | "" | -| `OC_SYSTEM_USER_IDP` | 4.0.0 | string | IDP of the OpenCloud STORAGE-SYSTEM system user. | "internal" | +| `OC_SYSTEM_USER_API_KEY` | 1.0.0 | string | API key for the STORAGE-SYSTEM system user. | "" | +| `OC_SYSTEM_USER_ID` | 1.0.0 | string | ID of the OpenCloud storage-system system user. Admins need to set the ID for the STORAGE-SYSTEM system user in this config option which is then used to reference the user. Any reasonable long string is possible, preferably this would be an UUIDv4 format. | "" | +| `OC_SYSTEM_USER_IDP` | 1.0.0 | string | IDP of the OpenCloud STORAGE-SYSTEM system user. | "internal" | | `OC_TRANSFER_SECRET` | 7.5.0 | string | The storage transfer secret. | "" | | `OC_TRANSLATION_PATH` | 1.0.0 | string | (optional) Set this to a path with custom translations to overwrite the builtin translations. Note that file and folder naming rules apply, see the documentation for more details. | "" | -| `OC_URL` | 1.0.0 | string | The OIDC issuer URL to use. | "https://localhost:9200" | +| `OC_URL` | 1.0.0 | string | The public facing URL of the OpenCloud frontend. | "https://localhost:9200" | | `OC_WOPI_DISABLE_CHAT` | 1.0.0 | bool | Disable chat in the office web frontend. This feature applies to OnlyOffice and Microsoft. | "false" | | `SEARCH_EVENTS_ACK_WAIT` | 4.0.0 | Duration | The time to wait for an ack before the message is redelivered. This is used to ensure that messages are not lost if the consumer crashes. | "1m0s" | | `SEARCH_EVENTS_MAX_ACK_PENDING` | 4.0.0 | int | The maximum number of unacknowledged messages. This is used to limit the number of messages that can be in flight at the same time. | "10000" | @@ -120,5 +120,5 @@ | `STORAGE_GRPC_ADDR` | 1.0.0 | string | GRPC address of the STORAGE-SYSTEM service. | "eu.opencloud.api.storage-system" | | `STORAGE_USERS_ASYNC_PROPAGATOR_PROPAGATION_DELAY` | 1.0.0 | Duration | The delay between a change made to a tree and the propagation start on treesize and treetime. Multiple propagations are computed to a single one. See the Environment Variable Types description for more details. | "0s" | | `STORAGE_USERS_PERMISSION_ENDPOINT` | 1.0.0 | string | Endpoint of the permissions service. The endpoints can differ for 'decomposed' and 'decomposeds3'. | "eu.opencloud.api.settings" | -| `WEB_OIDC_CLIENT_ID` | 6.0.0 | string | The OIDC client ID for the OpenCloud web client. The 'WEB_OIDC_CLIENT_ID' setting is only here for backwards compatibility and will be removed in a future release. | "web" | -| `WEB_OIDC_SCOPE` | 6.0.0 | []string | The OIDC client scopes the OpenCloud web client should request. The 'WEB_OIDC_SCOPE' setting is only here for backwards compatibility and will be removed in a future release. | "[openid profile email]" | +| `WEB_OIDC_CLIENT_ID` | 1.0.0 | string | The OIDC client ID which OpenCloud Web uses. This client needs to be set up in your IDP. Note that this setting has no effect when using the builtin IDP. | "web" | +| `WEB_OIDC_SCOPE` | 1.0.0 | string | OIDC scopes to request during authentication to authorize access to user details. Defaults to 'openid profile email'. Values are separated by blank. More example values but not limited to are 'address' or 'phone' etc. | "openid profile email" | diff --git a/docs/_static/env-vars/storage-users_configvars.md b/docs/_static/env-vars/storage-users_configvars.md index db78efc0..3d6aa5f8 100644 --- a/docs/_static/env-vars/storage-users_configvars.md +++ b/docs/_static/env-vars/storage-users_configvars.md @@ -1,5 +1,5 @@ -2026-10-13-00-11-11 +2026-10-14-00-06-59 ## Deprecation Notice diff --git a/docs/_static/env-vars/web_configvars.md b/docs/_static/env-vars/web_configvars.md index 89745b89..8cea7965 100644 --- a/docs/_static/env-vars/web_configvars.md +++ b/docs/_static/env-vars/web_configvars.md @@ -1,5 +1,5 @@ -2026-10-13-00-11-11 +2026-10-14-00-06-59 ## Deprecation Notice