website/integrations: owncloud: document

website/integrations/services/owncloud/index.md

@@ -0,0 +1,223 @@
+---
+title: Integrate with ownCloud
+sidebar_label: ownCloud
+---
+
+<span class="badge badge--secondary">Support level: Community</span>
+
+## What is ownCloud
+
+> ownCloud is a free and open-source software project for content collaboration and sharing and syncing of files.
+>
+> -- https://owncloud.com
+
+:::note
+This guide focuses on ownCloud installations that are deployed using Docker. If you have deployed it using a different mechanism, there may be some differences in the process.
+:::
+
+## Preparation
+
+The following placeholders are used in this guide:
+
+- `owncloud.company` is the FQDN of the ownCloud install.
+- `authentik.company` is the FQDN of the authentik install.
+
+## Authentication
+
+There are ownCloud plugins available that support various authentication methods, including:
+
+- [SAML/SSO](https://doc.owncloud.com/server/latest/admin_manual/enterprise/user_management/user_auth_shibboleth.html)
+- [OAuth2](https://doc.owncloud.com/server/latest/admin_manual/configuration/user/user_oauth2.html)
+- [OpenID Connect](https://doc.owncloud.com/server/latest/admin_manual/configuration/user/oidc/oidc.html)
+
+This guide will focus on OpenID Connect (OIDC).
+
+### OpenID Connect (OIDC)
+
+OIDC is supported in ownCloud through the use of the official [OIDC plugin](https://github.com/owncloud/openidconnect).
+
+## authentik configuration
+
+Ensure that you have a Signing Key available in authentik for use with these providers. Create one if necessary under **System > Certificates**.
+
+Multiple provider/application pairs are required to support all ownCloud applications, one for each of the: Web UI, Desktop application, Android application and iOS application.
+The configuration for each one is nearly identical, except that the Client ID and Client Secret are
+[pre-defined](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.
+You are free to use the autogenerated Client ID and Secret for the Web UI (or any other appropriate ID/Secret pair).
+
+Create an application and a provider with the following settings for each of the ownCloud applications you wish to support:
+
+### Create a provider
+
+In the authentik Admin Interface, go to **Applications -> Providers**. Create an **OAuth2/OpenID Provider** with the following parameters.
+Parameters not listed here should be left as the default values, or can be customized per your preferences.
+
+The following settings are common for the Web UI, and Desktop/Android/iOS applications:
+
+- General Settings:
+    - Name: owncloud (or owncloud-desktop, owncloud-android, etc.)
+- Protocol Settings:
+    - Signing Key: select the signing key you wish to use
+- Advanced Protocol Settings:
+    - Scopes: email, offline_access, openid, profile
+
+The following settings are different for the different ownCloud applications:
+
+- Web UI
+    - Protocol Settings:
+        - Client ID: use generated authentik value (or customize if you wish)
+        - Client Secret: use generated authentik value (or customize if you wish)
+        - Redirect URIs: `https://owncloud.company/apps/openidconnect/redirect`
+- Desktop Application:
+    - Protocol Settings:
+        - Client ID: use the pre-defined values from [ownCloud](https://doc.owncloud.com/server/latest/admin_manual/configuration/user/oidc/oidc.html#client-id)
+        - Client Secret: use the pre-defined values from [ownCloud](https://doc.owncloud.com/server/latest/admin_manual/configuration/user/oidc/oidc.html#client-secret)
+        - Redirect URI:
+            ```
+            http://localhost:\d+
+            http://127.0.0.1:\d+
+            ```
+- Android Application:
+    - Protocol Settings:
+        - Client ID: use the pre-defined values from [ownCloud](https://doc.owncloud.com/server/latest/admin_manual/configuration/user/oidc/oidc.html#client-id)
+        - Client Secret: use the pre-defined values from [ownCloud](https://doc.owncloud.com/server/latest/admin_manual/configuration/user/oidc/oidc.html#client-secret)
+        - Redirect URI: `oc://android.owncloud.com`
+- iOS Application:
+    - Protocol Settings:
+        - Client ID: use the pre-defined values from [ownCloud](https://doc.owncloud.com/server/latest/admin_manual/configuration/user/oidc/oidc.html#client-id)
+        - Client Secret: use the pre-defined values from [ownCloud](https://doc.owncloud.com/server/latest/admin_manual/configuration/user/oidc/oidc.html#client-secret)
+        - Redirect URI: `oc://ios.owncloud.com`
+
+##### Applications
+
+#### ownCloud
+
+In the authentik Admin Interface, go to **Applications -> Applications**, and create a new Application with the following settings for each of the providers defined above:
+
+- Name: owncloud, owncloud-desktop, owncloud-android, or owncloud-ios
+- Slug: same as name
+- Provider: one of the providers you created in the previous section
+- UI Settings:
+    - Launch URL: You can set this to `blank://blank` to prevent the application from being listed on the authentik
+      home page. This may be useful for the desktop, android and ios applications, since you will not be able
+      to navigate directly to those applications.
+      :::note
+      Sometimes this field glitches out when creating the application, you may need to save the application and then
+      edit it to fill this field.
+      :::
+
+##### Service Discovery
+
+In order for the ownCloud Applications to be able to login via OIDC, your reverse proxy will have to be configured to rewrite
+
+`https://owncloud.company/.well-known/openid-configuration`
+
+to
+
+`https://owncloud.company/index.php/apps/openidconnect/config`
+
+The ownCloud [documentation](https://doc.owncloud.com/server/latest/admin_manual/configuration/user/oidc/oidc.html#set-up-service-discovery) includes an example for accomplishing this with Apache.
+
+In Traefik, use the [replacepathregex](https://doc.traefik.io/traefik/middlewares/http/replacepathregex/) middleware to accomplish the same thing.
+When using Traefik in docker-compose as your reverse proxy, add the following labels to your container. See examples in the docs linked above to accomplish this for other Traefik configurations.
+
+```yaml
+labels:
+  ... # other labels for this service/router
+  traefik.http.routers.owncloud.middlewares: owncloud-oidc-rewrite
+  traefik.http.middlewares.owncloud-oidc-rewrite.replacepathregex.regex: ^/\.well-known/openid-configuration
+  traefik.http.middlewares.owncloud-oidc-rewrite.replacepathregex.replacement: /index.php/apps/openidconnect/config
+```
+
+##### ownCloud OIDC Plugin
+
+Navigate to the _Market_ in your ownCloud deployment by going to `https://owncloud.company/apps/market/#/` or by clicking the Hamburger menu in the top left of any page in your ownCloud deployment and then clicking _Market_.
+From the Market, search for and enable the OIDC plugin
+
+The OIDC plugin cannot be configured from the ownCloud UI, it must be done via the either the `config.php` file or by storing the configuration in the ownCloud database.
+Depending on how your ownCloud deployment is set up, the `config.php` file might be exposed in different places.
+The instructions below apply to deployments using Docker. Refer to the setup guide for your chosen deployment method to determine where the file is located within in your installation.
+
+:::note
+This guide will focus on configuration via the `config.php` mechanism.
+
+Details on configuring the OIDC plugin using the ownCloud database are included in the OIDC plugin's [README](https://github.com/owncloud/openidconnect?tab=readme-ov-file#settings-in-database).
+The configuration you end up with will be the same between the two methods, the only difference will be whether they end up in a `php` file or in the database (via an `occ` command).
+:::
+
+Create a file named `oidc.config.php` in the same directory as the existing `config.php` file in your ownCloud installation. ownCloud will treat files named with this pattern as "override" files, and will override matching configuration keys in the `config.php` file.
+
+The specific location of this file will depend on your Docker configuration. The default location within the container is `/mnt/data/config` which, in the [official setup guide](https://doc.owncloud.com/server/next/admin_manual/installation/docker/#docker-compose), is exposed via the `files` volume.
+
+Minimal contents of `oidc.config.php`:
+
+```php
+<?php
+$CONFIG = [
+  'http.cookie.samesite' => 'None',
+  'openid-connect' => [
+    'provider-url' => 'https://authentik.company/application/o/owncloud/', // replace `owncloud` with whatever name you selected for the web ui provider.
+    'client-id' => <client id chosen in authentik provider configuration>,
+    'client-secret' => <client secret chosen in authentik provider configuration>,
+    'loginButtonName' => 'authentik Login', // this is the text that will be shown on the authentik login button. Choose whatever you want.
+    'mode' => 'userid',
+    'search-attribute' => 'preferred_username',
+    ],
+  ],
+];
+```
+
+Enable automatic provisioning of new users by augmenting `openid-connect` key in the above configuration with the following options:
+
+```php
+  'openid-connect' => [
+    ... // configuration keys from above
+    'auto-provision' => [
+      'enabled' => true,
+      'email-claim' => 'email',
+      'display-name-claim' => 'given_name',
+      'update' => [
+        'enabled' => true,
+      ],
+    ],
+  ],
+```
+
+:::note
+The above configuration will result in new ownCloud users having the same username as the authentik user they are created from.
+If you would prefer to use the email address as the ownCloud username, simply remove the `mode` and `search-attributes` from the above configuration.
+
+This doesn't really impact anything, though if you elect to use the email address as the ownCloud username, the mobile apps will show the user's username as `[email protected]@owncloud.company` in the menus, which is kind of strange.
+:::
+
+Some other notable configuration options:
+
+```php
+<?php
+$CONFIG = [
+  'token_auth_enforced' => true,  // desktop/android/ios clients will be forced to login with OIDC,
+                                  // and existing sessions will be disconnected
+  'openid-connect' => [
+    'autoRedirectOnLoginPage' => true,  // automatic redirection to authentik sign-in
+    ],
+  ],
+];
+```
+
+:::warning
+If you enable the `autoRedirectOnLoginPage` configuration and your OIDC setup breaks, you will have no way of logging in.
+If this happens, simply disable this setting and restart ownCloud to re-enable the standard login page.
+:::
+
+:::tip
+The OIDC plugin's [README](https://github.com/owncloud/openidconnect?tab=readme-ov-file#settings-in-database) contains information about other configuration options.
+:::
+
+### Done!
+
+You should now be able to login using OIDC through authentik. If you did not set the `autoRedirectOnLoginPage` option to `true`, when you navigate to `https://owncloud.company` you will be presented with a login page that now includes an "authentik Login" button (or whatever text you chose in the `loginButtonName` field). If you did set it to `true`, when you attempt to access `https://owncloud.company` you will automatically be redirected to the authentik login page.
+
+New connections through any of the ownCloud applications (desktop, android, or ios) will automatically use OIDC for authentication.
+If you wish to force existing sessions to re-authenticate using OIDC, simply set the `token_auth_enforced`
+option to `true` in your `oidc.config.php` file (as mentioned in [OIDC section](#owncloud-oidc-plugin) above).
+Users will then be forced to re-auth in their ownCloud clients.

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",