ContextQMD
Back to Authentik

Integrate with Nextcloud

website/integrations/chat-communication-collaboration/nextcloud/index.mdx

latest21.1 KB
Original Source

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://nextcloud.com/

:::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 has access to only when using LDAP because 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 If there’s an issue with the configuration, you can log in using the built-in authentication by visiting http://nextcloud.company/login?direct=1. :::

Configuration methods

It is possible to configure Nextcloud to use OIDC, SAML, or LDAP for authentication. Below are the steps to configure each method.

import TabItem from "@theme/TabItem"; import Tabs from "@theme/Tabs";

<Tabs defaultValue="oidc" values={[ { label: "OIDC", value: "oidc" }, { label: "SAML", value: "saml" }, { label: "LDAP", value: "ldap" } ]}

<TabItem value="oidc">

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.

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

:::warning If you require server side encryption, you must use LDAP. OpenID and SAML will cause irrevocable data loss. :::

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)

Create property mapping (optional)

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

If you want to control user storage and designate Nextcloud administrators, you will need to create a property mapping.

  1. Log in to authentik as an administrator and open the authentik Admin interface.

  2. Navigate to Customization > Property mappings and click Create.

    • Select type: select Scope mapping.
    • Create Scope Mapping:

      • Name: Nextcloud Profile

      • Scope name: nextcloud

      • Expression:

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

# In Nextcloud, administrators must be members of a fixed group called "admin".

# If a user is an admin in authentik, ensure that "admin" is appended to their group list.
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)),
}

  3. Click Finish.

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

:::info 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). :::

Create an application and provider in authentik

  1. Log in to authentik as an administrator and open the authentik Admin interface.

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

    • 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 and slug values because they will be required later.
      • Set a Strict redirect URI to https://nextcloud.company/apps/user_oidc/code.
      • Select any available signing key.
      • Under Advanced protocol settings:
        • (optional) If you created the Nextcloud Profile scope mapping, add it to Selected Scopes.
        • Subject Mode: Based on the User's UUID
    • 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.

  3. Click Submit to save the new application and provider.

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

Nextcloud configuration

  1. In Nextcloud, ensure that the OpenID Connect user backend app is installed.

  2. Log in to Nextcloud as an administrator and navigate to Settings > OpenID Connect.

  3. Click the + button and enter the following settings:

    • Identifier: authentik

    • Client ID: Client ID from authentik

    • Client secret: Client secret from authentik

    • Discovery endpoint: https://authentik.company/application/o/<application_slug>/.well-known/openid-configuration

    • Scope: email profile nextcloud openid

    • Under 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 Nextcloud Profile property mapping was skipped)

      • Groups mapping: groups (leave blank if the Nextcloud Profile property mapping was skipped)

        :::tip Enable Use group provisioning to allow writing to this field. :::

    • Use unique user ID: If this option is disabled, Nextcloud will use the mapped user ID as the Federated Cloud ID.

    :::info If authentik and Nextcloud are running on the same host, you will need to add 'allow_local_remote_servers' => true to your nextcloud config.php file. This setting allows remote servers with local addresses. :::

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

    :::danger If you're using the Nextcloud Profile property mapping and want administrators to retain their ability to log in, make sure that Use unique user ID is disabled. If this setting is enabled, it will remove administrator users from the internal admin group and replace them with a hashed group ID named "admin," which does not have real administrative privileges. :::

Making OIDC the default login method

Automatically redirect users to authentik when they access Nextcloud by running the following command on your Nextcloud docker host:

```bash
sudo docker exec --user www-data -it nextcloud-aio-nextcloud php occ config:app:set --value=0 user_oidc allow_multiple_user_backends
```

Configuration verification

To confirm that authentik is correctly configured with Nextcloud, log out and then log back in by clicking OpenID Connect. You'll then be redirected to authentik to log in, and once authentication is successful, you'll reach the Nextcloud dashboard.

</TabItem> <TabItem value="saml">

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.

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

:::warning If you require server side encryption, you must use LDAP. OpenID and SAML will cause irrevocable data loss. :::

Create an application and provider in authentik

  1. Log in to authentik as an administrator and open the authentik Admin interface.

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

    • Application: provide a descriptive name, an optional group for the type of application, the policy engine mode, and optional UI settings.
      • Note the application slug because it will be required later.
    • Choose a Provider type: select SAML Provider 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.
      • Set the ACS URL to https://nextcloud.company/apps/user_saml/saml/acs.
      • Set the Issuer to https://authentik.company.
      • Set the Audience to https://nextcloud.company/apps/user_saml/saml/metadata.
      • Set the Service Provider Binding to Post.
      • Under Advanced protocol settings, set an available Signing certificate.
    • 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.

  3. Click Submit to save the new application and provider.

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

Download the signing certificate

  1. Log in to authentik as an administrator and open the authentik Admin interface.
  2. Navigate to Applications > Providers and click on the name of the newly created Nextcloud provider.
  3. Under Download signing certificate click Download. The contents of this certificate will be required in the next section.

Configure group quotas (optional)

To configure group quotas you will need to create groups in authentik for each quota, and a property mapping.

Create group/s in authentik (optional)

  1. Log in to authentik as an administrator and open the authentik Admin interface.
  2. Navigate to Directory > Groups and click Create.
  3. Set a name for the group (e.g. nextcloud-15GB), assign a custom attribute (e.g., nextcloud_quota), and click Create.
  4. Click the name of the newly created group and navigate to the Users tab.
  5. Click Add existing user, select the users that require this storage quota and click Add.

Create property mapping in authentik (optional)

  1. Log in to authentik as an administrator and open the authentik Admin interface.

  2. Navigate to Customization > Property mappings and click Create.

    • Select type: select SAML Provider Property Mapping as the property mapping type.
    • Create SAML Provider Property Mapping:

      • Name: Provide a name for the property mapping.

      • SAML Attribute Name: nextcloud_quota

      • Expression:

        python
        return user.group_attributes().get("nextcloud_quota", "1 GB")

        :::info Where "1 GB" is the default if a quota is not set. :::

  3. Click Finish to save the property mapping.

Configure quota attribute in Nextcloud (optional)

  1. Log in to Nextcloud as an administrator.
  2. Navigate to Settings > SSO & SAML Authentication.
  3. Set Attribute to map the quota to to nextcloud_quota.

Configure admin group (optional)

To grant Nextcloud admin access to authentik users you will need to create a property mapping.

Create property mapping in authentik (optional)

  1. Log in to authentik as an administrator and open the authentik Admin interface.
  2. Navigate to Customization > Property mappings and click Create.
    • Select type: select SAML Provider Property Mapping as the property mapping type.
    • Create SAML Provider Property Mapping:

      • Name: Provide a name for the property mapping.

      • SAML Attribute Name: http://schemas.xmlsoap.org/claims/Group

      • Expression:

        python
        for group in request.user.all_groups():
    yield group.name
if ak_is_group_member(request.user, name="<authentik nextcloud admin group's name>"):
    yield "admin"

Nextcloud configuration

  1. Log in to Nextcloud as an administrator and navigate to Apps by clicking your profile picture in the top right corner.

  2. Under App bundles, install the SSO & SAML authentication bundle.

  3. Click your profile picture in the top right corner and select Administrative settings. Under SSO & SAML authentication, click Use built-in SAML authentication.

  4. In the General section, set:

    • Attribute to map the UID to: http://schemas.goauthentik.io/2021/02/saml/uid
    • Optional display name: authentik

    :::danger Using the UID attribute as username is not recommended because of its mutable nature. If you map to the username instead, disable username changing and set the UID attribute to http://schemas.goauthentik.io/2021/02/saml/username. :::

  5. In the Identity Provider Data section, set:

    • Identifier of the IdP entity: https://authentik.company
    • URL Target of the IdP where the SP will send the Authentication Request Message: https://authentik.company/application/saml/<application_slug>/sso/binding/redirect/

    Under Show optional Identity Provider settings:

    • URL Location of the IdP where the SP will send the SLO Request: https://authentik.company/application/saml/<application_slug>/slo/binding/redirect/
    • X.509 certificate of the IdP: paste the contents of your certificate file

  6. In the Attribute mapping section, set:

    • Attribute to map the display name to: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name
    • Attribute to map the email address to: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
    • Attribute to map the user's groups to: http://schemas.xmlsoap.org/claims/Group (optional)

:::info If Nextcloud is behind a reverse proxy, force HTTPS by adding 'overwriteprotocol' => 'https' to the Nextcloud config/config.php file. See this guide for more details. :::

Configuration verification

To confirm that authentik is properly configured with Nextcloud, log out and log back in using the SSO and SAML log in option. You will be redirected to authentik to log in; if successful you will then be redirected to the Nextcloud dashboard.

</TabItem> <TabItem value="ldap">

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.

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

Create an application and provider in authentik

  1. Log in to authentik as an administrator and open the authentik Admin interface.

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

    • 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 LDAP as the provider type.
    • Configure the Provider: provide a name (or accept the auto-provided name) and the bind flow to use for this provider
    • 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.

  3. Click Submit to save the new application and provider.

Create an LDAP outpost

  1. Log in to authentik as an admin, and open the authentik Admin interface.

  2. Navigate to Applications > Outposts and click Create.

    • Name: provide a suitable name for the outpost.
    • Type: LDAP
    • Under applications, add the newly created Nextcloud application to Selected Applications.

  3. Click Create.

Nextcloud configuration

  1. In Nextcloud, ensure that the LDAP user and group backend app is installed.

  2. Log in to Nextcloud as an administrator.

  3. Navigate to Settings > LDAP user and group backend and configure the following settings:

    • On the Server tab:

      • Click the + icon and enter the following settings:
        • Host: enter the hostname/IP address of the authentik LDAP outpost preceded by ldap:// or ldaps://. If using LDAPS you will also need to specify the certificate that is being used.
        • Port: 389 or 636 for secure LDAP.
        • Under Credentials, enter the Bind DN of the authentik LDAP provider and the associated user password.
        • Under Base DN, enter the Search base of the authentik LDAP provider.

    • On the Users tab:

      • Set Only these object classes to Users.

    • On the LDAP/AD integration tab:

      • Uncheck LDAP/AD Username.
      • Set Other Attributes to cn.
      • Click Expert in the top right corner and enter these settings:
        • Internal Username Attribute: uid
        • UUID Attribute for Users: uid
        • UUID Attribute for Groups: gidNumber
      • Click Advanced in the top right corner and enter these settings:
        • Under Connection Settings:
          • Configuration Active: checked
        • Under Directory Settings:
          • User Display Name Field: name
          • Base User Tree: enter the Search base of the authentik LDAP provider.
          • Group Display Name Field: cn
          • Base Group Tree: enter the Search base of the authentik LDAP provider.
          • Group-Member Association: gidNumber
        • Under Special Attributes:
          • Email Field: mailPrimaryAddress

    • On the Groups tab:

      • Set Only these object classes to groups.
      • Select the authentik groups that require Nextcloud access.

    :::info If Nextcloud is behind a reverse proxy, force HTTPS by adding 'overwriteprotocol' => 'https' to the Nextcloud config/config.php file. See the Nextcloud admin manual for more details. :::

Configuration verification

To confirm that authentik is properly configured with Nextcloud, log out and log back in using LDAP credentials. If successful you will then be redirected to the Nextcloud dashboard.

</TabItem> </Tabs>

Resources