Integrate with ownCloud - Authentik

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. Advanced configuration details can be found in the ownCloud admin manual. :::

authentik configuration

To support the integration of ownCloud with authentik, you need to create multiple application/provider pairs in authentik. A different pair is required 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 by ownCloud for the Desktop, Android, and iOS applications.

Create an application and provider in authentik

Log in to authentik as an administrator and open the authentik Admin interface.
Navigate to Applications > Applications and click Create with Provider to create an application and provider pair. (Alternatively you can first create a provider separately, then create the application and connect it with the provider.) You will need to repeat the process four times: once each for the Desktop application, Web UI, Android application, and iOS application.

Application: provide a descriptive name, an optional group for the type of application, the policy engine mode, and optional UI settings.
Choose a Provider type: select OAuth2/OpenID Connect as the provider type.
Configure the Provider: provide a name (or accept the auto-provided name), the authorization flow to use for this provider, and the following required configurations.
- Note the Client ID, Client Secret, and slug values because they will be required later.
- 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.
  - Client Secret: Use the predefined value found in the ownCloud admin manual.
  - 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.
  - Client Secret: Use the predefined value found in the ownCloud admin manual.
  - 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.
  - Client Secret: Use the predefined value found in the ownCloud admin manual.
  - 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): you can create a binding (policy, group, or user) to manage the listing and access to applications on a user's My applications page.

Click Submit to save the new application and provider.

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 for an example configuration using Apache HTTPD.

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:

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.
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.

:::info
```
Instructions for configuring the OIDC plugin using the ownCloud database can be found in the OIDC plugin's README.md file. 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). :::
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.
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 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

<?php
$CONFIG = [
  'http.cookie.samesite' => 'None',
  'openid-connect' => [
    'provider-url' => 'https://authentik.company/application/o/owncloud/',
    'client-id' => '<Client ID from authentik>',
    'client-secret' => '<Client secret from authentik>',
    'loginButtonName' => '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

<?php
$CONFIG = [
  'http.cookie.samesite' => 'None',
  'openid-connect' => [
    'provider-url' => 'https://authentik.company/application/o/owncloud/',
    'client-id' => '<Client ID from authentik>',
    'client-secret' => '<Client secret from authentik>',
    '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,
      ],
    ],
  ],
];

:::info 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., [email protected]@owncloud.company). :::

In addition to the above settings, here are some additional options for configuring the OIDC integration in ownCloud:

php

<?php
$CONFIG = [
  'token_auth_enforced' => 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. :::

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.