diff --git a/antora.yml b/antora.yml index 507186d3..1f8f8939 100644 --- a/antora.yml +++ b/antora.yml @@ -50,7 +50,7 @@ asciidoc: # this is the first part of the name for envvars between major versions that will be added or removed # example for full name: 7.0.0-7.1.0-added.adoc or 7.0.0-7.1.0-removed.adoc # note that the name must be exactly how it is defined in the ocis repo to access the source files! - env_var_delta_name: '7.1.0-7.2.0' + env_var_delta_name: '7.2.0-7.3.0' # set attributes defining path components which will be assembled in the document compose_url: 'https://github.com/owncloud/ocis/tree/' @@ -66,5 +66,9 @@ asciidoc: ocis_services_raw_url: 'https://raw.githubusercontent.com/owncloud/ocis/' ocis_services_final_path: '/services/_includes/' + # only used in deployment/services/env-var-changes.adoc + # static path component, used to assemble the final path + ocis_services_env_var_deltas_path: '/services/general-info/envvars/env-var-deltas/' + # used in depl-examples download-gh-directory-url: https://download-directory.github.io diff --git a/modules/ROOT/pages/deployment/services/env-var-changes.adoc b/modules/ROOT/pages/deployment/services/env-var-changes.adoc index 24012d97..d91c998e 100644 --- a/modules/ROOT/pages/deployment/services/env-var-changes.adoc +++ b/modules/ROOT/pages/deployment/services/env-var-changes.adoc @@ -1,13 +1,14 @@ # Changed Environment Variables in Versions :toc: right -:description: This page contains tables with added and removed environment variables between Infinite Scale version 7.1.0 and 7.2.0. +:description: This page contains tables with added and removed environment variables between Infinite Scale version 7.2.0 and 7.3.0. + +:source_path: {ocis_services_raw_url}{service_url_component}{ocis_services_env_var_deltas_path} -:source_path: {ocis_services_raw_url}{service_url_component}{ocis_services_final_path}adoc/env-var-deltas/ //// -ocis_services_raw_url: https://raw.githubusercontent.com/owncloud/ocis/ -service_url_component: docs || docs-stable-7.2 -ocis_services_final_path: /services/_includes/ -env_var_delta_name: 7.1.0-7.2.0 +ocis_services_raw_url: https://raw.githubusercontent.com/owncloud/ocis/ +service_url_component: docs || docs-stable-7.3 +ocis_services_env_var_deltas_path: /services/general-info/envvars/env-var-deltas/ +env_var_delta_name: 7.2.0-7.3.0 //// == Introduction diff --git a/modules/ROOT/pages/deployment/services/s-list/proxy.adoc b/modules/ROOT/pages/deployment/services/s-list/proxy.adoc index 1b3785c2..74809590 100644 --- a/modules/ROOT/pages/deployment/services/s-list/proxy.adoc +++ b/modules/ROOT/pages/deployment/services/s-list/proxy.adoc @@ -75,7 +75,9 @@ Unless the claim configured via `PROXY_AUTOPROVISION_CLAIM_EMAIL` is the same as Next, the proxy will check if the user is a member of the groups configured in `PROXY_AUTOPROVISION_CLAIM_GROUPS`. It will add the user to the groups listed via the OIDC claim that holds the groups defined in the envvar and removes it from all other groups that he is currently a member of. Groups that do not exist in the external IDP yet will be created. Note: This can be a somewhat costly operation, especially if the user is a member of a large number of groups. If the group memberships of a user are changed in the IDP after the first login, it can take up to 5 minutes until the changes are reflected in Infinite Scale. -==== Claim Updates +==== Claims + +===== Claim Updates OpenID Connect (OIDC) scopes are used by an application during authentication to authorize access to a user's detail, like name, email or picture information. A scope can also contain among other things groups, roles, and permissions data. Each scope returns a set of attributes, which are called claims. The scopes an application requests, depends on which attributes the application needs. Once the user authorizes the requested scopes, the claims are returned in a token. @@ -90,6 +92,21 @@ These issued JWT tokens are immutable and integrity-protected. Which means, any * Infinite Scale does not get aware when a group is being deleted in the IDP, a new claim will not hold any information from the deleted group. Infinite Scale does not track a claim history to compare. ==== +===== Claim Checks and Step-up Authentication + +Infinite Scale provides access control via the OpenID Connect (OIDC) "Authentication Class Reference" (ACR) claim. This can be used to enforce step-up authentication on specific routes. For instance, if a user logs in with basic authentication, they may need a higher level to access a sensitive route. If the user has not authenticated at the required level, access to the route will be denied. + +This is configurable via environment variables, such as: + +``` +OCIS_MFA_ENABLED: true +OCIS_MFA_AUTH_LEVEL_NAME: advanced +``` + +This feature is disabled by default and requires an external Identity Provider (IDP) that supports step-up authentication and the ACR claim. Examples of such IDPs include Keycloak. + +If an authenticated user attempts to access a protected route without two-factor authentication (2FA), the server will respond with a 403 Forbidden error and an `X-OCIS-MFA-Required` header. + ===== Impacts For shares or space memberships based on groups, a renamed or deleted group will impact accessing the resource: @@ -138,6 +155,37 @@ role_assignment: ---- This would assign the role `admin` to users with the value `myAdminRole` in the claim `ocisRoles`. The role `user` to users with the values `myUserRole` in the claim `ocisRoles` and so on. +-- + +* Wildcard or Regex Claim Matching ++ +-- +The `claim_value` supports exact strings and regular expressions to map multiple claim values to a single role. Regexes are matched against the entire claim value (implicit start/end anchors). + +Examples: + +[source,yaml] +---- +role_assignment: + driver: oidc + oidc_role_mapper: + role_claim: ocisRoles + role_mapping: + # exact match + - role_name: user + claim_value: ocisUser + # regex: match any value starting with "ocis-user-" + - role_name: user-light + claim_value: ocis-user-.* + # regex: single alphanumeric suffix + - role_name: guest + claim_value: ocis-guest-[a-zA-Z0-9] +---- + +Note: Regex patterns are treated as full matches. Typically you don't need `^` or `$`. +If a `claim_value` is an invalid regex, it only matches claim values that are exactly equal; otherwise it's ignored. +Ordering still applies, and the first matching mapping wins. +-- Claim values that are not mapped to a specific Infinite Scale role will be ignored. @@ -161,7 +209,6 @@ The default `role_claim` (or `PROXY_ROLE_ASSIGNMENT_OIDC_CLAIM`) is `roles`. The - role_name: guest claim_value: ocisGuest ---- --- === Space Management Through OIDC Claims diff --git a/modules/ROOT/pages/deployment/services/s-list/storage-users.adoc b/modules/ROOT/pages/deployment/services/s-list/storage-users.adoc index 61319b33..351bed82 100644 --- a/modules/ROOT/pages/deployment/services/s-list/storage-users.adoc +++ b/modules/ROOT/pages/deployment/services/s-list/storage-users.adoc @@ -206,7 +206,7 @@ ocis storage-users uploads sessions \ ==== Remove Stale Uploads -Unlike the xref:sessions-command[Sessions Command] set above, this command deletes all nodes that are in processing state and not referenced by an upload session. Although this is a very rare occurrence, a command has been added to identify and remove these stale uploads, if they exist. +Unlike the xref:sessions-command[Sessions Command] set above, this command deletes (or reverts) all nodes that are in processing state and not referenced by an upload session. Although this is a very rare occurrence, a command has been added to identify and remove these stale uploads, if they exist. This command can be used to run on a specific Space, on all Spaces, and with a dry-run option to print only stale uploads as they are found. @@ -220,7 +220,7 @@ ocis storage-users uploads delete-stale-nodes help [source,plaintext] ---- NAME: - ocis storage-users uploads delete-stale-nodes - Delete all nodes in processing state that are not referenced by any upload session + ocis storage-users uploads delete-stale-nodes - Delete (or revert) all nodes in processing state that are not referenced by any upload session USAGE: ocis storage-users uploads delete-stale-nodes [command options] diff --git a/modules/ROOT/pages/maintenance/commands/changed-cli.adoc b/modules/ROOT/pages/maintenance/commands/changed-cli.adoc index e9ff8b62..949d6189 100644 --- a/modules/ROOT/pages/maintenance/commands/changed-cli.adoc +++ b/modules/ROOT/pages/maintenance/commands/changed-cli.adoc @@ -1,6 +1,6 @@ = Changed or Added CLI Commands :toc: right -:description: This page contains a list with added, changed or removed CLI commands between Infinite Scale version 7.1.0 and 7.2.0. +:description: This page contains a list with added, changed or removed CLI commands between Infinite Scale version 7.2.0 and 7.3.0. == Introduction @@ -8,7 +8,9 @@ == Affected CLI Commands +// None of the admin-related commands have changed. + See the link for a detailed description of the respective CLI command if available. * xref:maintenance/commands/commands.adoc#manage-expired-or-stale-uploads[Manage Expired or Stale Uploads] + -The `ocis storage-users uploads delete-stale-nodes` command deletes all nodes that are in processing state and not referenced by an upload session. +The `ocis storage-users uploads delete-stale-nodes` command has been updated. Previously, only faulty nodes were deleted, which could cause issues when file versions were present. Now, after deleting faulty nodes, nodes are rolled back to the latest functional version if file versions are present. diff --git a/modules/ROOT/pages/migration/upgrading-ocis.adoc b/modules/ROOT/pages/migration/upgrading-ocis.adoc index 9b67c264..bdb9001a 100644 --- a/modules/ROOT/pages/migration/upgrading-ocis.adoc +++ b/modules/ROOT/pages/migration/upgrading-ocis.adoc @@ -19,6 +19,20 @@ IMPORTANT: When upgrading from an older release to the desired one, *ALL* upgrad IMPORTANT: When upgrading from an older release to the desired one, mandatory configuration settings may have been added or removed. To see the changes required, you can run `ocis init --diff` after upgrading but before finally starting. For more details, see the xref:deployment/general/ocis-init.adoc[ocis init command] description. +== Version 7.2.0 to 7.3.0 + +=== Notable Changes Requiring Manual Intervention + +There are no notable changes requiring manual intervention in Infinite Scale 7.3 + +=== Breaking Changes Requiring Manual Intervention + +There are no breaking changes in Infinite Scale 7.3 + +=== Upgrade Steps + +For a detailed description of the steps to upgrade, see the xref:migration/upgrading_7.2.0_7.3.0.adoc[Upgrading from 7.2.0 to 7.3.0] documentation. Note that this document also contains references to added/changed/removed CLI commands and environment variables. + == Version 7.1.0 to 7.2.0 === Notable Changes Requiring Manual Intervention diff --git a/modules/ROOT/pages/migration/upgrading_7.2.0_7.3.0.adoc b/modules/ROOT/pages/migration/upgrading_7.2.0_7.3.0.adoc new file mode 100644 index 00000000..7fb8631d --- /dev/null +++ b/modules/ROOT/pages/migration/upgrading_7.2.0_7.3.0.adoc @@ -0,0 +1,107 @@ += Upgrading from 7.2.0 to 7.3.0 +:toc: right +:description: This document describes the necessary steps when upgrading Infinite Scale from release 7.2.0 to 7.3.0. + +:actual_seven_version: 7.3.0 + +include::partial$multi-location/compose-version.adoc[] + +== Introduction + +{description} + +IMPORTANT: Read the important notes in the xref:migration/upgrading-ocis.adoc#introduction[Upgrading Infinite Scale] documentation before you start. + +IMPORTANT: Check below, if you are affected by breaking changes and prepare all steps mentioned before you start the upgrade. + +== Upgrade Steps + +. Download and install Infinite Scale + +*Do not start it after downloading the image*! +. Shut down the Infinite Scale instance +. We strongly recommend doing a backup +. Reconfigure the deployment +. Manage Breaking Changes +. Manage Added/Removed/Deprecated environment variables +. Start Infinite Scale + +:sectnums: + +== Download and Install Infinite Scale + +Download and install Infinite Scale: + +* Issue the following command to download the new image: ++ +[source,bash,subs="attributes+"] +---- +docker pull owncloud/ocis:{actual_seven_version} +---- + +== Shut Down the Infinite Scale Instance + +Depending how you deployed Infinite Scale, you need to shut it down differently. + +* *docker compose* + +For deployments using `docker compose` do a graceful shutdown as described in xref:depl-examples/ubuntu-compose/ubuntu-compose-prod.adoc#stop-the-deployment[Stop the Deployment]. + +* *Any other image based deployment* + +For any other image based deployment, shut down Infinite Scale according the vendors deployment description. + +== Backup of Infinite Scale + +See the xref:maintenance/b-r/backup_considerations.adoc[Backup Considerations] and the xref:maintenance/b-r/backup.adoc[Backup] documentation for more details. + +== Reconfigure the Deployment + +Reconfigure the deployment to use the new image: + +* For binary, nothing extra needs to be done + +* When using `docker compose` +** Update _every_ compose file where the `ocis image` is referenced accordingly. +** If you have used the deployment examples either for xref:depl-examples/ubuntu-compose/ubuntu-compose-prod.adoc[Local Production Setup] or xref:depl-examples/ubuntu-compose/ubuntu-compose-hetzner.adoc[Deployment on Hetzner], read the *Updating and Upgrading* section of those pages carefully. + +== Manage Breaking Changes + +* There are no breaking changes in Infinite Scale 7.3 + +== Added-Removed-Deprecated Environment Variables + +* See the xref:deployment/services/env-var-changes.adoc[Changed Environment Variables in Versions] for more details. + +== Reconfigure Deployment Examples + +The following steps are based on the xref:depl-examples/ubuntu-compose/ubuntu-compose-prod.adoc[Local Production Setup] deployment example. The steps are identical for the xref:depl-examples/ubuntu-compose/ubuntu-compose-hetzner.adoc[Deployment on Hetzner]. + +* Stop the deployment example + +* Backup the the base folder containing the existing deployment example by renaming it. + +You will need your configuration details with the new example. + +* Follow the xref:depl-examples/ubuntu-compose/ubuntu-compose-prod.adoc#download-and-transfer-the-example[Download and Transfer Example] to get the new deployment and extract it as described in the following section of the guide. + +* Reconfigure the new `.env` file based on settings made in the `.env` file of the backup. + +Note that new environment variables have been added: +** Configurable image versions for: `Traefik`, `Collabora` and `OnlyOffice`. + +The provided versions are tested, update on your onw risk, note that this especially applies when using `latest`. If a new deployment example is proveded, you now have to update the image versions manually. + +** Pull the new image versions with `docker compose pull`. + +* Start the deployment example. + +== Start Infinite Scale + +When you have finished upgrading, you now can start Infinite Scale as usual. + +For any deployment used, you now can delete/remove old binaries or images/containers. + +:sectnums!: + +== Changed or Added CLI Commands + +See the xref:maintenance/commands/changed-cli.adoc[Changed or Added CLI Commands] document for details. + +== Changed Environment Variables + +See the xref:deployment/services/env-var-changes.adoc[Changed Environment Variables in Versions] document for details.