diff --git a/website/integrations/services/owncloud/index.md b/website/integrations/services/owncloud/index.md new file mode 100644 index 000000000000..93601ee645e5 --- /dev/null +++ b/website/integrations/services/owncloud/index.md @@ -0,0 +1,209 @@ +--- +title: Integrate with ownCloud +sidebar_label: ownCloud +--- + +Support level: Community + +## What is ownCloud + +> ownCloud is a free and open-source software project for content collaboration and sharing and syncing of files. +> +> -- https://owncloud.com + +## Preparation + +The following placeholders are used in this guide: + +- `owncloud.company` is the FQDN of the ownCloud installation. +- `authentik.company` is the FQDN of the authentik installation. + +:::info +This guide focuses on deploying ownCloud installations using Docker. If you deployed ownCloud using a different mechanism, there might be some differences in the process. Furthermore, these instructions use the [official OIDC plugin](https://github.com/owncloud/openidconnect). Advanced configuration details can be found in the [ownCloud admin manual](https://doc.owncloud.com/server/latest/admin_manual/configuration/user/oidc/oidc.html). +::: + +## authentik configuration + +To support all ownCloud applications, multiple application/provider pairs are required—one each for the Web UI, Desktop application, Android application, and iOS application. + +The configuration for each application is nearly identical, except for the **Client ID**, **Client Secret**, and the **Redirect URI** values, which are [predefined](https://doc.owncloud.com/server/latest/admin_manual/configuration/user/oidc/oidc.html#client-ids-secrets-and-redirect-uris) by ownCloud for the Desktop, Android, and iOS applications. + +### Create applications/providers + +Follow these steps to create the required application/provider pairs. You will need to repeat the process four times: once each for the Desktop application, Web UI, Android application, and iOS application + +1. In the Admin interface, navigate to **Applications** > **Applications**. +2. Use the wizard to create the application and provider, with the following settings: + + - **Application**: Provide a descriptive name (e.g., `owncloud`, `owncloud-desktop`, `owncloud-android`, `owncloud-ios`), an optional group for the type of application, the policy engine mode, and optional UI settings. + - **Choose a Provider type**: Select **OAuth2/OpenID Provider** as the provider type. + - **Configure the Provider**: Provide a name (the default name will suffice for most users), the authorization flow to use for this provider, and the following required configurations. The settings for each of the four application/provider pairs are shown below: + + - **Protocol settings:** + + **Web UI:** + + - **Signing Key**: Select any available signing key. + - **Client ID**: Use the value generated by authentik. + - **Client Secret**: Use the value generated by authentik. + - **Redirect URIs**: + - Strict: `https://owncloud.company/apps/openidconnect/redirect` + + **Desktop Application** + + - **Signing Key**: Select any available signing key. + - **Client ID**: Use the predefined value found in the [ownCloud admin manual](https://doc.owncloud.com/server/latest/admin_manual/configuration/user/oidc/oidc.html#client-id). + - **Client Secret**: Use the predefined value found in the [ownCloud admin manual](https://doc.owncloud.com/server/latest/admin_manual/configuration/user/oidc/oidc.html#client-secret). + - **Redirect URIs**: + - Regex: `http://localhost:\d+` + - Regex: `http://127.0.0.1:\d+` + + **Android Application** + + - **Signing Key**: Select any available signing key. + - **Client ID**: Use the predefined value found in the [ownCloud admin manual](https://doc.owncloud.com/server/latest/admin_manual/configuration/user/oidc/oidc.html#client-id). + - **Client Secret**: Use the predefined value found in the [ownCloud admin manual](https://doc.owncloud.com/server/latest/admin_manual/configuration/user/oidc/oidc.html#client-secret). + - **Redirect URI**: + - Strict: `oc://android.owncloud.com` + + **iOS Application** + + - **Signing Key**: Select any available signing key. + - **Client ID**: Use the predefined value found in the [ownCloud admin manual](https://doc.owncloud.com/server/latest/admin_manual/configuration/user/oidc/oidc.html#client-id). + - **Client Secret**: Use the predefined value found in the [ownCloud admin manual](https://doc.owncloud.com/server/latest/admin_manual/configuration/user/oidc/oidc.html#client-secret). + - **Redirect URI**: + - Strict: `oc://ios.owncloud.com` + + - **Advanced protocol settings:** + - **Scopes**: Select the following scopes for each of the four application/provider pairs: `email`, `offline_access`, `openid`, `profile`. + + - **Configure Bindings** (optional): To manage the listing and access to applications on a user's **My applications** page, you can optionally create a [binding](https://docs.goauthentik.io/docs/add-secure-apps/flows-stages/bindings/) between the application and a specific policy, group, or user. Keep in mind that if you do not specify any bindings, all users will have access to the application. For more information about user access, refer to our documentation about [authorization](https://docs.goauthentik.io/docs/add-secure-apps/applications/manage_apps#policy-driven-authorization) and [hiding an application](https://docs.goauthentik.io/docs/add-secure-apps/applications/manage_apps#hide-applications). + +### Service discovery + +To allow ownCloud applications to log in via OIDC, your reverse proxy must be configured to rewrite `https://owncloud.company/.well-known/openid-configuration` to `https://owncloud.company/index.php/apps/openidconnect/config`. + +Refer to the [ownCloud Admin Manual](https://doc.owncloud.com/server/latest/admin_manual/configuration/user/oidc/oidc.html#set-up-service-discovery) for an example configuration using [Apache HTTPD](https://httpd.apache.org/). + +For other reverse proxies, consult the provider-specific documentation for guidance on implementing this rewrite rule. + +## ownCloud Configuration + +To enable OIDC functionality in ownCloud, follow these steps: + +1. **Navigate to the Market**: + + - Access the Market by visiting: + `https://owncloud.company/apps/market/#/` + or by clicking the **Hamburger Menu** in the top-left corner of any page in your ownCloud deployment and selecting **Market**. + - Search for and enable the **OIDC plugin**. + +2. **OIDC Plugin Configuration**: + The OIDC plugin cannot be configured via the ownCloud UI. Configuration must be performed either: + + - by editing the `config.php` file + OR + - by storing the configuration in the ownCloud database + + The location of the `config.php` file depends on your deployment method. Consult the setup guide for your chosen deployment method to identify the file’s location within your installation. + + :::note + + Instructions for configuring the OIDC plugin using the ownCloud database can be found in the OIDC plugin's [README.md file](https://github.com/owncloud/openidconnect?tab=readme-ov-file#settings-in-database). Both methods produce identical configurations, differing only in whether the settings are stored in a `php` file or in the database (via an `occ` command). + ::: + +3. **Create the `oidc.config.php` File**: + + - Place a file named `oidc.config.php` in the same directory as the existing `config.php` file in your ownCloud installation. + - Files named with this pattern are treated as "override" files, allowing ownCloud to override matching configuration keys in the `config.php` file. + + The location of this file depends on your Docker configuration. By default, the file resides in `/mnt/data/config` within the container. This location is exposed via the `files` volume in the [official setup guide](https://doc.owncloud.com/server/next/admin_manual/installation/docker/#docker-compose). + +4. **Minimal Contents of `oidc.config.php`**: + Add the necessary configuration settings to this file. Ensure it includes at least the minimal requirements for your setup: + + :::warning + You can configure ownCloud to use either the `sub` or `preferred_username` as the UID field under `search-attribute`. When using `preferred_username` as the user identifier, ensure that the [**Allow users to change username** setting](https://docs.goauthentik.io/docs/sys-mgmt/settings#allow-users-to-change-username) is disabled to prevent authentication issues. The `sub` option uses a unique, stable identifier for the user, while `preferred_username` uses the username configured in authentik. + ::: + +```php + 'None', + 'openid-connect' => [ + 'provider-url' => 'https://authentik.company/application/o/owncloud/', + 'client-id' => '', + 'client-secret' => ' 'Log in with authentik', + 'mode' => 'userid', + 'search-attribute' => 'preferred_username', + ], + ], +]; +``` + +To enable automatic provisioning of new users, you can augment the `openid-connect` configuration in your `oidc.config.php` file with the following settings: + +```php + 'None', + 'openid-connect' => [ + 'provider-url' => 'https://authentik.company/application/o/owncloud/', + 'client-id' => '', + 'client-secret' => '', + 'loginButtonName' => 'Log in with authentik', + 'mode' => 'userid', + 'search-attribute' => 'preferred_username', + 'auto-provision' => [ + 'enabled' => true, + 'email-claim' => 'email', + 'display-name-claim' => 'given_name', + 'update' => [ + 'enabled' => true, + ], + ], + ], +]; +``` + +:::note +The configuration above will result in new ownCloud users being assigned the same username as the authentik username. If you prefer to use the user's email address as the ownCloud username, you can remove the `mode` and `search-attribute` settings. + +Note that using email as the username may cause mobile app interfaces to display usernames in an unusual format (e.g., `user@email.com@owncloud.company`). +::: + +In addition to the above settings, here are some additional options for configuring the OIDC integration in ownCloud: + +```php + true, // Forces OIDC authentication on all desktop, Android, and iOS clients, and disconnects existing sessions. + 'openid-connect' => [ + 'autoRedirectOnLoginPage' => true, // Enables automatic redirection to the authentik login page + ], +]; +``` + +:::warning +Enabling the `autoRedirectOnLoginPage` setting may lock you out of the system if your OIDC setup is misconfigured. To regain access, you can disable this setting and restart ownCloud, which will restore the standard login page. +::: + +:::tip +For more information on other available configuration options, refer to the OIDC plugin's [README](https://github.com/owncloud/openidconnect?tab=readme-ov-file#settings-in-database). +::: + +### You're done! + +You have successfully configured OIDC authentication through authentik. Here's what you can expect next: + +- **Login Behavior:** + + - If the `autoRedirectOnLoginPage` option is **set to false**, navigating to `https://owncloud.company` will present the standard login page, which now includes an "Log in with authentik" button (or any custom text defined in the `loginButtonName` field). + - If the `autoRedirectOnLoginPage` option is **set to true**, users will be automatically redirected to the authentik login page when attempting to access `https://owncloud.company`. + +- **ownCloud Applications:** + Any new connections through the ownCloud desktop, Android, or iOS applications will automatically use OIDC for authentication. + +- **Force Re-authentication:** + To enforce re-authentication using OIDC for existing sessions, set the `token_auth_enforced` option to **true** in the `oidc.config.php` file (as detailed in the above section). This will prompt users to re-authenticate on their ownCloud clients. diff --git a/website/sidebarsIntegrations.js b/website/sidebarsIntegrations.js index a9b40c0eeaaa..cd1637da15a1 100644 --- a/website/sidebarsIntegrations.js +++ b/website/sidebarsIntegrations.js @@ -28,6 +28,7 @@ module.exports = { "services/nextcloud/index", "services/onlyoffice/index", "services/outline/index", + "services/owncloud/index", "services/paperless-ng/index", "services/paperless-ngx/index", "services/rocketchat/index",