Skip to main content

Integrate with Nextcloud

Support level: Community

What is Nextcloud​

Nextcloud is a suite of client-server software for creating and using file hosting services. Nextcloud is free and open-source, which means that anyone is allowed to install and operate it on their own private server devices.

-- https://en.wikipedia.org/wiki/Nextcloud

warning

If you require Server Side Encryption, you must use LDAP. OpenID and SAML will cause irrevocable data loss. Nextcloud Server-Side Encryption requires access to the user's cleartext password, which Nextcloud only has access to when using LDAP as the user enters their password directly into Nextcloud.

caution

This setup only works when Nextcloud is running with HTTPS enabled. See here on how to configure this.

info

In case something goes wrong with the configuration, you can use the URL http://nextcloud.company/login?direct=1 to log in using the built-in authentication.

note

This documentation lists only the settings that you need to change from their default values. Be aware that any changes other than those explicitly mentioned in this guide could cause issues accessing your application.

Configuration methods​

It is possible to configure Nextcloud to use either OpenID Connect or SAML for authentication. Below are the steps to configure both methods.

Preparation​

The following placeholders are used in this guide:

  • nextcloud.company is the FQDN of the Nextcloud installation.
  • authentik.company is the FQDN of the authentik installation.

Let's start by considering which user attributes need to be available in Nextcloud:

  • name
  • email
  • unique user ID
  • storage quota (optional)
  • groups (optional)

authentik already provides some default scopes with claims, such as:

  • email scope: includes email and email_verified
  • profile scope: includes name, given_name, preferred_username, nickname, groups
  • openid scope: a default required by the OpenID spec (contains no claims)

Custom Profile Scope​

If you do not need storage quota, group information, or to manage already existing users in Nextcloud, skip to the next step.

If you want to control user storage and designate Nextcloud administrators, create a custom profile scope. Go to Customization > Property mappings and create a Scope mapping with:

  • Name: Nextcloud Profile

  • Scope name: profile

  • Expression:

    # Extract all groups the user is a member of
    groups = [group.name for group in user.ak_groups.all()]

    # Nextcloud admins must be members of a group called "admin".
    # This is static and cannot be changed.
    # Append "admin" to the user's groups if they are an admin in authentik.
    if user.is_superuser and "admin" not in groups:
        groups.append("admin")

    return {
        "name": request.user.name,
        "groups": groups,
        # Set a quota by using the "nextcloud_quota" property in the user's attributes
        "quota": user.group_attributes().get("nextcloud_quota", None),
        # To connect an existing Nextcloud user, set "nextcloud_user_id" to the Nextcloud username.
        "user_id": user.attributes.get("nextcloud_user_id", str(user.uuid)),
    }
note

To set a quota, define the nextcloud_quota attribute for individual users or groups. For example, setting it to 1 GB will restrict the user to 1GB of storage. If not set, storage is unlimited.

note

To connect to an existing Nextcloud user, set the nextcloud_user_id attribute to match the Nextcloud username (found under the user's Display name in Nextcloud).

Provider and Application​

  1. Create a provider:
    In the authentik Admin Interface, navigate to Applications > Providers. Create an OAuth2/OpenID Provider with the following settings:

    • Name: Nextcloud
    • Client type: Confidential
    • Redirect URIs/Origins (RegEx):
      https://nextcloud.company/apps/user_oidc/code
    • Signing key: Any valid certificate

  2. Configure advanced settings:
    Under advanced settings, set:

    • Scopes:

      • authentik default Oauth Mapping email
      • Nextcloud Profile (or authentik default Oauth Mapping profile if you skipped the custom profile scope)

    • Subject mode: Based on the User's UUID

      danger

      Mapping the subject mode to authentik usernames is not recommended due to their mutable nature. If you choose to map to usernames, disable username changing in authentik and set it to Based on the User's username.

    • Include claims in ID token: Enabled

    Note: Save your client ID and secret ID for later.

note

An issue with the Nextcloud OIDC app limited the secret ID size to 64 characters. This has been fixed as of December 2023—ensure you update the OpenID Connect user backend to the latest version.

note

Depending on your Nextcloud configuration, you might need to use https://nextcloud.company/index.php/ instead of https://nextcloud.company/.

  1. Link the provider to an application:
    In Applications > Applications, create an application and select the provider you just created. Note the application slug for later use.

Nextcloud configuration​

  1. Install the app:
    In Nextcloud, ensure the OpenID Connect user backend app is installed. Then navigate to Settings > OpenID Connect.

  2. Add a provider:
    Click the + button and enter the following:

    • Identifier: Authentik

    • Client ID: (from the provider)

    • Client secret: (from the provider)

    • Discovery endpoint:

      https://authentik.company/application/o/<nextcloud-app-slug>/.well-known/openid-configuration

    • Scope: email profile (omit openid if preferred)

    • Attribute mappings:

      • User ID mapping: sub (or user_id for existing users)

      • Display name mapping: name

      • Email mapping: email

      • Quota mapping: quota (leave blank if the custom profile scope was skipped)

      • Groups mapping: groups (leave blank if the custom profile scope was skipped)

        tip

        Enable Use group provisioning to allow writing to this field.

    • Use unique user ID:
      If deselected, Nextcloud uses the mapped user ID in the Federated Cloud ID.

      tip

      To avoid a hashed Federated Cloud ID, deselect Use unique user ID and use user_id for the User ID mapping.

  3. Log in:
    Once configured, single sign-on (SSO) login via authentik becomes available.

Making OIDC the default login method​

Automatically redirect users to authentik when they access Nextcloud by running:

sudo -u www-data php var/www/nextcloud/occ config:app:set --value=0 user_oidc allow_multiple_user_backends