habsi/authentik
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
a15365a9f1b570150d52d3b51f34408cda0000c7
authentik/website/integrations/services/nextcloud/index.mdx
Teffen Ellis bfdb827ff9 website/docs: Update Docusaurus config. Prep for version picker. (#14401) 
* website/docs: Clean up config. Add types.

* website/docs: Format MDX.

* website: Fix build warnings. Lint badges frontmatter.
2025-05-06 10:04:39 -04:00

308 lines
12 KiB
Plaintext
Raw Blame History

---
title: Integrate with Nextcloud
sidebar_label: 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](https://docs.nextcloud.com/server/latest/admin_manual/configuration_files/encryption_configuration.html), 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](https://docs.nextcloud.com/server/stable/admin_manual/configuration_server/reverse_proxy_configuration.html?highlight=overwriteprotocol#overwrite-parameters) 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.
import TabItem from "@theme/TabItem";
import Tabs from "@theme/Tabs";
<Tabs
defaultValue="oidc"
values={[
{ label: "OpenID Connect", value: "oidc" },
{ label: "SAML", value: "saml" },
]}
>
<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.
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](#provider-and-application).
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:**
```python
# 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](../../../docs/sys-mgmt/settings#allow-users-to-change-username) 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](https://apps.nextcloud.com/apps/user_oidc) 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/`.
:::
3. **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.
:::
:::danger
If you are using a custom profile scope and want administrators to be able to log in, ensure that **Use unique user ID** is deselected. Otherwise, this setting will remove Administrator users from the internal admin group and replace them with a hashed group ID named "admin", which lacks actual admin access rights.
:::
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:
```bash
sudo -u www-data php var/www/nextcloud/occ config:app:set --value=0 user_oidc allow_multiple_user_backends
```
</TabItem>
<TabItem value="saml">
### SAML Auth
## 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.
:::note
This documentation lists only the settings you need to change from their default values. Other changes might cause issues accessing your application.
:::
1. **Create an application in authentik:**
Note the chosen slug as it will be used later.
2. **Create a SAML provider:**
In authentik, navigate to **Applications > Providers** and create a **SAML provider** with the following settings:
- **ACS URL:**
`https://nextcloud.company/apps/user_saml/saml/acs`
- **Issuer:**
`https://authentik.company`
- **Service Provider Binding:**
Post
- **Audience:**
`https://nextcloud.company/apps/user_saml/saml/metadata`
- **Signing certificate:** Select any valid certificate.
- **Property mappings:** Select all managed mappings.
:::note
Depending on your Nextcloud configuration, you might need to use `https://nextcloud.company/index.php/` instead of `https://nextcloud.company/`.
:::
#### Nextcloud configuration
1. **Install the app:**
In Nextcloud, ensure the **SSO & SAML Authentication** app is installed. Then navigate to **Settings > SSO & SAML Authentication**.
2. **Configure the following settings:**
- **Attribute to map the UID to:**
`http://schemas.goauthentik.io/2021/02/saml/uid`
:::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](https://docs.goauthentik.io/docs/sys-mgmt/settings#allow-users-to-change-username) and set the UID attribute to `http://schemas.goauthentik.io/2021/02/saml/username`.
:::
- **Optional display name:** `authentik`
- **Identifier of the IdP entity:**
`https://authentik.company`
- **URL target for authentication requests:**
`https://authentik.company/application/saml/<application-slug>/sso/binding/redirect/`
- **URL for SLO requests:**
`https://authentik.company/application/saml/<application-slug>/slo/binding/redirect/`
- **Public X.509 certificate of the IdP:**
Paste the PEM from your selected certificate.
3. **Set attribute mapping:**
Configure the following mappings:
- **Display name:**
`http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name`
- **Email:**
`http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress`
- **User groups:**
`http://schemas.xmlsoap.org/claims/Group`
:::note
If Nextcloud is behind a reverse proxy, force HTTPS by adding `'overwriteprotocol' => 'https'` to the Nextcloud `config/config.php` file. See [this guide](https://docs.nextcloud.com/server/latest/admin_manual/configuration_server/reverse_proxy_configuration.html#overwrite-parameters) for more details.
:::
#### Group quotas
1. **Set up groups:**
Create a group for each storage quota level and assign a custom attribute (e.g., `nextcloud_quota`) with values like `15 GB`.
2. **Create a custom SAML property mapping:**
Name the mapping **SAML Nextcloud Quota** with:
- **SAML Attribute Name:** `nextcloud_quota`
- **Expression:**
```python
return user.group_attributes().get("nextcloud_quota", "1 GB")
```
(Here, `"1 GB"` is the default if no quota is set.)
3. **Configure Nextcloud:**
In Nextcloud under **Settings > SSO & SAML Authentication**, set the **Attribute to map the quota to** as `nextcloud_quota`.
#### Admin group
To grant admin access to authentik users:
1. **Create a custom SAML property mapping for admins:**
Configure a mapping with:
- **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"
```
2. **Update the Nextcloud provider:**
Replace the default Groups mapping with this custom mapping.
</TabItem>
</Tabs>
Reference in New Issue View Git Blame Copy Permalink