From 83cf679dc6cdda5370f681948dd4e7b4ec39edfa Mon Sep 17 00:00:00 2001 From: Jan Sandbrink Date: Mon, 24 Mar 2025 08:43:19 +0100 Subject: [PATCH] Apply suggestions from code review Co-authored-by: Maya Berdygylyjova --- .../integrations/nextcloud/README.md | 9 +++++---- .../integrations/nextcloud/oidc-sso/README.md | 14 +++++++------- .../nextcloud/two-way-oauth2/README.md | 10 +++++----- 3 files changed, 17 insertions(+), 16 deletions(-) diff --git a/docs/system-admin-guide/integrations/nextcloud/README.md b/docs/system-admin-guide/integrations/nextcloud/README.md index 9ebb98e0592..d046f37201c 100644 --- a/docs/system-admin-guide/integrations/nextcloud/README.md +++ b/docs/system-admin-guide/integrations/nextcloud/README.md @@ -99,15 +99,15 @@ Next, enter the **Host URL** of your Nextcloud instance. This is simply the addr ![Adding a new storage via OpenProject Administration settings](openproject_system_guide_nextcloud_integration_setup_step_2.png) -After deciding for an authentication method (more details in the next step), click on **Save and continue setup**. Your new storage is now created, but before you can use it, you will need to configure the chosen authentication method. +After deciding on an authentication method (more details in the next step), click on **Save and continue setup**. Your new storage is now created, but before you can use it, you will need to configure the chosen authentication method. ### 3. Configure Authentication method -The next part of the setup will be different depending on the way that you choose authentication between OpenProject and Nextcloud to happen. +The next part of the setup will vary depending on your chosen authentication method between OpenProject and Nextcloud. **Two-way OAuth 2.0 authorization code flow:** This way of authentication works with all deployments of OpenProject and Nextcloud. Requests between the two applications will act with the target application acting as OAuth 2.0 authorization server. For the users this means, that they will usually have to confirm a separate OAuth consent screen for both directions of communication. -**Single-Sign-On through OpenID Connect Identity Provider:** In this authentication mode, users will not have to confirm additional consent screens, providing a better user experience. Requests between OpenProject and Nextcloud are authenticated with access tokens obtained from a common Identity Provider. This works only if users authenticate to OpenProject and Nextcloud through the same OpenID Connect Identity Provider and specific configuration needs to be done at the identity provider. This advanced feature is available to all installations under the Corporate plan. +**Single-Sign-On through OpenID Connect Identity Provider:** This authentication mode improves user experience by eliminating additional consent screens. Requests between OpenProject and Nextcloud are authenticated with access tokens obtained from a common Identity Provider. This requires both applications to use the same OpenID Connect Identity Provider and specific configurations at the provider level. This advanced feature is available for all installations under the Enterprise Corporate plan.``` Instructions for both authentication methods can be found on the following pages: @@ -132,7 +132,8 @@ In case you want to use this functionality you will be requested to enter a pass > [!IMPORTANT] > You will need to install the [Group folder](https://apps.nextcloud.com/apps/groupfolders) app in Nextcloud in order to have OpenProject automatically managed your Nextcloud folders. Each storage can only have one group folder with the same name. -Please note, when you use the **Terms of Service** app on the Nextcloud side, all terms also need to be accepted for the OpenProject user that gets created during the setup. This is set to happen automatically during the initial set-up. If you see an error message indicating otherwise or the integration does not behave as expected, please refer to the [Troubleshooting](#troubleshooting) section at the bottom of this page. +> [!NOTE] +> When you use the **Terms of Service** app on the Nextcloud side, all terms also need to be accepted for the OpenProject user that gets created during the setup. This is set to happen automatically during the initial set-up. If you see an error message indicating otherwise or the integration does not behave as expected, please refer to the [Troubleshooting](#troubleshooting) section at the bottom of this page. At this point, you can click on **Done, complete setup** in both applications and your instance configuration will be completed. diff --git a/docs/system-admin-guide/integrations/nextcloud/oidc-sso/README.md b/docs/system-admin-guide/integrations/nextcloud/oidc-sso/README.md index a8618f29d65..552478bd99a 100644 --- a/docs/system-admin-guide/integrations/nextcloud/oidc-sso/README.md +++ b/docs/system-admin-guide/integrations/nextcloud/oidc-sso/README.md @@ -1,7 +1,7 @@ --- sidebar_navigation: title: Setup Single-Sign-On through OpenID Connect Identity Provider - priority: 600 + priority: 900 description: Set up Single-Sign-On through OpenID Connect Identity Provider as the authentication method for your Nextcloud storage keywords: Nextcloud file storage integration --- @@ -20,7 +20,7 @@ To use SSO authentication between OpenProject and Nextcloud, a few prerequisites 2. The identity provider needs to hand out compatible access tokens 3. The identity provider needs to allow long-term access (e.g. through the `offline_access` scope) -Those requirements are explained in more detail below. +These requirements are explained in more detail below. ### User authentication @@ -32,14 +32,14 @@ Additionally the user account has to be created in both systems already at the t ### Token compatibility -The identity provider will need to hand out JWT encoded access tokens that can be validated according to the rules of [RFC 9068](https://www.rfc-editor.org/rfc/rfc9068). Such tokens indicate at which application they are allowed to be used (the so-called Token _Audience_) and can be validated by an application mostly without performing additional web requests to the identity provider. +The identity provider will need to hand out JWT encoded access tokens that can be validated according to the rules of [RFC 9068](https://www.rfc-editor.org/rfc/rfc9068). Such tokens indicate which application they are allowed to be used in (the so-called Token _Audience_) and can be validated by an application mostly without performing additional web requests to the identity provider. It must be possible for OpenProject to obtain an access token that includes the Nexcloud client in the audience and vice versa, to allow making requests between the two applications. This has to be supported in one of two ways by the identity provider: 1. It allows to perform _OAuth 2.0 Token Exchange_ according to [RFC 8693](https://www.rfc-editor.org/rfc/rfc8693) 2. Alternatively, it provides tokens with the necessary audience during initial SSO authentication of the user -Token exchange is generally the more secure option, since it allows fine-grained control by the identity provider which application can obtain tokens to make requests to other applications. It's usually harder to use leaked access tokens of this kind for privilege escalation. However, depending on the provider, the latter option may be easier to set-up. +Token exchange is generally the more secure option, since it allows stricter control by the identity provider which application can obtain tokens to make requests to other applications. It's usually harder to use leaked access tokens of this kind for privilege escalation. However, depending on the provider, the latter option may be easier to set-up. ### Long-term access @@ -56,18 +56,18 @@ Other identity providers might work as well, but we only have limited capabiliti ### Keycloak -Keycloak can provide tokens via Token Exchange, as well as immediately after signing in the user. Using Token Exchange is preferred, but requires to enable two preview features in the Keycloak deployment: +Keycloak can provide tokens via Token Exchange, as well as immediately after user sign in. Using Token Exchange is preferred, but requires to enable two preview features in the Keycloak deployment: * `token-exchange` * `admin-fine-grained-authz` -If you prefer to not enable preview features on your production deployment, it's also possible to use wide-access tokens. +If you prefer not to enable preview features on your production deployment, it's also possible to use wide-access tokens. #### ... using Token Exchange ##### Configuring Keycloak -First make sure that you enabled both required features in Keycloak: `token-exchange` and `admin-fine-grained-authz`. You can [follow the Keycloak docs on how to do that](https://www.keycloak.org/server/features). Once they are enabled you can confirm them from the "Server Info" tab in your Keycloak installation: +First make sure that you enabled both required features in Keycloak: `token-exchange` and `admin-fine-grained-authz`. You can [follow the Keycloak documentation on how to do that](https://www.keycloak.org/server/features). Once they are enabled you can confirm them from the "Server Info" tab in your Keycloak installation: ![The Keycloak UI that shows enabled features](keycloak_features.png) diff --git a/docs/system-admin-guide/integrations/nextcloud/two-way-oauth2/README.md b/docs/system-admin-guide/integrations/nextcloud/two-way-oauth2/README.md index 76e195e6e0a..eb91916837a 100644 --- a/docs/system-admin-guide/integrations/nextcloud/two-way-oauth2/README.md +++ b/docs/system-admin-guide/integrations/nextcloud/two-way-oauth2/README.md @@ -1,14 +1,14 @@ --- sidebar_navigation: title: Setup Two-way OAuth 2.0 authentication - priority: 600 + priority: 800 description: Set up Two-way OAuth 2.0 authentication as the authentication method for your Nextcloud storage keywords: Nextcloud file storage integration --- # Setup Two-way OAuth 2.0 authentication -This authentication mode will use access tokens provided by an OAuth application of either side of the integration between OpenProject and Nextcloud to authenticate requests performed in the name of users. +This authentication mode will use access tokens provided by an OAuth application on either side of the integration between OpenProject and Nextcloud to authenticate requests performed in the name of users. You will have to perform configuration in OpenProject and in Nextcloud. @@ -33,15 +33,15 @@ Once you have copied the values, click on **Save** to proceed to the next step. ## 2. Enter Nextcloud OAuth values in OpenProject -In the page that appears, you will see new OAuth values that are once again generated automatically, but this time by Nextcloud. +On the page that appears, you will see new OAuth values that are once again generated automatically, but this time by Nextcloud. -OpenProject will need these values to be able to connect to your Nextcloud instance. +OpenProject will need these values to be able to connect with your Nextcloud instance. Much like in the previous step, you will need to copy these two generated values (**Nextcloud OAuth client ID** and **Nextcloud OAuth client secret**) and paste them into OpenProject. ![Nextcloud also generates OAuth values that need to be copied to OpenProject](two_way_oauth2_setup_step_3.png) -Navigate back to your OpenProject tab and click on the **Done, continue** button on the screen you previously left it at. You will now see a screen where you will be able to enter the Nextcloud values. +Navigate back to your OpenProject tab and click the **Done, continue** button on the screen you previously left it at. You will now see a screen where you will be able to enter the Nextcloud values. ![OpenProject_NC_OAuth_values](two_way_oauth2_setup_step_4.png)