* jmap/EmailCreate: add more attributes that were omitted: Headers,
InReplyTo, References, Sender
* add jmap GetEmailSubmissionStatus
* improve email integration tests by adding a thorough test for email
submission
* jmap integration tests: provision principals and domains using the
Stalwart Management API, switching from an in-memory to an internal
directory
* fix a bug in how email summaries are flattened across multiple
accounts, which was previous resulting in empty email objects
* allow negative offset in email pagination
* make all /emails endpoints return emails without bodies
* implement Request.AllAccountIds() to generalize the fetching (and
uniqifying) of all account IDs, which will allow us to implement
things such as "subscribed" accounts, or limiting the number of
accounts in one request
* add Account-Id response header
* add Object-Type response header
* upgrade Stalwart image for devtools/full to 0.14.1
* re-assert which features are implemented or not in 0.14.1
* refactor the integration tests yet again to make it clearer and
easier to see those "features-or-not"
* get rid of old tests that are now better covered by integration tests
* rewrite how we compare expected and actual objects in integration
tests, finally having found a way to ignore the @type attribute
properly instead of having to mutate all objects to remove it
* add endpoints for Mailboxes:
- PATCH mailboxes/{id}
- DELETE mailboxes/{id}
- POST mailboxes
* refactor the pkg/jmap and groupware framework to systematically
return a jmap.State out-of-band of the per-method payloads, since
they are almost always present in JMAP responses, which lead to the
artificial creation of a lot of composed struct types just to also
return the State; on the downside, it adds yet another return
parameter
* upgrade image version in devtools to 0.14.0
* fix idmldap configuration to use the cn attribute in order for that
to also work for groups (groups don't have a uid attribute in the IDM
built-in LDAP)
* group resources are now checked against LDAP, changed
demo-principals.yaml accordingly to refer to a group that exists in
LDAP as part of the demo data
* made several email related operations multi-account:
QueryEmailSnippets, QueryEmails, QueryEmailsWithSnippets
* add GetIdentitiesForAllAccounts
* add GetEmailsForAllAccounts
* jmap: add CreateIdentity, UpdateIdentity; groupware: add
GetIdentityById, AddIdentity, ModifyIdentity
* add temporary workaround until Calendars, Tasks, Contacts are
implemented in Stalwart when determining the default account for
those: use the mail one in the mean time
* changes from 0.13.4:
- JMAP: Protocol layer rewrite for zero-copy deserialization and
architectural improvements.
- IMAP: Unbounded memory allocation in request parser
(CVE-2025-61600)
- IMAP: Wrong permission checked for GETACL.
- JMAP: References to previous method fail when there are no results
(stalwartlabs#1507).
- JMAP: Enforce quota checks on Blob/copy.
- JMAP: Mailbox/get fails without accountId argument (stalwartlabs#1936).
- JMAP: Do not return invalidProperties when email update doesn't
contain changes (stalwartlabs#1139)
- iTIP: Include date properties in REPLY (stalwartlabs#2102).
- OIDC: Do not set username field if it is the same as the email field.
- Telemetry: Fix calculateMetrics housekeeper task (stalwartlabs#2155).
- Directory: Always use rsplit to extract the domain part from email
addresses.
* changes from 0.13.3:
- CLI: Health checks
- WebDAV: Assisted discovery v2
- iTIP: Do not send a REPLY when deleting an event that was not
accepted.
- iTIP: Include event details in REPLY messages (stalwart#2102).
- iTIP: Add organizer to iMIP replies if missing to deal with MS
Exchange 2010 bug.
- OIDC: Do not overwrite locally defined aliases (stalwart#2065).
- HTTP: Scan ban should only be triggered by HTTP parse errors.
- HTTP: Skip scanner fail2ban checks when the proxy client IP can't
be parsed (stalwart#2121).
- JMAP: Do not allow roles to be removed from system mailboxes
(stalwart#1977).
- JMAP WS: Fix panic when using invalid server url.
- SMTP: Do no send EHLO twice when STARTTLS is unavailable
(stalwart#2050).
- IMAP: Allow ENABLE UTF8 in IMAPrev1.
- IMAP: Include administer permission in ACL responses.
- IMAP: Add owner rights to ACL get responses.
- IMAP: Do not auto-train Bayes when moving messages from Junk to
Trash.
- IMAP/ManageSieve: Increase maximum quoted argument size
(stalwart#2039).
- CalDAV: Limit recurrence expansions in calendar reports
(CVE-2025-59045).
- WebDAV: Do not fix percent encoding on WebDAV FS (stalwart#2036).
* made a few changes in order to further simplify the setup for
developers of the Groupware backend
* add STALWART_DOMAIN to deployments/examples/opencloud_full/.env
* adapt the Stalwart configuration file to not set server.hostname and,
instead, pick it up from /etc/hostname, which is set by Docker
Compose as we can use default values for STALWART_DOMAIN there, in an
analogous fashion to the other containers in that project
* add config/keycloak/clients/groupware.json to avoid requiring manual
configuration of Keycloak via the admin web UI
* Stalwart container:
- listen for SMTPS on :1465
- remove the stalwart-logs volume, not needed (logs are going to
stdout)
* updated services/groupware/DEVELOPER.md:
- refer to a variable OCDIR to make instructions more copy-pasteable
- remove manual Keycloak configuration section as it is now obsolete,
replaced by provisioning a configuration file instead
Minor: be more Go idiomatic: just use a function to pick the attachment
from an Email's attachment list instead of using an interface with
multiple iplementation structs.
* fix(jmap): fix bug where CommandBlobUpload was used instead of
CommandBlobGet in GetBlob (now GetBlobMetadata)
* we currently don't need a variant of BlobGetCommand that also
retrieves the content of the blob, instead we only use it for
retrieving metadata about it
* the JMAP error handling was not working properly, fixed it and added
error definitions accordingly
* add operations to retrieve mailbox roles and mailboxes by role for
all accounts
There was really no reason to go with "Messages" as far as the
vocabulary of the Groupware API goes, since the objects those APIs serve
are "Emails", to stick with the wording of the JMAP specification.
* introduce a function 'mcid' to assemble method call IDs per account
instead of doing that inline in each function, in case the rules for
doing so change in the future
* move jmap.request() to jmap.Client.request() and pass the Session
and a Logger to introduce checking the number of methodCalls within a
request not exceeding the limit of the Session, as well as error
handling and logging there instead of in each caller
* a few bugfixes:
- add a few missing Send() calls in logs
- correct the response tag matching for
GetMailboxChangesForMultipleAccounts
- fix typo in Identity.ReplyTo json serialization rune
- fix response tag in pkg/jmap/testdata/mailboxes1.json after
changing them to be prefixed by the accountId
* add a launcher for running OpenCloud from within VSCode, but using
third-party services that are running within the docker compose
'full' example setup
* add URL to retrieve all the mailboxes for all the accounts of a user,
as a first use-case for an all-accounts operation, as
/accounts/all/mailboxes
* add URL to retrieve mailbox changes for all the mailboxes of all the
accounts of a user, as a first use-case for an all-accounts
operation, as /accounts/all/mailboxes/changes
* change the defaultAccountId from '*' to '_', as '*' rather indicates
"all" than "default", and we might want to use that for "all
accounts" operations in the future
* refactor(groupware): remove the accountId parameter from the logger()
function, as it is not used anyways, but also confusing for
operations that support multiple account ids
* refactor some pkg/jmap and groupware methods to make more sense from
an API point-of-view
* add path parameter documentation, but automate it by injecting their
definition into the OpenAPI YAML tree that is extracted from the
source code using go-swagger as it is too cumbersome, repetitive and
error-prine to document them in the source code; wrote a TypeScript
file apidoc-process.ts to do so
* add generating an offline HTML file for the OpenAPI documentation
using redocly, and injecting a favicon into the resulting HTML; wrote
a TypeScript file apidoc-postprocess-html.ts to do so
* move the logging of the username and session state away from pkg/jmap
and into services/groupware
* introduce more decoupling for the session cache, as well as moving
the implementation into groupware_session.go
* remove the baseurl from the JMAP client configuration, and pass it to
the session retrieval functions instead, as that is really the only
place where it is relevant, and we gain flexibility to discover that
session URL differently in the future without having to touch the
JMAP client
* move the default account identifier handling from the JMAP package to
the Groupware one, as it really has nothing to do with JMAP itself,
and is an opinionated feature of the Groupware REST API instead
* add an event listener interface for JMAP events to be more flexible
and universal, typically for metrics that are defined on the API
level that uses the JMAP client
* add errors for when default accounts cannot be determined
* split groupware_framework.go into groupware_framework.go,
groupware_request.go and groupware_response.go
* move the accountId logging into the Groupware level instead of JMAP
since it can also be relevant to other operations that might be
worthy of logging before the JMAP client is even invoked
* implement more metrics, in a more streamlined fashion
* use concurrent-map to store SSE streams instead of a regular map with
one big lock that will not scale when it grows, causing too much
contention on that one lock
* while testing error metrics, noticed a few bugs with error handling
when Stalwart is down: fixed
* implement correct Etag and If-None-Match handling, responding with
304 Not Modified if they match
* introduce SessionState and State string type aliases to ensure we are
using the correct fields for those, respectively
* extract the SessionState from the JMAP response bodies in the
groupware framework instead of having to do that in every single
groupware API
* use uint instead of int in some places to clarify that the values are
>= 0
* trace-log how long a Session was held in cache before being evicted
* add Trace-Id header handling: add to response when specified in
request, and implement a custom request logger to include it as a
field
* implement a more compact trace-logging of all the methods and URIs
that are served, to put them into a single log entry instead of
creating one log entry for every URI
* add a GET /accounts/{a}/boostrap URI that delivers the same as GET /
but also mailboxes for a given account, in case the UI remembers the
last used account identifier, to avoid an additional roundtrip
* streamline the use of simpleError()
* add logging of errors at the calling site
* add logging of evictions of Sessions from the cache
* change default Session cache TTL to 5min instead of 30sec
* add more documentation for properties
* fixes after a bit of trial-and-error with go-swagger
* fix email filter marshalling when there are no search criteria
* introduce an apidoc.yml that contains Swagger data and is merged when
generating the swagger.yml from sources
* ensure that all the jmap responses contain the SessionState
* implement missing errors that were marked as TODO
* moved common functions from pkg/jmap and pkg/services/groupware to
pkg/log and pkg/structs to commonalize them across both source trees
* implement error handling for SetError occurences
* Email: replace anonymous map[string]bool for mailbox rights with a
MailboxRights struct, as the keys are well-defined, which allows for
properly documenting them
* introduce ObjectType as an "enum"
* fix JSON marshalling and unmarshalling of EmailBodyStructure
* move the swagger documentation structs from groupware_api.go to
groupware_docs.go
* fix: change verb for /groupware/accounts/*/vacation from POST to PUT
* refactor the jmap package to split it into several files as the
jmap.api.go file was becoming too unwieldy
* refactor the Groupware handler function response to be a Response
object, to be more future-proof and avoid adding more and more
return parameters while handling "no content" response as well
* more godoc for the JMAP model
* add Email creation, updating, deleting (Email/set,
EmailSubmission/set)
* add endpoints
- POST /accounts/{accountid}/messages
- PATCH|PUT /accounts/{accountid}/messages/{messageid}
- DELETE /accounts/{accountid}/messages/{messageid}
* after having decided that the Groupware API should be a standalone
independent custom REST API that is using JMAP data models as much as
possible,
* removed Groupware APIs from the Graph service
* moved Groupware implementation to the Groupware service, and
refactored a few things accordingly
* refactored the models to be strongly typed with structs and mapstruct
to decompose the dynamic parts of the JMAP payloads
* externalized large JSON strings for tests into .json files under
testdata/
* added a couple of fantasy Graph groupware APIs to explore further
options
* added k6 scripts to test those graph/me/messages APIs, with a setup
program to set up users in LDAP, fill their IMAP inbox, activate them
in Stalwart, cleaning things up, etc...
* primitive implementation to demonstrate how it could work, still to
be considered WIP at best
* add new dependency: MicahParks/jwkset and MicahParks/keyfunc to
retrieve the JWK set from KeyCloak to verify the signature of the
JWTs sent as part of Bearer authentication in the /auth API
* (minor) opencloud/.../service.go: clean up a logging statement that
was introduced earlier to hunt down why the auth-api service was not
being started
fix opensearch client certificate
well ... technically it is not a fix. We expected the certificate on the CLI to be in PEM format. so, it would have worked if you used sth. like:
```console
export SEARCH_ENGINE_OPEN_SEARCH_CLIENT_CA_CERT="-----BEGIN CERTIFICATE-----
MIIDXTCCAkWgAwIBAgIJAKJ...
...
-----END CERTIFICATE-----"
```
which was different than all our other cert env vars, which take a path.
When events occur in the supervisor, log them as FATAL when appropriate
(panic and termination when not restarting) instead of always using
INFO, and include more information such as the service name and the
current failures, etc..., rather than the generic message that was used
so far.
This set the 'IsAdminUser' Property correctly in the CheckFileInfo
Response. For that a new Permission 'WebOffice.Manage' is introduced. By
default this permission is only assigned to the Admin role.
User with this permission get access to certain admin features in
Collabora (e.g. the 'Server Audit' dashboard)
Closes: #796
When OC_URL_SIGNING_SECRET is not set. Fall back to the value of the
reva transfer token. This allows handling upgrades on a instance that
was created before the OC_URL_SIGNING_SECRET was introduced to be
handled more graceful.
Unfortunately this still only works reliably for single instance
deployments (or instance that where bootstrapped using 'opencloud init')
that are guaranteed to have the transfer token available.
When running 'proxy' and 'ocdav' as separate services the upgrade might
still require manual intervention.
This is required for allowing the web office to download images to
insert into documents.
The secret is generated by `opencloud init` and the server refuses
to start now without a secret being set. (Breaking Change)
Also the setting is now moved to the shared options as all involved
services need the same secret to work properly.
Related: https://github.com/opencloud-eu/web/issues/704
The readyz endpoint contained unconditional checks for the LDAP and nats
endpoints. Depending on configuration neihter LDAP nor NATS might be
required.
Fix the ordering of the env vars for the 'set_default_assignments'
setting. The service specific variable ('SETTINGS_SETUP_DEFAULT_ASSIGNMENTS')
should take precedence over other variable ('IDM_CREATE_DEMO_USERS' in
this case).
This allows to pass the multi-tenant enablement flag as a shared config
option to the reva service. This needs to be done for all reva services
since it ends up in a global variable in reva that is only initialized
once, by the service that is the first to parse its config.
See https://github.com/opencloud-eu/opencloud/issues/1563 for details.
* fix: collaboration service name
* change: do not use app name in service name
* feat: make collaboration service name configurable
* test: fix test config
We agreed to move the 'opencloud_full' example to a new directory to
avoid confusion with the supported compose examples in
opencloud-compose.
This commit keeps the bare-metal example in place as that is still
mentioned in the documentation.
Up to now we only set the OpaqueId attribute, which breaks sharing as soon as
multi-tenancy is enabled. We need the full UserId (including the
tenantId and the idp value).
Related Issue: #1194
* remove opencloud_full from the read.me and add opencloud-compose instead
* remove wrong changes
* add eicar file which accendially was removed
* replace eicar.zip
This reverts parts of commit 926a2c2080.
The LDAP identity backend of the graph service was supposed to stay single-tenant
only. The focus for multi-tenancy should be on the CS3 identity backend.
Also lets keep the internal IDM and demo users clean of any
multi-tenancy stuff for now.
Due to the sunsetting of the Docker Hub bitnami repository on 2025-09-28, use the `bitnamilegacy/openldap:2.6 `container image instead of `bitnami/openldap:2.6`
Due to the sunsetting of the Docker Hub bitnami repository on
2025-09-28, use the bitnamilegacy/openldap:2.6 container image instead
of bitnami/openldap:2.6, also in .woodpecker.star
Due to the sunsetting of the Docker Hub bitnami repository on
2025-09-28, use the bitnamilegacy/openldap:2.6 container image instead
of bitnami/openldap:2.6
The collaborative mode of posixfs does currently not support the creation
and removal of spaces directly on the file system. This has to happen
via the graph API.
The STORAGE_USERS_DATA_GATEWAY_URL env var is used in the `tokens` `datagateway_endpoint` reva configuration. That `DataGatewayEndpoint` is used by the decomposedfs driver to create urls:
```go
// URL returns a url to download an upload
func (session *DecomposedFsSession) URL(_ context.Context) (string, error) {
// [ ... ]
return joinurl(session.store.tknopts.DataGatewayEndpoint, tkn), nil
}
```
As the comment points out this URL is internally used when emitting events. Either in:
```go
func (session *DecomposedFsSession) FinishUploadDecomposed(ctx context.Context) error {
// [ ... ]
s, err := session.URL(ctx)
if err != nil {
return err
}
var iu *userpb.User
if utils.ExistsInOpaque(u.Opaque, "impersonating-user") {
iu = &userpb.User{}
if err := utils.ReadJSONFromOpaque(u.Opaque, "impersonating-user", iu); err != nil {
return err
}
}
if err := events.Publish(ctx, session.store.pub, events.BytesReceived{
UploadID: session.ID(),
URL: s,
```
or in
```go
// Postprocessing starts the postprocessing result collector
func (fs *Decomposedfs) Postprocessing(ch <-chan events.Event) {
// [ ... ]
s, err := session.URL(ctx)
if err != nil {
sublog.Error().Err(err).Msg("could not create url")
continue
}
metrics.UploadSessionsRestarted.Inc()
// restart postprocessing
if err := events.Publish(ctx, fs.stream, events.BytesReceived{
UploadID: session.ID(),
URL: s,
```
So, we do not need to go throught the proxy here.
* Dockerfile.multiarch: use bind- and cache-mounts to speedup build
Use a cache mount for go build cache in the build container and mount
the sources as a bind mount as recommended in
https://docs.docker.com/build/cache/optimize/ this largely speeds up the
container build for subsequent builds.
* Use Dockerfile.multiarch for "dev-docker" target
Let's remove some redundancy. AFAICS the Docker.multiarch does
everything the Docker.linux.* files did. And with the build caches
enable it should be just as quick as building on the host.
* Dockerfile.multiarch: Align the alpine version of the base images
* Dockerfile: Reduce build context by adding more files to .dockerignore
- Add 'posix' to the list of supported values
- Correct the default value from 'decomposed' to 'posix'
- Add brief description of the posix driver
Fixes: #1304
With the ocdav service being able to provided signed download URLs we
need the proxy to be able to verify the signatures.
This should also be a first step towards phasing out the weird ocs based
client side signed urls.
Related Tickets: #1104
The expirationDate for new shares needs to be in the future. Using
static dates in the tests means we need to update them every now an
then. This adjusts the helpers to allow relative date formats like
"+3 days" and "tomorrow" when creating shares.
This allows more direct control of the nats events. As a first step
we'll now acknowledge events manually, but in the future we'll add
metrics etc. to gain more insight into the queues.
* feat: adjust space template image to match brand color
* temporally skip user-settings e2e tests
---------
Co-authored-by: Viktor Scharf <v.scharf@opencloud.eu>
Maintaining the positioning of the files from v2 to reduce cognitive
load.
Indentation of yaml files now matches `.editorconfig`.
All mock files regenerated.
Added empty `{}` following convention from `mockery init` etc.
Removed directory specification where it would already match.
After autoprovisioning a user, we need to get a reva token via
`auth-machine`. If that fails the code would panic because the logger
tried to access the `user` object returned from the GetUserByClaims
call. Which is `nil`in case failure.
Fixes#936
Also split the list of activities in different chunks, one per buffered
write. That allows for scaling the service horizontally and also helps
reduce the load caused by the write operations.
The ODATA spec is not exactly clear about the semantics here:
"The semantics of system query options applied to POST requests to
entity sets as well as all PATCH, PUT and DELETE requests are not
defined by this specification and are reserved for future versions."
And currently we don't really need that anyway.
Only enable trace and/or debug logging when the outer logger has the
log level set accordingly. Even when the though the messages where not
really logged the nats service wasted quite some cycles especially in
the trace log related code path.
Related issue: #716
This introduces the "additional_headers", "remote_user_header" and
"skip_x_access_token" config keys to allow configuring routes to
external services that require addtional headers to be set.
"remote_user_header": defines the name of a Header that will carry the
userid of the authenticated user on the outgoing request.
"additional_headers": defines a list of header names and values that will
be added to outgoing requests on matching routes.
"skip_x_access_token": when set to true the reva access token will not
be added to the outgoing request.
Needed for #206
When successfully authenticating a user via apptoken, resolve the user's
roles and add the user and the token returned by the auth service to the
request context. Rely on the account_resolve middleware to add the reva
token to the outgoing request as the other auth middlewares do.
The app provider is called `CollaboraOnline` in the deployment example, not `Collabora`. Also switches the default app to Collabora for all mime types since it's the only app provider running per default.
* ldap setup
* run ldap in the opencloud full
* set admin user
* feat: use the shared LDAP schema and new phpldapadmin
* chore: change dc to match opencloud domain
---------
Co-authored-by: Michael Barz <michael.barz@zeitgestalten.eu>
* Harmonize Keycloak client configurations with built-in IdP
This change makes the Keycloak client configurations consistent with the built-in IdP:
1. Standardized client IDs to match built-in IdP:
- web (unchanged)
- OpenCloudDesktop (was random ID)
- OpenCloudAndroid (was random ID)
- OpenCloudIOS (was random ID)
- Cyberduck (simplified ID)
2. Updated domain names to use .eu consistently:
- Changed from opencloud.com to opencloud.eu for mobile apps
- Changed from hardcoded domains to templated {{OC_URL}} values
3. Updated redirect URIs to match built-in IdP format:
- Added specific callback paths for web client
- Removed wildcarded ports for desktop client
4. Changed mobile/desktop clients to public clients (equivalent to native app type)
5. Enhanced docker-entrypoint-override.sh to handle {{OC_URL}} template variables
These changes ensure a consistent authentication experience regardless of
whether users are using the built-in IdP or Keycloak.
* Harmonize Keycloak client configuration with client JSONs
Update the realm configuration to match the client configuration JSON files:
1. Update client IDs to match client JSON files:
- Changed 'xdXOt13JKxym1B1QcEncf2XDkLAexMBFwiT9j6EfhhHFJhs2KM9jbjTmf8JBXE69' to 'OpenCloudDesktop'
- Changed 'e4rAsNUSIUs0lF4nbv9FmCeUkTlV9GdgTLDH1b5uie7syb90SzEVrbN7HIpmWJeD' to 'OpenCloudAndroid'
- Changed 'mxd5OQDk6es5LzOzRvidJNfXLUZS2oN3oUFeXPP8LpPrhx3UroJFduGEYIBOxkY1' to 'OpenCloudIOS'
2. Fix additional client properties:
- Fix client names: Use proper capitalization for all clients
- Fix OAuth redirect URIs for Android and iOS to use .eu domain
- Fix Desktop URIs by removing wildcard asterisks
- Update post-logout redirect URIs to match client JSONs
- Set publicClient flag to true for all mobile/desktop clients
These changes ensure that when the realm is imported during deployment,
the client configurations will match the client JSONs exactly.
* Update web client configuration in Keycloak realm
Harmonize the web client configuration in the realm:
- Add 'OpenCloud Web App' client name
- Change URLs to use {{OC_URL}} template variables
- Update redirect URIs to use specific paths instead of wildcard
- Set backchannel logout URL to use templated URL
This completes the harmonization of all client configurations in the realm.
* Revert template variable approach in Keycloak configuration
Reverted templating changes to match upstream conventions:
1. Removed template variable handling from docker-entrypoint-override.sh
- Removed {{OC_URL}} replacement, keeping only domain replacement
This maintains compatibility with the upstream approach of using direct URLs
with domain substitution instead of template variables.
* Fix remaining old client ID references in role mappings
Updated the remaining references to old client IDs in the role mappings section:
- xdXOt13JKxym1B1QcEncf2XDkLAexMBFwiT9j6EfhhHFJhs2KM9jbjTmf8JBXE69 → OpenCloudDesktop
- e4rAsNUSIUs0lF4nbv9FmCeUkTlV9GdgTLDH1b5uie7syb90SzEVrbN7HIpmWJeD → OpenCloudAndroid
- mxd5OQDk6es5LzOzRvidJNfXLUZS2oN3oUFeXPP8LpPrhx3UroJFduGEYIBOxkY1 → OpenCloudIOS
This ensures all client ID references throughout the realm configuration are
consistent and use the simplified IDs.
The compose example lacked support for setting various SMTP related
config vars. Even though some of them where present in the '.env' file.
Closes: #511
* fix(collaboration): hide SaveAs and ExportAs buttons in collabora
---------
Co-authored-by: Viktor Scharf <v.scharf@opencloud.eu>
Co-authored-by: Viktor Scharf <scharf.vi@gmail.com>
Bumps Collabora in the deployment example to `24.04.13.2.1` and fixes the entrypoint. It seems to have changed with newer versions of the docker image, hence we need to specify the entrypoint manually to make the start commands work.
When started with the '--resume' command line switch the
'storage-users uploads sessions' was crashing because it did not
initialize the event queue correctly.
Fixes: #390
Instead of using the same hardcoded label for all app tokens, allow to
specify one on the API.
When an app token is generate via the impersonation feature we add the
string ` (Impersonation)` to the label.
the 'exclude' feature
(https://woodpecker-ci.org/docs/usage/workflow-syntax#path) does not
seem to provide # what we need. It seems to skip the build as soon as
one of the changed files matches an exclude pattern, we only # want to
skip of ALL changed files match. So skip this condition for now:
// user id of "admin", for user creation and admin role assignement
"OC_ADMIN_USER_ID":"some-admin-user-id-0000-000000000000",// FIXME currently must have the length of a UUID, see reva/pkg/storage/utils/decomposedfs/spaces.go:228
// admin user default password
"IDM_ADMIN_PASSWORD":"admin",
// system user
"OC_SYSTEM_USER_ID":"some-system-user-id-000-000000000000",// FIXME currently must have the length of a UUID, see reva/pkg/storage/utils/decomposedfs/spaces.go:228
- build(deps): bump golang.org/x/image from 0.30.0 to 0.31.0 [[#1552](https://github.com/opencloud-eu/opencloud/pull/1552)]
- build(deps): bump github.com/nats-io/nats.go from 1.45.0 to 1.46.0 [[#1551](https://github.com/opencloud-eu/opencloud/pull/1551)]
- build(deps): bump golang.org/x/crypto from 0.41.0 to 0.42.0 [[#1545](https://github.com/opencloud-eu/opencloud/pull/1545)]
- build(deps): bump github.com/testcontainers/testcontainers-go/modules/opensearch from 0.38.0 to 0.39.0 [[#1544](https://github.com/opencloud-eu/opencloud/pull/1544)]
- build(deps): bump github.com/open-policy-agent/opa from 1.6.0 to 1.8.0 [[#1510](https://github.com/opencloud-eu/opencloud/pull/1510)]
- build(deps): bump google.golang.org/grpc from 1.75.0 to 1.75.1 [[#1534](https://github.com/opencloud-eu/opencloud/pull/1534)]
- enhancement(docs): describe what and why ADRs [[#1518](https://github.com/opencloud-eu/opencloud/pull/1518)]
- enhancement(docs): add branch naming styleguide and clean up the contribution guidelines [[#1520](https://github.com/opencloud-eu/opencloud/pull/1520)]
- fix(search): readme typos and mention the lack of scalability [[#1516](https://github.com/opencloud-eu/opencloud/pull/1516)]
- enhancement(search): simplify search docs and document opensearch backend [[#1513](https://github.com/opencloud-eu/opencloud/pull/1513)]
- remove opencloud_full from the read.me and add opencloud-compose instead [[#1474](https://github.com/opencloud-eu/opencloud/pull/1474)]
### ✅ Tests
- [full-ci][tests-only] revert behat version and fix regex on test script [[#1507](https://github.com/opencloud-eu/opencloud/pull/1507)]
- update behat version in `composer.json` [[#1501](https://github.com/opencloud-eu/opencloud/pull/1501)]
- build(deps): bump github.com/onsi/ginkgo/v2 from 2.25.2 to 2.25.3 [[#1515](https://github.com/opencloud-eu/opencloud/pull/1515)]
- build(deps): bump google.golang.org/protobuf from 1.36.8 to 1.36.9 [[#1491](https://github.com/opencloud-eu/opencloud/pull/1491)]
- build(deps): bump go.opentelemetry.io/contrib/zpages from 0.62.0 to 0.63.0 [[#1490](https://github.com/opencloud-eu/opencloud/pull/1490)]
- build(deps): bump golang.org/x/text from 0.28.0 to 0.29.0 [[#1484](https://github.com/opencloud-eu/opencloud/pull/1484)]
- build(deps): bump github.com/spf13/afero from 1.14.0 to 1.15.0 [[#1483](https://github.com/opencloud-eu/opencloud/pull/1483)]
- build(deps): bump github.com/prometheus/client_golang from 1.23.0 to 1.23.2 [[#1476](https://github.com/opencloud-eu/opencloud/pull/1476)]
- build(deps): bump golang.org/x/sync from 0.16.0 to 0.17.0 [[#1477](https://github.com/opencloud-eu/opencloud/pull/1477)]
- build(deps): bump go.etcd.io/bbolt from 1.4.2 to 1.4.3 [[#1463](https://github.com/opencloud-eu/opencloud/pull/1463)]
- build(deps): bump github.com/go-chi/chi/v5 from 5.2.2 to 5.2.3 [[#1460](https://github.com/opencloud-eu/opencloud/pull/1460)]
- build(deps): bump github.com/grpc-ecosystem/grpc-gateway/v2 from 2.27.1 to 2.27.2 [[#1461](https://github.com/opencloud-eu/opencloud/pull/1461)]
- build(deps): bump github.com/spf13/cobra from 1.9.1 to 1.10.1 [[#1459](https://github.com/opencloud-eu/opencloud/pull/1459)]
- build(deps): bump github.com/riandyrn/otelchi from 0.12.1 to 0.12.2 [[#1456](https://github.com/opencloud-eu/opencloud/pull/1456)]
- build(deps): bump github.com/beevik/etree from 1.5.1 to 1.6.0 [[#1453](https://github.com/opencloud-eu/opencloud/pull/1453)]
- build(deps): bump github.com/blevesearch/bleve/v2 from 2.5.2 to 2.5.3 [[#1450](https://github.com/opencloud-eu/opencloud/pull/1450)]
- build(deps): bump go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp from 0.62.0 to 0.63.0 [[#1448](https://github.com/opencloud-eu/opencloud/pull/1448)]
- build(deps): bump go.opentelemetry.io/contrib/instrumentation/google.golang.org/grpc/otelgrpc from 0.62.0 to 0.63.0 [[#1446](https://github.com/opencloud-eu/opencloud/pull/1446)]
- build(deps): bump github.com/nats-io/nats-server/v2 from 2.11.7 to 2.11.8 [[#1410](https://github.com/opencloud-eu/opencloud/pull/1410)]
- build(deps): bump github.com/gabriel-vasile/mimetype from 1.4.9 to 1.4.10 [[#1413](https://github.com/opencloud-eu/opencloud/pull/1413)]
- build(deps): bump golang.org/x/net from 0.41.0 to 0.42.0 [[#1232](https://github.com/opencloud-eu/opencloud/pull/1232)]
- build(deps): bump github.com/KimMachineGun/automemlimit from 0.7.3 to 0.7.4 [[#1226](https://github.com/opencloud-eu/opencloud/pull/1226)]
- build(deps): bump golang.org/x/text from 0.26.0 to 0.27.0 [[#1227](https://github.com/opencloud-eu/opencloud/pull/1227)]
- build(deps): bump golang.org/x/sync from 0.15.0 to 0.16.0 [[#1209](https://github.com/opencloud-eu/opencloud/pull/1209)]
- build(deps): bump golang.org/x/term from 0.32.0 to 0.33.0 [[#1208](https://github.com/opencloud-eu/opencloud/pull/1208)]
- build(deps): bump github.com/olekukonko/tablewriter from 1.0.7 to 1.0.8 [[#1174](https://github.com/opencloud-eu/opencloud/pull/1174)]
- build(deps): bump github.com/nats-io/nats-server/v2 from 2.11.5 to 2.11.6 [[#1164](https://github.com/opencloud-eu/opencloud/pull/1164)]
- build(deps): bump github.com/go-playground/validator/v10 from 10.26.0 to 10.27.0 [[#1165](https://github.com/opencloud-eu/opencloud/pull/1165)]
- build(deps): bump github.com/pkg/xattr from 0.4.11 to 0.4.12 [[#1156](https://github.com/opencloud-eu/opencloud/pull/1156)]
- build(deps): bump go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp from 0.61.0 to 0.62.0 [[#1155](https://github.com/opencloud-eu/opencloud/pull/1155)]
- build(deps): bump github.com/open-policy-agent/opa from 1.5.1 to 1.6.0 [[#1148](https://github.com/opencloud-eu/opencloud/pull/1148)]
- build(deps): bump github.com/oklog/run from 1.1.0 to 1.2.0 [[#1150](https://github.com/opencloud-eu/opencloud/pull/1150)]
- build(deps): bump go.opentelemetry.io/contrib/instrumentation/google.golang.org/grpc/otelgrpc from 0.61.0 to 0.62.0 [[#1122](https://github.com/opencloud-eu/opencloud/pull/1122)]
- build(deps): bump go.opentelemetry.io/contrib/zpages from 0.61.0 to 0.62.0 [[#1123](https://github.com/opencloud-eu/opencloud/pull/1123)]
- build(deps): bump go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracegrpc from 1.36.0 to 1.37.0 [[#1111](https://github.com/opencloud-eu/opencloud/pull/1111)]
- build(deps): bump go.opentelemetry.io/otel from 1.36.0 to 1.37.0 [[#1112](https://github.com/opencloud-eu/opencloud/pull/1112)]
- build(deps): bump github.com/go-chi/chi/v5 from 5.2.1 to 5.2.2 [[#1075](https://github.com/opencloud-eu/opencloud/pull/1075)]
- build(deps): bump github.com/grpc-ecosystem/grpc-gateway/v2 from 2.26.3 to 2.27.0 [[#1072](https://github.com/opencloud-eu/opencloud/pull/1072)]
- build(deps): bump github.com/jellydator/ttlcache/v3 from 3.3.0 to 3.4.0 [[#1071](https://github.com/opencloud-eu/opencloud/pull/1071)]
- build(deps): bump github.com/urfave/cli/v2 from 2.27.6 to 2.27.7 [[#1061](https://github.com/opencloud-eu/opencloud/pull/1061)]
- build(deps): bump github.com/KimMachineGun/automemlimit from 0.7.2 to 0.7.3 [[#1062](https://github.com/opencloud-eu/opencloud/pull/1062)]
- Bump reva to pull in the latest fixes [[#1063](https://github.com/opencloud-eu/opencloud/pull/1063)]
- build(deps): bump go.etcd.io/bbolt from 1.4.0 to 1.4.1 [[#1045](https://github.com/opencloud-eu/opencloud/pull/1045)]
- build(deps): bump google.golang.org/grpc from 1.72.2 to 1.73.0 [[#1034](https://github.com/opencloud-eu/opencloud/pull/1034)]
- build(deps): bump golang.org/x/net from 0.40.0 to 0.41.0 [[#1033](https://github.com/opencloud-eu/opencloud/pull/1033)]
- build(deps-dev): bump jest from 29.7.0 to 30.0.0 in /services/idp [[#1040](https://github.com/opencloud-eu/opencloud/pull/1040)]
- build(deps-dev): bump css-minimizer-webpack-plugin from 7.0.0 to 7.0.2 in /services/idp [[#1038](https://github.com/opencloud-eu/opencloud/pull/1038)]
- build(deps): bump query-string from 9.1.1 to 9.2.0 in /services/idp [[#1031](https://github.com/opencloud-eu/opencloud/pull/1031)]
- build(deps): bump i18next from 25.1.2 to 25.2.1 in /services/idp [[#1024](https://github.com/opencloud-eu/opencloud/pull/1024)]
- build(deps): bump golang.org/x/image from 0.27.0 to 0.28.0 [[#1012](https://github.com/opencloud-eu/opencloud/pull/1012)]
- build(deps): bump @types/node from 22.15.29 to 22.15.30 in /services/idp [[#1008](https://github.com/opencloud-eu/opencloud/pull/1008)]
- build(deps): bump github.com/open-policy-agent/opa from 1.5.0 to 1.5.1 [[#1000](https://github.com/opencloud-eu/opencloud/pull/1000)]
- build(deps): bump golang.org/x/sync from 0.14.0 to 0.15.0 [[#1006](https://github.com/opencloud-eu/opencloud/pull/1006)]
- build(deps-dev): bump eslint-plugin-react from 7.37.2 to 7.37.5 in /services/idp [[#1004](https://github.com/opencloud-eu/opencloud/pull/1004)]
- build(deps-dev): bump postcss-normalize from 13.0.0 to 13.0.1 in /services/idp [[#1003](https://github.com/opencloud-eu/opencloud/pull/1003)]
- build(deps): bump @testing-library/react from 11.2.7 to 12.1.5 in /services/idp [[#994](https://github.com/opencloud-eu/opencloud/pull/994)]
- build(deps): bump github.com/blevesearch/bleve/v2 from 2.5.1 to 2.5.2 [[#999](https://github.com/opencloud-eu/opencloud/pull/999)]
- build(deps): bump @fontsource/roboto from 5.1.0 to 5.2.5 in /services/idp [[#995](https://github.com/opencloud-eu/opencloud/pull/995)]
- build(deps): bump google.golang.org/grpc from 1.72.1 to 1.72.2 [[#991](https://github.com/opencloud-eu/opencloud/pull/991)]
- build(deps): bump github.com/nats-io/nats.go from 1.42.0 to 1.43.0 [[#990](https://github.com/opencloud-eu/opencloud/pull/990)]
- build(deps): bump @types/jest from 29.5.12 to 29.5.14 in /services/idp [[#987](https://github.com/opencloud-eu/opencloud/pull/987)]
- build(deps): bump github.com/leonelquinteros/gotext from 1.7.1 to 1.7.2 [[#981](https://github.com/opencloud-eu/opencloud/pull/981)]
- build(deps): bump @types/node from 22.15.19 to 22.15.29 in /services/idp [[#980](https://github.com/opencloud-eu/opencloud/pull/980)]
- build(deps): bump github.com/opencloud-eu/libre-graph-api-go from 1.0.6 to 1.0.7 [[#982](https://github.com/opencloud-eu/opencloud/pull/982)]
- build(deps-dev): bump sass-loader from 16.0.4 to 16.0.5 in /services/idp [[#979](https://github.com/opencloud-eu/opencloud/pull/979)]
- build(deps): bump web-vitals from 4.2.4 to 5.0.2 in /services/idp [[#978](https://github.com/opencloud-eu/opencloud/pull/978)]
- build(deps): bump github.com/open-policy-agent/opa from 1.4.2 to 1.5.0 [[#977](https://github.com/opencloud-eu/opencloud/pull/977)]
- build(deps-dev): bump cldr from 7.5.0 to 7.9.0 in /services/idp [[#975](https://github.com/opencloud-eu/opencloud/pull/975)]
- build(deps): bump github.com/olekukonko/tablewriter from 1.0.6 to 1.0.7 [[#974](https://github.com/opencloud-eu/opencloud/pull/974)]
- build(deps): bump go.opentelemetry.io/contrib/instrumentation/google.golang.org/grpc/otelgrpc from 0.60.0 to 0.61.0 [[#915](https://github.com/opencloud-eu/opencloud/pull/915)]
- build(deps): bump go.opentelemetry.io/contrib/zpages from 0.60.0 to 0.61.0 [[#938](https://github.com/opencloud-eu/opencloud/pull/938)]
- build(deps): bump @testing-library/user-event from 14.5.2 to 14.6.1 in /services/idp [[#939](https://github.com/opencloud-eu/opencloud/pull/939)]
- build(deps): bump i18next-browser-languagedetector from 7.2.1 to 8.1.0 in /services/idp [[#937](https://github.com/opencloud-eu/opencloud/pull/937)]
- build(deps): bump go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp from 0.60.0 to 0.61.0 [[#923](https://github.com/opencloud-eu/opencloud/pull/923)]
- build(deps): bump github.com/nats-io/nats-server/v2 from 2.11.3 to 2.11.4 [[#914](https://github.com/opencloud-eu/opencloud/pull/914)]
- build(deps): bump go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracegrpc from 1.35.0 to 1.36.0 [[#907](https://github.com/opencloud-eu/opencloud/pull/907)]
- build(deps): bump go.opentelemetry.io/otel/trace from 1.35.0 to 1.36.0 [[#906](https://github.com/opencloud-eu/opencloud/pull/906)]
- build(deps): bump github.com/blevesearch/bleve/v2 from 2.5.0 to 2.5.1 [[#900](https://github.com/opencloud-eu/opencloud/pull/900)]
- build(deps): bump axios from 1.7.7 to 1.8.2 in /services/idp [[#902](https://github.com/opencloud-eu/opencloud/pull/902)]
- build(deps): bump github.com/opencloud-eu/libre-graph-api-go from 1.0.5 to 1.0.6 [[#899](https://github.com/opencloud-eu/opencloud/pull/899)]
- build(deps): bump @types/node from 20.14.11 to 22.15.19 in /services/idp [[#886](https://github.com/opencloud-eu/opencloud/pull/886)]
- build(deps-dev): bump i18next-conv from 14.1.0 to 15.1.1 in /services/idp [[#887](https://github.com/opencloud-eu/opencloud/pull/887)]
- build(deps): bump golang.org/x/net from 0.39.0 to 0.40.0 [[#889](https://github.com/opencloud-eu/opencloud/pull/889)]
- build(deps): bump github.com/olekukonko/tablewriter from 0.0.5 to 1.0.6 [[#888](https://github.com/opencloud-eu/opencloud/pull/888)]
- build(deps): bump google.golang.org/grpc from 1.72.0 to 1.72.1 [[#862](https://github.com/opencloud-eu/opencloud/pull/862)]
- build(deps): bump golang.org/x/net from 0.39.0 to 0.40.0 [[#855](https://github.com/opencloud-eu/opencloud/pull/855)]
- build(deps-dev): bump dotenv-expand from 10.0.0 to 12.0.2 in /services/idp [[#831](https://github.com/opencloud-eu/opencloud/pull/831)]
- build(deps): bump github.com/libregraph/lico from 0.65.2-0.20250428103211-356e98f98457 to 0.66.0 [[#839](https://github.com/opencloud-eu/opencloud/pull/839)]
- build(deps): bump i18next from 23.16.8 to 25.1.2 in /services/idp [[#832](https://github.com/opencloud-eu/opencloud/pull/832)]
- build(deps): bump dario.cat/mergo from 1.0.1 to 1.0.2 [[#829](https://github.com/opencloud-eu/opencloud/pull/829)]
- build(deps): bump golang.org/x/image from 0.26.0 to 0.27.0 [[#817](https://github.com/opencloud-eu/opencloud/pull/817)]
- build(deps): bump github.com/CiscoM31/godata from 1.0.10 to 1.0.11 [[#815](https://github.com/opencloud-eu/opencloud/pull/815)]
- build(deps): bump github.com/KimMachineGun/automemlimit from 0.7.1 to 0.7.2 [[#803](https://github.com/opencloud-eu/opencloud/pull/803)]
- build(deps): bump golang.org/x/crypto from 0.37.0 to 0.38.0 [[#802](https://github.com/opencloud-eu/opencloud/pull/802)]
- build(deps): bump github.com/open-policy-agent/opa from 1.3.0 to 1.4.2 [[#784](https://github.com/opencloud-eu/opencloud/pull/784)]
- build(deps): bump golang.org/x/sync from 0.13.0 to 0.14.0 [[#785](https://github.com/opencloud-eu/opencloud/pull/785)]
- build(deps-dev): bump eslint-plugin-import from 2.30.0 to 2.31.0 in /services/idp [[#777](https://github.com/opencloud-eu/opencloud/pull/777)]
- build(deps): bump github.com/nats-io/nats.go from 1.41.2 to 1.42.0 [[#776](https://github.com/opencloud-eu/opencloud/pull/776)]
- build(deps): bump golang.org/x/oauth2 from 0.29.0 to 0.30.0 [[#775](https://github.com/opencloud-eu/opencloud/pull/775)]
- build(deps): bump i18next-http-backend from 2.5.2 to 3.0.2 in /services/idp [[#774](https://github.com/opencloud-eu/opencloud/pull/774)]
- build(deps): bump github.com/beevik/etree from 1.5.0 to 1.5.1 [[#759](https://github.com/opencloud-eu/opencloud/pull/759)]
- build(deps): bump github.com/nats-io/nats-server/v2 from 2.11.2 to 2.11.3 [[#762](https://github.com/opencloud-eu/opencloud/pull/762)]
- build(deps): bump github.com/nats-io/nats-server/v2 from 2.11.1 to 2.11.2 [[#754](https://github.com/opencloud-eu/opencloud/pull/754)]
- build(deps): bump github.com/gookit/config/v2 from 2.2.5 to 2.2.6 [[#753](https://github.com/opencloud-eu/opencloud/pull/753)]
- build(deps-dev): bump css-loader from 5.2.7 to 7.1.2 in /services/idp [[#740](https://github.com/opencloud-eu/opencloud/pull/740)]
- build(deps): bump react-i18next from 15.1.1 to 15.5.1 in /services/idp [[#741](https://github.com/opencloud-eu/opencloud/pull/741)]
- build(deps): bump github.com/blevesearch/bleve/v2 from 2.4.4 to 2.5.0 [[#743](https://github.com/opencloud-eu/opencloud/pull/743)]
- build(deps): bump github.com/gabriel-vasile/mimetype from 1.4.8 to 1.4.9 [[#744](https://github.com/opencloud-eu/opencloud/pull/744)]
First of all, thank you for taking the time to read this and your interest in contributing to OpenCloud!
First, thank you for taking the time to read this and your interest in contributing to OpenCloud!
The following is a set of guidelines suitable to most of the projects hosted in the [OpenCloud Organization](https://github.com/opencloud-eu). These are mostly guidelines, not rules. Use your best judgement, and feel free to propose changes to this document in a pull request.
The following is a set of guidelines suitable to most of the projects hosted in the [OpenCloud Organization](https://github.com/opencloud-eu).
These are mostly guidelines, not rules.
For simplicity reasons, this document mostly refers to the [opencloud repository](https://www.github.com/opencloud-eu/opencloud), but it should be easily transferable to other (sub)projects.
Use your best judgment and feel free to propose changes to this document in a [pull request](https://github.com/opencloud-eu/opencloud/pulls).
For simplicity reasons, this document mostly refers to the [opencloud repository](https://www.github.com/opencloud-eu/opencloud),
but it should be easily transferable to other (sub)projects.
#### Table Of Contents
[I don't want to read this whole thing, I just have a question](#i-dont-want-to-read-this-whole-thing-i-just-have-a-question)
[What should I know before I get started](#what-should-i-know-before-i-get-started)
[What to know before getting started](#what-to-know-before-getting-started)
* [OpenCloud is hosted on GitHub](#opencloud-is-hosted-on-github)
* [OpenCloud Company, Engineering Partners and Community](#opencloud-company,-engineering-partners-and-community)
* [OpenCloud Company, Engineering Partners and Community](#opencloud-company-engineering-partners-and-community)
* [Licensing and CLA](#licensing-and-cla)
[How Can I Contribute](#how-can-i-contribute)
[How to Contribute](#how-to-contribute)
* [Help spreading the word](#help-spreading-the-word)
@@ -37,35 +42,38 @@ For simplicity reasons, this document mostly refers to the [opencloud repository
For general questions, please refer to [OpenCloud's FAQs](https://opencloud.eu/faq/) or check the [project page](https://github.com/opencloud-eu) for communication channels.
## What should I know before I get started
## What to know before getting started
### OpenCloud is hosted on GitHub
To effectively contribute to OpenCloud, you need a GitHub account. You can get that for free at [GitHub](https://github.com/join). You can find howtos on the internet, for example [here](https://www.wikihow.com/Create-an-Account-on-GitHub).
To effectively contribute to OpenCloud, you need a GitHub account. You can get that for free at [GitHub](https://github.com/join). You can find howtos on the internet, for example, [here](https://www.wikihow.com/Create-an-Account-on-GitHub).
For other ways of contributing, for example with translations, other systems require you to have an account as well, for example [Transifex](https://www.transifex.com).
For other ways of contributing, for example, with translations, other systems require you to have an account as well, for example [Transifex](https://www.transifex.com).
The OpenCloud project follows the strict GitHub workflow of development as briefly [described here](https://guides.github.com/introduction/flow/).
### OpenCloud Company, Engineering Partners and Community
OpenCloud is largely created by developers who are employed by the [OpenCloud company](https://opencloud.eu), which is located in Germany. It is providing support for OpenCloud for customers mainly in the EU. In addition, there are engineering partners who also work full time on OpenCloud related code, for example on the component [REVA](https://github.com/cs3org/reva/).
OpenCloud is largely created by developers who are employed by the [OpenCloud company](https://opencloud.eu), which is located in Germany.
It is providing support for OpenCloud for customers mainly in the EU. In addition, there are engineering partners who also work full-time on OpenCloud related code, for example, on the component [REVA](https://github.com/cs3org/reva/).
Because of that fact, the pace that the development is moving forward is sometimes high for people who are not willing and/or able to spend a comparable amount of time to contribute. Even though this can be a challenge, it should not scare anybody away. Here is our clear commitment that we feel honored by everybody who is interested in our work and improves it, no matter how big the contribution might be.
Because of that fact, the pace that the development is moving forward is sometimes high for people who are not willing and/or able to spend a comparable amount of time to contribute.
Even though this can be a challenge, it should not scare anybody away. Here is our clear commitment that we feel honored by everybody who is interested in our work and improves it, no matter how big the contribution might be.
We as the fulltime devs from either organization are doing our best to listen, review and consider all changes that are brought forward following this guideline and make sense for the project.
We as the full-time devs from either organization are doing our best to listen, review and consider all changes that are brought forward following this guideline and make sense for the project.
### Licensing and CLA
There is *no CLA* required for any of the public code of OpenCloud.
## How Can I Contribute
## How to Contribute
There are many ways to contribute to open source projects, and all are equally valuable and appreciated.
### Help spreading the word
This way to contribute to the project cannot be overestimated: People who talk about their experience with OpenCloud and help others with that are the key to success of the project.
This way to contribute to the project cannot be overestimated:
People who talk about their experience with OpenCloud and help others with that are the key to the success of the project.
There are too many ways of doing that to line them up here, but examples are answering questions in any social media or in the [OpenCloud Matrix channel](https://matrix.to/#/#opencloud:matrix.org), writing blog posts etc. pp.
@@ -73,9 +81,11 @@ There is no formal guideline to this, just do it :-)
### Reporting Bugs
This section guides you through submitting a bug report for OpenCloud. Following these guidelines helps maintainers and the community understand your report :pencil:, reproduce the behavior :computer: :computer:, and find related reports :mag_right:.
This section guides you through submitting a bug report for OpenCloud. Following these guidelines help maintainers and the community understand your report :pencil:,
reproduce the behavior :computer: :computer:, and find related reports :mag_right:.
Before creating bug reports, please check [this list](#before-submitting-a-bug-report) as you might find out that you don't need to create one. When you are creating a bug report, please [include as many details as possible](#how-do-i-submit-a-good-bug-report). Fill out [the required template](https://github.com/opencloud-eu/opencloud/issues/new?Type%3ABug&template=bug_report.md), the information it asks for helps to resolve issues faster.
Before creating bug reports, please check [this list](#before-submitting-a-bug-report) as you might find out that you don't need to create one.
When you are creating a bug report, please [include as many details as possible](#how-to-submit-a-good-bug-report). Fill out [the required template](https://github.com/opencloud-eu/opencloud/issues/new?Type%3ABug&template=bug_report.md), the information it asks for helps to resolve issues faster.
> **Note:** If you find a **Closed** issue that seems like it is the same thing that you're experiencing, open a new issue and include a link to the original issue in the body of your new one. If you have permission to reopen the issue, feel free to do so.
***Make sure you are running a recent version** Usually, developers' interest in old versions of software drops very fast once a new version has been released. So the general requirement is: Use the latest released version or even the current master to reproduce problems that you might encounter. That helps a lot to attract developers attention.
***Determine which [repository](https://github.com/opencloud-eu) the problem should be reported in**.
***Perform a [cursory search](https://github.com/search?q=org%3Aopencloud-eu+type%3Aissue+&type=issues)** with possibly a more granular filter on the repository, to see if the problem has already been reported. If it has **and the issue is still open**, add a comment to the existing issue instead of opening a new one **if you have new information**. Please abstain from adding "+1" comments. Instead use the GitHub reaction emojis to indicate that you are affected by the issue as well.
***Perform a [cursory search](https://github.com/search?q=org%3Aopencloud-eu+type%3Aissue+&type=issues)** with possibly a more granular filter on the repository to see if the problem has already been reported. If it has **and the issue is still open**, add a comment to the existing issue instead of opening a new one **if you have new information**. Please abstain from adding "+1" comments. Instead, use the GitHub reaction emojis to indicate that you are affected by the issue as well.
#### How Do I Submit A (Good) Bug Report
#### How to Submit A (Good) Bug Report
Bugs are tracked as [GitHub issues](https://guides.github.com/features/issues/). After you've determined [which repository](https://github.com/opencloud-eu) your bug is related to, create an issue on that repository and provide the following information by filling in [the template](https://github.com/opencloud-eu/opencloud/issues/new?Type%3ABug&template=bug_report.md).
@@ -103,23 +113,26 @@ Explain the problem and include additional details to help maintainers reproduce
Provide more context by answering these questions:
***Did the problem start happening recently** (e.g. after updating to a new version) or was this always a problem?
* If the problem started happening recently, **can you reproduce the problem in an older version?** What's the most recent version in which the problem doesn't happen? You can find more information about how to set up [test environments](https://docs.opencloud.eu/devel/testing) in the [developer documentation](https://docs.opencloud.eu/devel).
* If the problem started happening recently, **can you reproduce the problem in an older version?** What's the most recent version in which the problem doesn't happen? You can find more information about how to set up [test environments](https://docs.opencloud.eu/devel/testing) in the [developer documentation](https://docs.opencloud.eu/docs/dev/intro).
***Can you reliably reproduce the issue?** If not, provide details about how often the problem happens and under which conditions it normally happens.
Include details about your configuration and environment as asked for in the template.
### Suggesting Enhancements
This section guides you through submitting an enhancement suggestion for OpenCloud, including completely new features and minor improvements to existing functionality. Following these guidelines helps maintainers and the community understand your suggestion :pencil: and find related suggestions :mag_right:.
This section guides you through submitting an enhancement suggestion for OpenCloud, including completely new features and minor improvements to existing functionality.
Following these guidelines help maintainers and the community understand your suggestion :pencil: and find related suggestions :mag_right:.
Before creating enhancement suggestions, please check [this list](#before-submitting-an-enhancement-suggestion) as you might find out that you don't need to create one. When you are creating an enhancement suggestion, please [include as many details as possible](#how-do-i-submit-a-good-enhancement-suggestion). Fill in [the template](https://github.com/opencloud-eu/opencloud/.github/blob/master/.github/ISSUE_TEMPLATE/feature_request.md), including the steps that you imagine you would take if the feature you're requesting existed.
Before creating enhancement suggestions, please check [this list](#before-submitting-an-enhancement-suggestion) as you might find out that you don't need to create one.
When you are creating an enhancement suggestion, please [include as many details as possible](#how-to-submit-a-good-enhancement-suggestion).
Fill in [the template](https://github.com/opencloud-eu/opencloud/issues/new?template=feature_request.md), including the steps that you imagine you would take if the feature you're requesting existed.
#### Before Submitting An Enhancement Suggestion
***Check if there's already an extension or other component which provides that enhancement, even in a different way.**
***Perform a [cursory search](https://github.com/search?q=+is%3Aissue+user%3Aopencloud)** to see if the enhancement has already been suggested. If it has, add a comment to the existing issue instead of opening a new one. Feel free to use the GitHub emojis to indicate that you are in favour of an enhancement request.
***Check if there's already an extension or other component that provides that enhancement, even differently.**
***Perform a [cursory search](https://github.com/search?q=+is%3Aissue+user%3Aopencloud)** to see if the enhancement has already been suggested. If it has, add a comment to the existing issue instead of opening a new one. Feel free to use the GitHub emojis to indicate that you are in favor of an enhancement request.
#### How Do I Submit A (Good) Enhancement Suggestion
#### How to Submit A (Good) Enhancement Suggestion
Enhancement suggestions are tracked as [GitHub issues](https://guides.github.com/features/issues/). After you've determined [which repository](https://github.com/opencloud-eu) your enhancement suggestion is related to, create an issue on that repository and provide the following information:
@@ -137,9 +150,11 @@ Unsure where to begin contributing to OpenCloud? You can start by looking throug
* [Tests needed](https://github.com/opencloud-eu/opencloud/labels/Interaction%3ANeeds-tests) - issues which would benefit from a test.
* [Help wanted issues](https://github.com/opencloud-eu/opencloud/labels/Interaction%3ANeeds-help) - issues which should be a bit more involved.
It is fine to pick one of the list following personal preference. While not perfect, number of comments is a reasonable proxy for impact a given change will have.
It is fine to pick one of the lists following personal preference.
While not perfect, the number of comments is a reasonable proxy for the impact a given change will have.
To find out how to set up OpenCloud for local development please refer to the [Developer Documentation](https://docs.opencloud.eu/devel/getting-started). It contains a lot of information that will come in handy when starting to work on the project.
To find out how to set up OpenCloud for local development, please refer to the [Developer Documentation](https://docs.opencloud.eu/docs/dev/web/getting-started).
It contains a lot of information that will come in handy when starting to work on the project.
### Pull Requests
@@ -148,7 +163,7 @@ All contributions to OpenClouds projects use so-called pull requests following t
Please follow these steps to have your contribution considered by the maintainers:
* Follow all instructions in [the template](https://github.com/opencloud-eu/opencloud/blob/main/.github/pull_request_template.md)
* Follow the [styleguides](#styleguides) where applicable
* Follow the [styleguide](#styleguide) where applicable
* After you submit your pull request, verify that all [status checks](https://help.github.com/articles/about-status-checks/) are passing <details><summary>What if the status checks are failing?</summary>If a status check is failing, and you believe that the failure is unrelated to your change, please leave a comment on the pull request explaining why you believe the failure is unrelated. A maintainer will re-run the status check for you. If we conclude that the failure was a false positive, then we will open an issue to track that problem with our status check suite.</details>
While the prerequisites above must be satisfied prior to having your pull request reviewed, the reviewer(s) may ask you to complete additional design work, tests, or other changes before your pull request can be ultimately accepted.
@@ -161,25 +176,38 @@ You find more guidance in the [Documentation Repo](https://github.com/opencloud-
### Internationalization
Our projects are getting translated into many languages to allow people from all over the world to use OpenCloud in their native language. For translations, OpenCloud uses [Transifex](https://www.transifex.com) as a community based collaboration platform for internationalization.
Our projects are getting translated into many languages to allow people from all over the world to use OpenCloud in their native language.
For translations, OpenCloud uses [Transifex](https://www.transifex.com) as a community-based collaboration platform for internationalization.
For contributions please refer to the [Transifex Resources](https://www.transifex.com/resources/) to learn how to improve OpenClouds translations there.
## Styleguides
## Styleguide
To keep up with a consistent code and tooling landscape, some OpenCloud modules maintain styleguides for contributions. It is mandatory to follow them in contributions.
To keep up with a consistent code and tooling landscape, some OpenCloud modules maintain styleguide for contributions.
It is mandatory to follow them in contributions.
### Git Commit Messages
### Commit Messages
* Use the present tense ("Add feature" not "Added feature")
* Use the imperative mood ("Move cursor to..." not "Moves cursor to...")
* Limit the first line to 72 characters or less
* Reference issues and pull requests liberally after the first line
* When only changing documentation, include `[docs-only]` in the commit title
* Use conventional commit messages, see https://www.conventionalcommits.org/en/v1.0.0/
### Branch Naming
* Use short, descriptive names for your branches. For example, use `fix-login-bug` instead of `bugfix123`.
* Use hyphens to separate words in branch names. For example, use `add-new-feature` instead of `add_new_feature`.
* Avoid using special characters or spaces in branch names.
* Consider including the issue number in the branch name for easy reference. For example, use `issue-45-fix-login-bug` if the branch addresses issue #45.
* Keep branch names concise and to the point, ideally under 30 characters.
* Use lowercase letters to maintain consistency and avoid confusion.
### Golang Styleguide
Use the built-in golang code formatter before submitting the patch. Also, consulting documentation like [Effective Go](https://golang.org/doc/effective_go) or [Practical Go](http://bit.ly/gcsg-2019) helps to improve the code quality.
Use the built-in golang code formatter before submitting the patch.
Also, consulting documentation like [Effective Go](https://golang.org/doc/effective_go) or [Practical Go](http://bit.ly/gcsg-2019) helps to improve the code quality.
## Additional Notes
@@ -187,11 +215,13 @@ Use the built-in golang code formatter before submitting the patch. Also, consul
This section lists the labels we use to help us track and manage issues and pull requests. Most labels are used across all OpenCloud repositories, but some are specific.
[GitHub search](https://help.github.com/articles/searching-issues/) makes it easy to use labels for finding groups of issues or pull requests you're interested in. To help you find issues and pull requests, each label can be used in search links for finding open items with that label in the OpenCloud repositories.
[GitHub search](https://help.github.com/articles/searching-issues/) makes it easy to use labels for finding groups of issues or pull requests you're interested in.
To help you find issues and pull requests, each label can be used in search links for finding open items with that label in the OpenCloud repositories.
The labels are loosely grouped by their purpose, but it's not required that every issue has a label from every group or that an issue can't have more than one label from the same group.
The list here contains all the more general categories of issues which are followed by a colon and a specific value. For example severity 1 looks like `Severity:sev1-critical`.
The list here contains all the more general categories of issues which are followed by a colon and a specific value.
For example, severity 1 looks like `Severity:sev1-critical`.
#### Platform
@@ -211,11 +241,11 @@ Flags to indicate the internal QA status in terms of process and priority. Pleas
#### Severity
Severity for the product, mostly impact on user.
Severity for the product, mostly impacts on the user.
#### Type
The issue type, helps to structure the issues in the agile categories (Epic, Story...) but also organizational ones.
The issue type helps to structure the issues in the agile categories (Epic, Story...) but also organizational ones.
#### Topic
@@ -235,8 +265,8 @@ Another label that indicates the type of the issue.
#### Browser
Important for browserdependent web issues. It specifies the browser that shows the error.
Important for browser-dependent web issues. It specifies the browser that shows the error.
#### Early-Adopter
Tags issues that were reported by one of the OpenCloud early adopters, i.e. customers and users who start using OpenCloud before its general availability.
Tags issues reported by one of the OpenCloud early adopters, i.e. customers and users who start using OpenCloud before its general availability.
> For general information about OpenCloud and how to install please visit [OpenCloud on Github](https://github.com/opencloud-eu/) and [OpenCloud GmbH](https://opencloud.eu).
This the main repository of the OpenCloud server. It contains the golang codebase for the backend services.
This is the main repository of the OpenCloud server.
It contains the golang codebase for the backend services.
## Getting Involved
The OpenCloud server is released under [Apache 2.0](https://github.com/opencloud-eu/opencloud/blob/main/LICENSE). The project is very happy to receive contributions in all forms. Start hacking now 😃
The OpenCloud server is released under [Apache 2.0](https://github.com/opencloud-eu/opencloud/blob/main/LICENSE).
The project is thrilled to receive contributions in all forms.
Start hacking now, there are many ways to get involved such as:
### Build OpenCloud
- Reporting [issues or bugs](https://github.com/opencloud-eu/opencloud/issues)
- Helping others in the [community](https://app.element.io/#/room/#opencloud:matrix.org)
Every contribution is meaningful and appreciated!
Please refer to our [Contribution Guidelines](https://github.com/opencloud-eu/opencloud/blob/main/CONTRIBUTING.md) if you want to get started.
## Build OpenCloud
To build the backend, follow these instructions:
Generate the assets needed by e.g. the web UI and the builtin IDP
Generate the assets needed by e.g., the web UI and the builtin IDP
``` console
make generate
@@ -40,10 +53,6 @@ This creates a server configuration (by default in `$HOME/.opencloud`) and start
For more setup- and installation options consult the [Development Documentation](https://docs.opencloud.eu/).
### Contribute
We very much appreciate contributions from the community. Please refer to our [Contribution Guidelines](https://github.com/opencloud-eu/opencloud/blob/main/CONTRIBUTING.md) on how to get started.
## Technology
Important information for contributors about the technology in use.
@@ -58,4 +67,4 @@ The OpenCloud backend does not use a database. It stores all data in the filesys
## Security
If you find a securityrelated issue, please contact [security@opencloud.eu](mailto:security@opencloud.eu) immediately.
If you find a security-related issue, please contact [security@opencloud.eu](mailto:security@opencloud.eu) immediately.
These docker-compose deployment examples are referenced in the documentation on [docs.opencloud.eu](https://docs.opencloud.eu/opencloud/next/). Therefore, please create an issue on the documentation [issue tracker](https://github.com/opencloud-eu/docs/issues) prior to major changes like moving, renaming or massively changing deployment examples.
Please note: The docker-compose deployment examples that lived in this directory have been moved over to the
document this deployment example in: docs/opencloud/deployment/opencloud_full.md
---
# OpenCloud WOPI Deployment Example
This deployment example is documented in two locations for different audiences:
* In the [Admin Documentation](https://docs.opencloud.eu/opencloud/latest/index.html)\
Providing two variants using detailed configuration step by step guides:\
[Local Production Setup](https://docs.opencloud.eu/opencloud/next/depl-examples/ubuntu-compose/ubuntu-compose-prod.html) and [Deploy OpenCloud on the Hetzner Cloud](https://docs.opencloud.eu/opencloud/next/depl-examples/ubuntu-compose/ubuntu-compose-hetzner.html).\
Note that these examples use LetsEncrypt certificates and are intended for production use.
* In the [Developer Documentation](https://docs.opencloud.eu/opencloud/deployment/opencloud_full/)\
Providing details which are more developer focused. This description can also be used when deviating from the default.\
Note that this examples uses self signed certificates and is intended for testing purposes.
# Start dn with uid (user identifier / login), not cn (Firstname + Surname)
dn: uid=alan,ou=users,dc=opencloud,dc=eu
objectClass: inetOrgPerson
objectClass: organizationalPerson
objectClass: person
objectClass: top
uid: alan
givenName: Alan
sn: Turing
cn: alan
displayName: Alan Turing
description: An English mathematician, computer scientist, logician, cryptanalyst, philosopher and theoretical biologist. He was highly influential in the development of theoretical computer science, providing a formalisation of the concepts of algorithm and computation with the Turing machine.
description: A director of the Software Engineering Division of the MIT Instrumentation Laboratory, which developed on-board flight software for NASA's Apollo program.
description: American computer scientist. He created the C programming language and the Unix operating system and B language with long-time colleague Ken Thompson.
The mechanics are currently to mount a different configuration file depending on the environment, as we support two scenarios that are described in [`services/groupware/DEVELOPER.md`](../../../../../services/groupware/DEVELOPER.md):
* «production» setup, with OpenLDAP and Keycloak containers
* «homelab» setup, with the built-in IDM (LDAP) and IDP that run as part of the `opencloud` container
The Docker Compose setup (in [`stalwart.yml`](../../stalwart.yml)) mounts either [`idmldap.toml`](./idmldap.toml) or [`ldap.toml`](./ldap.toml) depending on how the variable `STALWART_AUTH_DIRECTORY` is set, which is either `idmldap` for the homelab setup, or `ldap` for the production setup.
This is thus all done automatically, but whenever changes are performed to Stalwart configuration files, they must be reflected across those two files, to keep them in sync, as the only entry that should differ is this one:
In a groupware environment, not every user will always use the OpenCloud UI to read their emails, some will resort to other [MUAs (Mail User Agents)](https://en.wikipedia.org/wiki/Email_client) that support a subset of features, use older protocols (IMAP, POP, SMTP, CalDAV, CardDAV) and lesser authentication methods (basic authentication). Those email clients will talk to Stalwart directly, as opposed to the OpenCloud UI which will make use of APIs of the OpenCloud Groupware service, since those protocols are provided by Stalwart and implementing them in OpenCloud would offer very little benefits, but definitely a lot of (almost completely) unnecessary effort.
Those protocols and operations that bypass the OpenCloud UI also need to be authenticated, this in and by Stalwart, and we need to find the best fitting approach that fulfills most or all of the following constraints:
### Single Provisioning
We want to avoid multiple provisioning of users, groups, passwords and other resources as much as possible.
While it is possible to have e.g. OpenCloud's user management also perform [Management API](https://stalw.art/docs/category/management-api/) calls, one still inevitably ends up in situations where users, user passwords, or other resources are not in sync, which becomes complex to debug and fix, and should thus be avoided if possible.
To do so, we should strive to have a single source of truth regarding users, their passwords, and similar resources and attributes such as groups, roles, application passwords, etc...
### Attack Detection
Coordinated attacks such as [denial of service](https://en.wikipedia.org/wiki/Denial-of-service_attack) attempts don't necessarily focus on a single protocol but are commonly multi-pronged, e.g. by brute forcing the [OIDC API](https://www.keycloak.org/docs/latest/authorization_services/index.html#token-endpoint), the OpenCloud Groupware API, IMAP and SMTP, \*DAV protocols, etc...
In order to detect those as well as to quickly react by blacklisting clients that are identified to attempt such attacks, it is useful to have a single authentication service for all the components of the system, all protocols, all clients (e.g. [PowerDNS Weakforced](https://github.com/PowerDNS/weakforced), [Nauthilus](https://nauthilus.org/), ...)
Furthermore, such services typically make use of [DNSBL/RBL services](https://en.wikipedia.org/wiki/Domain_Name_System_blocklist) that allow IP addresses of botnets to be blocked across many services of many providers as a shared defense mechanism.
As a bonus, a centralized authentication component can also provide metrics and observability capabilities across all those protocols.
### Custom Authentication Implementations
Some customers might want custom authentication implementations to integrate with their environment, in which case we would want those to be done once and in the technology stack we're all most familiar with (thus as a service in Go in the OpenCloud framework, and not e.g. a Lua script in Nauthilus, or a Rust plugin in Stalwart, etc...)
## Decision Drivers
TODO
*
## Considered Options
First off, here is a brief explanation of each of the scenarios that we potentially or absolutely need to support, which we will explore for each implementation option:
* MUAs with basic authentication
* these are external mail clients (Thunderbird, Apple Mail, ...) with which users authenticate using legacy protocols (IMAP, POP3, SMTP) and their primary username and password in clear text (encrypted through the mandatory use of TLS)
* MUAs with application password authentication
* these are external mail clients (Thunderbird, Apple Mail, ...) with which users authenticate using legacy protocols (IMAP, POP3, SMTP) and one of the application passwords that they created in the OpenCloud UI, which is a useful security mechanism as it reduces the attack surface when one such password is leaked or discovered
* MUAs with SASL bearer token authentication
* these are more modern external mail clients (Thunderbird) with which users authenticate using legacy protocols (IMAP, POP3, SMTP) but more secure OIDC token based authentication (SASL OAUTHBEARER or SASL XOAUTH2), which closely resembles the OIDC authentication used by the OpenCloud UI towards the OpenCloud backends
* JMAP clients with basic authentication
* modern mail clients (Thunderbird) that speak the JMAP protocol over HTTP and authenticate using their primary username and password in clear text (encrypted through the use of HTTPS)
* JMAP clients with bearer token authentication
* modern mail clients (Thunderbird) that speak the JMAP protocol over HTTP and authenticate using an OIDC token (JWT) obtained from an IDP (typically KeyCloak)
* OpenCloud Groupware with master authentication
* the OpenCloud UI client uses APIs from the OpenCloud Groupware backend (and authenticates using OIDC)
* the OpenCloud Groupware backend, in turn, performs JMAP operations with Stalwart, and authenticates using Stalwart's shared secret master authentication protocol
* OpenCloud Groupware with generated token authentication
* the OpenCloud UI client uses APIs from the OpenCloud Groupware backend (and authenticates using OIDC)
* the OpenCloud Groupware backend, in turn, performs JMAP operations with Stalwart, and authenticates against Stalwart using bearer authentication with JWTs that it generates itself
* in the future, that JWT might also be the JWT that the OpenCloud UI used to authenticate against the OpenCloud Groupware in the first place
### Stalwart with the LDAP Directory
```mermaid
flowchart LR
c(client)
s(Stalwart)
l(LDAP)
c -- IMAP/SMTP --> s
c -- JMAP --> s
s -- LDAP --> l
```
Clients authenticate directly against Stalwart, that is configured to use an LDAP authentication Directory.
An LDAP server (e.g. OpenLDAP) is needed as part of the infrastructure.
OpenCloud also has to make use of the same LDAP server.
* ✅ MUAs with basic authentication
* MUAs authenticate directly against Stalwart
* Stalwart's LDAP Directory plugin supports plain text authentication by looking up the userPassword attribute in the LDAP server
* ❌ MUAs with application password authentication
* MUAs authenticate directly against Stalwart
* Stalwart's LDAP Directory plugin does not support application password as it is hardwired to look up the password in the userPassword attribute in the LDAP server
* even if it did support looking up alternative passwords in LDAP, this would hardly be practical as the application passwords are currently created and stored in OpenCloud, which would need to be modified to store them in LDAP in the first place
* ❌ MUAs with SASL bearer token authentication
* MUAs authenticate directly against Stalwart
* Stalwart's LDAP Directory plugin does not support verifying OIDC tokens
* ✅ JMAP clients with basic authentication
* JMAP clients authenticate directly against Stalwart
* Stalwart's LDAP Directory plugin supports plain text authentication by looking up the userPassword attribute in the LDAP server
* ❌ JMAP clients with bearer token authentication
* JMAP clients authenticate directly against Stalwart
* Stalwart's LDAP Directory plugin does not support verifying OIDC tokens
* ✅ OpenCloud Groupware with master authentication
* the OpenCloud Groupware backend authenticates directly against Stalwart
* Stalwart detects and supports clear text password master authentication regardless of the Directory that is being used, and verifies it against the shared secret password that is configured in the server
* ❌ OpenCloud Groupware with generated token authentication
* the OpenCloud Groupware backend authenticates directly against Stalwart
* Stalwart's LDAP Directory plugin does not support verifying OIDC tokens
### Stalwart with the OIDC Directory
```mermaid
flowchart LR
c(client)
s(Stalwart)
o(IDP)
c -- IMAP/SMTP --> s
c -- JMAP --> s
s -- OIDC HTTP --> o
```
Clients authenticate directly against Stalwart, that is configured to use an OIDC authentication Directory.
An OIDC IDP (server) is needed as part of the infrastructure, e.g. KeyCloak.
Optionally, an LDAP server (e.g. OpenLDAP) might be used as well, and KeyCloak would look up users and their credentials in LDAP.
OpenCloud also has to make use of the same LDAP server, or would need to be modified to be capable of only making use of an OIDC IDP (which would include limitations that are yet to be resolved, e.g. the option of using KeyCloak Admin APIs to retreieve groups, group members, ...)
* ❌ MUAs with basic authentication
* MUAs authenticate directly against Stalwart
* Stalwart's OIDC Directory plugin does not support plain text authentication
* ❌ MUAs with application password authentication
* MUAs authenticate directly against Stalwart
* Stalwart's OIDC Directory plugin does not support application passwords
* ❓ MUAs with SASL bearer token authentication
* MUAs authenticate directly against Stalwart
* Stalwart's OIDC Directory plugin does not currently support external IDPs, but is expected to in future versions
* as of Stalwart 0.12, this would only work if Stalwart itself is used as the IDP when acquiring a token
* ❌ JMAP clients with basic authentication
* JMAP clients authenticate directly against Stalwart
* Stalwart's OIDC Directory plugin does not support plain text authentication
* ❓ JMAP clients with bearer token authentication
* JMAP clients authenticate directly against Stalwart
* Stalwart's OIDC Directory plugin does not currently support external IDPs, but is expected to in future versions
* as of Stalwart 0.12, this would only work if Stalwart itself is used as the IDP when acquiring a token
* ✅ OpenCloud Groupware with master authentication
* the OpenCloud Groupware backend authenticates directly against Stalwart
* Stalwart detects and supports clear text password master authentication regardless of the Directory that is being used, and verifies it against the shared secret password that is configured in the server
* ❓ OpenCloud Groupware with generated token authentication
* the OpenCloud Groupware backend authenticates directly against Stalwart
* Stalwart's OIDC Directory plugin does not currently support external IDPs, but is expected to in future versions
* as of Stalwart 0.12, this would only work if Stalwart itself is used as the IDP when acquiring a token, which is not the case with this approach as the tokens are generated by the Groupware backend itself
### Stalwart with the Internal Directory
```mermaid
flowchart LR
c(client)
s(Stalwart)
c -- IMAP/SMTP --> s
c -- JMAP --> s
```
Clients authenticate directly against Stalwart, that is configured to use an Internal authentication Directory.
Neither an OIDC IDP nor an LDAP server are needed as part of the infrastructure, as principal resources (users, groups) and their credentials exist in Stalwart's storage.
OpenCloud would not be capable of accessing those resources, which means that provisioning of groups, users, user passwords must be duplicated and kept in sync between Stalwart and OpenCloud.
* ✅ MUAs with basic authentication
* MUAs authenticate directly against Stalwart
* Stalwart's Internal Directory plugin supports plain text authentication
* users are able to create those themselves using the self-service web UI of Stalwart
* they are not shared with the OpenCloud application passwords though and would need to be provisioned into Stalwart when created in OpenCloud to provide a single UI
* ❌ MUAs with SASL bearer token authentication
* MUAs authenticate directly against Stalwart
* Stalwart's Internal Directory plugin does not support OIDC token authentication
* ✅ JMAP clients with basic authentication
* JMAP clients authenticate directly against Stalwart
* Stalwart's Internal Directory plugin supports plain text authentication
* ❌ JMAP clients with bearer token authentication
* JMAP clients authenticate directly against Stalwart
* Stalwart's Internal Directory plugin does not support OIDC token authentication
* ✅ OpenCloud Groupware with master authentication
* the OpenCloud Groupware backend authenticates directly against Stalwart
* Stalwart detects and supports clear text password master authentication regardless of the Directory that is being used, and verifies it against the shared secret password that is configured in the server
* ❌ OpenCloud Groupware with generated token authentication
* the OpenCloud Groupware backend authenticates directly against Stalwart
* Stalwart's Internal Directory plugin does not support OIDC token authentication
### Stalwart with the OpenCloud Authentication API
```mermaid
flowchart LR
c(client)
s(Stalwart)
o(OpenCloud)
l(LDAP)
c -- IMAP/SMTP --> s
c -- JMAP --> s
s -- REST --> o
o -- LDAP --> l
```
Clients authenticate directly against Stalwart, that is configured to use an "External" authentication Directory, that is yet to be developed. (warning)
Its protocol is currently not defined, but not particularly relevant at this time, as long as it supports accepting basic and bearer authentication in order to authenticate both username and password credentials as well as OIDC tokens.
That External Directory implementation forwards the basic or bearer credentials to an endpoint in the OpenCloud backend, that the responds with whether the authentication is successful or not, as well as with additional information that is needed for Stalwart (email address, display name, groups, roles, ...)
* ✅ MUAs with basic authentication
* MUAs authenticate directly against Stalwart
* Stalwart's External Directory supports plain text authentication by relaying the authentication operation to the OpenCloud backend, which can then authenticate users by username and password using an LDAP server
* note that this option requires having an LDAP server in the environment, including having it accessible by OpenCloud
* if that is not the case, then a viable option is also to support OIDC tokens and application passwords
* to clarify: this scenario is only about supporting authentication using the "primary" username and password
* ✅ MUAs with application password authentication
* MUAs authenticate directly against Stalwart
* Stalwart's External Directory supports application password authentication by relaying the authentication operation to the OpenCloud backend, which can then authenticate against its list of application passwords
* this is the ideal scenario for application passwords, since they are already supported by OpenCloud, and can be created and managed using the OpenCloud UI
* relaying the authentication operation to OpenCloud also prevents the need for duplicate provisioning of application passwords
* ✅ MUAs with SASL bearer token authentication
* MUAs authenticate directly against Stalwart
* Stalwart's External Directory supports OIDC token authentication by relaying the authentication operation to the OpenCloud backend, which can then either perform local token inspection and authentication by verifying the token's signature, or use the OIDC IDP's token introspection endpoint
* ✅ JMAP clients with basic authentication
* JMAP clients authenticate directly against Stalwart
* Stalwart's External Directory supports plain text authentication by relaying the authentication operation to the OpenCloud backend, which can then authenticate users by username and password using an LDAP server
* the same limitations/requirements as for the "MUAs with basic authentication" scenario apply here as well
* ✅ JMAP clients with bearer token authentication
* MUAs authenticate directly against Stalwart
* Stalwart's External Directory supports OIDC token authentication by relaying the authentication operation to the OpenCloud backend, which can then either perform local token inspection and authentication by verifying the token's signature, or use the OIDC IDP's token introspection endpoint
* ✅ OpenCloud Groupware with master authentication
* the OpenCloud Groupware backend authenticates directly against Stalwart
* Stalwart detects and supports clear text password master authentication regardless of the Directory that is being used, and verifies it against the shared secret password that is configured in the server
* ✅ OpenCloud Groupware with generated token authentication
* the OpenCloud Groupware backend authenticates directly against Stalwart
* in the worst case, the External Directory plugin in Stalwart would also perform a forwarding of the authentication operation to OpenCloud, which would obviously be able to verify a token it has created
* an optimization might be possible here, if the External Directory implementation permits for the configuration of specific issuers which should then be verifying against a JWK set directly, whereas the fallback behaviour would be to query the OpenCloud Authentication API
### Stalwart with Nauthilus and LDAP
```mermaid
flowchart LR
c(client)
s(Stalwart)
n(Nauthilus)
l(LDAP)
c -- IMAP/SMTP --> s
c -- JMAP --> s
s -- REST --> n
n -- LDAP --> l
```
In this scenario, we introduce the [Nauthilus authentication service](https://nauthilus.org/), which has its own API but also a KeyCloak integration plugin.
It supports various backends and can also be scripted for more complex combinations.
⚠️ It would require the implementation of a Stalwart Nauthilus Directory, **that is yet to be developed**.
We do not make use of any OpenCloud Authentication API but, instead, attempt to have everything go through Nauthilus instead, backed by an LDAP server that then contains the users, groups, and user passwords.
The upside of using Nauthilus is that it does brute force attack detection and can provide metrics across multiple protocols and clients in a centralized fashion.
* ✅ MUAs with basic authentication
* MUAs authenticate directly against Stalwart
* Stalwart's Nauthilus Directory supports plain text authentication by relaying the authentication operation to Nauthilus, e.g. using its JSON API
* Nauthilus provides a response that contains user attributes from LDAP (display name, email addresses, ...)
* ❓ MUAs with application password authentication
* Nauthilus has no support for application passwords in itself
* a Lua plugin could potentially be used in Nauthilus to detect whether the clear text password matches a regular expression for application passwords and, if that is the case, first attempt to verify it through an API call (that does not exist yet) to the OpenCloud backend, but that would definitely be more complex and less elegant than having a single API
* ❓ MUAs with SASL bearer token authentication
* it is currently unclear whether Nauthilus supports OIDC token authentication
* ✅ JMAP clients with basic authentication
* Stalwart's Nauthilus Directory supports plain text authentication by relaying the authentication operation to Nauthilus, e.g. using its JSON API
* Nauthilus provides a response that contains user attributes from LDAP (display name, email addresses, ...)
* ❓ JMAP clients with bearer token authentication
* it is currently unclear whether Nauthilus supports OIDC token authentication
* ✅ OpenCloud Groupware with master authentication
* the OpenCloud Groupware backend authenticates directly against Stalwart
* Stalwart detects and supports clear text password master authentication regardless of the Directory that is being used, and verifies it against the shared secret password that is configured in the server
* ❓ OpenCloud Groupware with generated token authentication
* the OpenCloud Groupware backend authenticates directly against Stalwart
* it is currently unclear whether Nauthilus supports OIDC token authentication
* an optimization might be possible here, if the Nauthilus Directory implementation permits for the configuration of specific issuers which should then be verifying against a JWK set directly, whereas the fallback behaviour would be to query the Nauthilus API, but that does sound like a stretch to fit into the concept
### Stalwart with Nauthilus and an OpenCloud Authentication API
```mermaid
flowchart LR
c(client)
j(client)
s(Stalwart)
n(Nauthilus)
o(OpenCloud)
l(LDAP)
k(Keycloak)
c -- IMAP/SMTP --> s
j -- JMAP --> s
s -- REST --> n
subgraph internal auth
n -- REST --> o
o -- LDAP --> l
o -- OIDC --> k
end
```
This option also makes use of the [Nauthilus authentication service](https://nauthilus.org/), but instead of it using LDAP to resolve users, we would either make use of its Lua scripting abilities to implement a backend that performs HTTP calls to an OpenCloud Authentication API, or implement an additional Nauthilus backend that uses the Nauthilus API to delegate to another instance, which would then be the OpenCloud Authentication API with support for the Nauthilus API.
⚠️ As with the previous option, it would require the implementation of a Stalwart Nauthilus Directory, **that is yet to be developed**.
Interestingly, if the OpenCloud Authentication API follows the Nauthilus API, this scenario can easily be degraded by dropping Nauthilus and, instead, having all services talk to the OpenCloud Authentication API directly.
* ✅ MUAs with basic authentication
* MUAs authenticate directly against Stalwart
* Stalwart's Nauthilus Directory supports plain text authentication by relaying the authentication operation to Nauthilus, e.g. using its JSON API
* Nauthilus provides a response that contains user attributes from LDAP (display name, email addresses, ...)
* ✅ MUAs with application password authentication
* Nauthilus would forward the authentication request to the OpenCloud Authentication API, which would support application passwords
* ❓ MUAs with SASL bearer token authentication
* it is currently unclear whether Nauthilus supports OIDC token authentication and whether it would be able to forward such requests to the OpenCloud Authentication API
* ✅ JMAP clients with basic authentication
* Stalwart's Nauthilus Directory supports plain text authentication by relaying the authentication operation to Nauthilus, e.g. using its JSON API
* Nauthilus then forwards that request to the OpenCloud Authentication API
* the OpenCloud Authentication API, and then Nauthilus, provides a response that contains user attributes from LDAP (display name, email addresses, ...) or claims from the JWT
* ❓ JMAP clients with bearer token authentication
* it is currently unclear whether Nauthilus supports OIDC token authentication and whether it would be able to forward such requests to the OpenCloud Authentication API
* ✅ OpenCloud Groupware with master authentication
* the OpenCloud Groupware backend authenticates directly against Stalwart
* Stalwart detects and supports clear text password master authentication regardless of the Directory that is being used, and verifies it against the shared secret password that is configured in the server
* ❓ OpenCloud Groupware with generated token authentication
* the OpenCloud Groupware backend authenticates directly against Stalwart
* it is currently unclear whether Nauthilus supports OIDC token authentication and whether it would be able to forward such requests to the OpenCloud Authentication API
> [!IMPORTANT]
> We need to clarify whether the Nauthilus API allows for a JWT to be submitted for the authentication request, and not only username and password – not to secure the request in itself, but to forward an OIDC token based authentication attempt as part of the payload.
### Comparing Options
| | MUA basic | MUA app password | MUA sasl | JMAP clients with basic auth | JMAP clients with JWT auth | Groupware Middleware with master auth | Groupware Middleware with JWT auth |
| --- | --- | --- | --- | --- | --- | --- | --- |
| Stalwart 0.12 with LDAP Directory | ✅ MUA → Stalwart | ❌ not supported with LDAP | ❌ not supported with LDAP | ✅ | ❌ | ✅ | ❌ |
| Stalwart 0.12 with Internal Directory | ✅ MUA → Stalwart, must be provisioned in Stalwart | ✅ MUA → Stalwart, must be provisioned in Stalwart | ❌ | ❌ | ❌ unless using Stalwart as IDP | ✅ | ❌ |
With the current multi-tenancy implementation, the user-management is mostly external
to the OpenCloud instance. Up to [now](../0001-simple-multi-tenancy-using-a-single-opencloud-instance.md)
we relied on some external LDAP server providing the users including their tenant assignment.
We'd like multi-tenancy to also work in environments where no such LDAP server is available.
## Decision Drivers
* Multi-tenancy must work without some existing external (as in not managed by us) LDAP server
* keep the implementation effort low
* allow integration with existing (de)provisioning systems
## Considered Options
### Use the auto-provisioning feature of OpenCloud
We already have basic auto-provsioning features implemented in OpenCloud.
Currently this is not tenant-aware, but it could be extended to support that.
This would require some changes in the way that the users are managed by the
auto-proviosioning code.
The auto-provisioning code does currently use the "normal" graph API to create
users. That API is not tenant-aware and would need to be significantly changed
to support multi-tenancy. However currently there is no real need to put
tenant-awareness into that API (and it would drive us even further a away from
compatibility with the MS Graph API). We could also switch away from the Graph API
for auto-provisioning and use some direct calls to the underlying LDAP server.
Also, using the auto-provisioning feature means that users are only created
when they first login. This means it is not possible to share files with users that
have not yet logged in. This is a significant limitation.
Also we don't currently have any de-provisioning features implemented.
### Use the existing Eudcation API of the Graph Service
We already implemented the Graph Education API in OpenCloud (based on the MS Graph Education API).
This, apart from the somewhat different naming, does already bring most of what is needed
for provisioning users in a multi-tenant environment.
The customer would just need to hookup their existing (de)provisioning system to call the
Education API to create/delete users and assign them to tenants (schools/classes).
The main drawback of this approach is that the customer needs to create some code to
hookup their existing system to the Education API.
The main advantage is that it would give the customer much more control over the users' lifecycle.
## Decision Outcome
Use the existing Education API of the Graph Service.
* Allows integration with existing (de)provisioning systems
* hopefully keeps the implementation effort low
Note: For now this means that the auto-provisioning feature will not be available for
multi-tenant setups. We might want to revisit this in the future.
### Implementation Steps
* re-vive the existing Education API implementation and run it as a separate service
* (maybe) allow to create tenants with a customer specified ID. The tenant id might also be
part of the user's claims (provided by the customer's identity provider). It would be better
if the tenant ids in our system match the tenant ids in the customer's identity provider.
* For de-provisioning to work we need to implement a way to lookup users by an external ID as
that is only unique identfier the customer's system knows for a user. While the MS Graph API
already provides an `externalId` Attribute we don't currently support that on our APIs.
Some files were not shown because too many files have changed in this diff
Show More
Reference in New Issue
Block a user
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
