website/docs: Add OIDC auth integration with Nextcloud (#7406)
* Add OIDC auth docs * lint * fix note * lint * typo * Update index.md Signed-off-by: sdimovv <36302090+sdimovv@users.noreply.github.com> * clarify 2 SSO protocols * lint * Update index.md Signed-off-by: sdimovv <36302090+sdimovv@users.noreply.github.com> * fix typos Signed-off-by: Jens Langhammer <jens@goauthentik.io> --------- Signed-off-by: sdimovv <36302090+sdimovv@users.noreply.github.com> Signed-off-by: Jens Langhammer <jens@goauthentik.io> Co-authored-by: Jens Langhammer <jens@goauthentik.io>
This commit is contained in:
sdimovv
GitHub
parent
0e244c3eba
commit
30f9d6bf83
|
|
@ -18,7 +18,192 @@ This setup only works, when Nextcloud is running with HTTPS enabled. See [here](
|
|||
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.
|
||||
:::
|
||||
|
||||
## Preparation
|
||||
## Authentication
|
||||
|
||||
There are 2 ways to setup single sign on (SSO) for Nextcloud:
|
||||
|
||||
- [via OIDC Connect (OAuth)](#openid-connect-auth)
|
||||
- [via SAML](#saml-auth)
|
||||
|
||||
### OpenID Connect auth
|
||||
|
||||
#### Preparation
|
||||
|
||||
The following placeholders will be used:
|
||||
|
||||
- `nextcloud.company` is the FQDN of the Nextcloud install.
|
||||
- `authentik.company` is the FQDN of the authentik install.
|
||||
- `authentik.local` is the internal FQDN of the authentik install (only relevant when running authentik and Nextcloud behind a reverse proxy)
|
||||
|
||||
Lets start by thinking what 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_ inside them, such as:
|
||||
|
||||
- `email` scope: Has claims `email` and `email_verified`
|
||||
- `profile` scope: Has claims `name`, `given_name`, `preferred_username`, `nickname`, `groups`
|
||||
- `openid` scope: This is a default scope required by the OpenID spec. It contains no claims
|
||||
|
||||
##### Custom profile scope
|
||||
|
||||
If you do not need storage quota or group information in Nextcloud [skip to the next step](#provider-and-application).
|
||||
|
||||
However, if you want to be able to control how much storage users in Nextcloud can use, as well as which users are recognized as Nextcloud administrators, you would need to make this information available in Nextcloud. To achieve this you would need to create a custom `profile` scope. To do so, go to _Customisation_ -> _Property mappings_. Create a _Scope mapping_ with the following parameters:
|
||||
|
||||
- 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.
|
||||
# We append a fictional "admin" group to the user's groups if they are an admin in authentik.
|
||||
# This group would only be visible in Nextcloud and does not exist in authentik.
|
||||
if user.is_superuser and "admin" not in groups:
|
||||
groups.append("admin")
|
||||
|
||||
return {
|
||||
"name": request.user.name,
|
||||
"groups": groups,
|
||||
# To set a quota set the "nextcloud_quota" property in the user's attributes
|
||||
"quota": user.group_attributes().get("nextcloud_quota", None)
|
||||
}
|
||||
```
|
||||
|
||||
:::note
|
||||
To set a quota set the "nextcloud_quota" property in the user's attributes. This can be set for individual users or a group of users, as long as the target user is a member of a group which has this attribute set.
|
||||
|
||||
If set to a value, for example `1 GB`, user(s) will have 1GB storage quota. If the attribute is not set, user(s) will have unlimited storage.
|
||||
:::
|
||||
|
||||
##### Provider and Application
|
||||
|
||||
Create a provider for Nextcloud. In the Admin Interface, go to _Applications_ -> _Providers_. Create an _OAuth2/OpenID Provider_ with the following parameters:
|
||||
|
||||
- Name: Nextcloud
|
||||
- Client type: Confidential
|
||||
- Redirect URIs/Origins (RegEx): `https://nextcloud.company/apps/user_oidc/code`
|
||||
- Signing key: Any valid certificate
|
||||
- Under advanced settings:
|
||||
- Scopes:
|
||||
- `authentik default Oauth Mapping email`
|
||||
- `Nextcloud Profile` (or `authentik default Oauth Mapping profile` if you skipped the [custom profile scope](#custom-profile-scope) section)
|
||||
- Subject mode: Based on the User's UUID
|
||||
:::danger
|
||||
Nextcloud will use the UUID as username. However, mapping the subject mode to authentik usernames is **not recommended** due to their mutable nature. This can lead to security issues such as user impersonation. If you still wish to map the subject mode to an username, [disable username changing](../../../docs/installation/configuration#authentik_default_user_change_username) in authentik and set this to `Based on the User's username`.
|
||||
:::
|
||||
- Include claims in ID token: ✔️
|
||||
|
||||
Before continuing, make sure to take note of your `client ID` and `secret ID`. Don't worry you can go back to see/change them at any time.
|
||||
|
||||
:::warning
|
||||
Currently there is a bug in the Nextcloud OIDC app, that is [limiting the size of the secret ID](https://github.com/nextcloud/user_oidc/issues/405) token to 64 characters. Since authentik uses 128 characters for a secret ID by default, you will need to trim it down to 64 characters in order to be able to set it in Nextcloud. Don't worry, 64 characters is still sufficiently long and should not compromise security.
|
||||
:::
|
||||
|
||||
:::note
|
||||
Depending on your Nextcloud configuration, you might need to use `https://nextcloud.company/index.php/` instead of `https://nextcloud.company/`
|
||||
:::
|
||||
|
||||
After the provider is created, link it to an app. Go to _Applications_ -> _Applications_. Create an application and choose the provider you just created. Make sure to take note of the _application slug_. You will need this later.
|
||||
|
||||
#### Nextcloud
|
||||
|
||||
In Nextcloud, ensure that the `OpenID Connect user backend` app is installed. Navigate to `Settings`, then `OpenID Connect`.
|
||||
|
||||
Add a new provider using the `+` button and set the following values:
|
||||
|
||||
- Identifier: Authentik
|
||||
- Client ID: The client ID from the provider
|
||||
- Client secret: The secret ID from the provider
|
||||
- Discovery endpoint: `https://authentik.company/application/o/<nextcloud-app-slug>/.well-known/openid-configuration`
|
||||
:::tip
|
||||
If you are running both your authentik and Nextcloud instances behind a reverse proxy, you can go ahead and use your internal FQDN here (i.e. `http://authentik.local`, however, note that if you do so there is [extra configuration required](#extra-configuration-when-running-behind-a-reverse-proxy)).
|
||||
:::
|
||||
- Scope: `email`, `profile` (you can safely omit `openid` if you prefer)
|
||||
- Attribute mappings:
|
||||
- User ID mapping: sub
|
||||
- Display name mapping: name
|
||||
- Email mapping: email
|
||||
- Quota mapping: quota (leave empty if you have skipped the [custom profile scope](#custom-profile-scope) section)
|
||||
- Groups mapping: group (leave empty if you have skipped the [custom profile scope](#custom-profile-scope) section)
|
||||
:::tip
|
||||
You need to enable the "Use group provisioning" checkmark to be able to write to this field
|
||||
:::
|
||||
- Use unique user ID: If you only have one provider you can uncheck this if you prefer.
|
||||
|
||||
At this stage you should be able to login with SSO.
|
||||
|
||||
##### Making the OIDC provider the default login method
|
||||
|
||||
If you intend to only login to Nextcloud using your freshly configured authentik provider, you may wish to make it the default login method. This will allow your users to be automatically redirected to authentik when they attempt to access your Nextcloud instance, as opposed to having to manually click on "Log in with Authentik" every time they wish to login.
|
||||
|
||||
To achieve this, you will need to use the `occ` command of your Nextcloud instance:
|
||||
|
||||
```bash
|
||||
sudo -u www-data php var/www/nextcloud/occ config:app:set --value=0 user_oidc allow_multiple_user_backends
|
||||
```
|
||||
|
||||
##### Extra configuration when running behind a reverse proxy
|
||||
|
||||
The OpendID Connect discovery endpoint is queried by Nextcloud and contains a list of endpoints for use by both the relying party (Nextcloud) and the authenticating user.
|
||||
|
||||
:::note
|
||||
If you are configuring an insecure (http) discovery endpoint, Nextcloud will, by default, refuse to connect to it. To change this behaviour, you must add `allow_local_remote_servers => true` to your `config.php`
|
||||
:::
|
||||
|
||||
:::note
|
||||
It is currently not possible force Nextcloud to connect to an https endpoint which uses an untrusted (selfsigned) certificate. If this is the case with your setup, you can do one of 3 things:
|
||||
|
||||
- switch to using a trusted certificate
|
||||
- add the selfsigned certificate to Nextcloud's trust store
|
||||
- switch to using an http endpoint and add `allow_local_remote_servers => true` to your `config.php`
|
||||
|
||||
:::
|
||||
|
||||
Because authentik has no knowledge of where each endpoint is/can be accessed from, it will always return endpoints with domain names matching the one used to make the discovery endpoint request.
|
||||
|
||||
For example, if your Nextcloud instance queries the discovery endpoint using an internal domain name (`authentik.local`), all returned endpoints will have the same domain name. In this case:
|
||||
|
||||
- `http://authentik.local/application/o/<app-slug>/`
|
||||
- `http://authentik.local/application/o/authorize/`
|
||||
- `http://authentik.local/application/o/token/`
|
||||
- `http://authentik.local/application/o/userinfo/`
|
||||
- `http://authentik.local/application/o/<app-slug>/end-session/`
|
||||
- `http://authentik.local/application/o/introspect/`
|
||||
- `http://authentik.local/application/o/revoke/`
|
||||
- `http://authentik.local/application/o/device/`
|
||||
- `http://authentik.local/application/o/<app-slug>/jwks/`
|
||||
|
||||
This represents a problem, because Nextcloud will attempt to redirect the user to the received `authorization` and `end-session` endpoints during login and logout respectively. When that happens, the user will try to access an internal domain and fail.
|
||||
|
||||
The easiest way to fix this is to modify the redirect response's `Location` header coming back from Nextcloud during login and logout. Different proxies have different ways of achieving this. For example with Traefik, a 3rd party plugin called [Rewrite Header](https://plugins.traefik.io/plugins/628c9eb5108ecc83915d7758/rewrite-header) can be used.
|
||||
|
||||
At a minimum, the `authorize` and `end-session` endpoints must be edited in-flight like so:
|
||||
|
||||
- `http://authentik.local/application/o/authorize/` -> `https://authentik.company/application/o/authorize/`
|
||||
- `http://authentik.local/application/o/<app-slug>/end-session/` -> `https://authentik.company/application/o/<app-slug>/end-session/`
|
||||
|
||||
:::note
|
||||
HTTP headers are usually capitalised (e.g. **L**ocation), however, at least some versions of Nextcloud seem to return all lowercase headers (e.g. **l**ocation). To be safe, make sure to add header replacement rules for both cases.
|
||||
:::
|
||||
|
||||
If you prefer, you may also edit the rest of the endpoints, though that should not be necessary, as they should not be accessed by the user.
|
||||
|
||||
:::tip
|
||||
If you do not have any relying parties accessing authentik from the outside, you may also configure your proxy to only allow access to the `authorize` and `end-session` endpoints from the outside world.
|
||||
:::
|
||||
|
||||
### SAML auth
|
||||
|
||||
#### Preparation
|
||||
|
||||
The following placeholders will be used:
|
||||
|
||||
|
|
@ -40,7 +225,7 @@ Depending on your Nextcloud configuration, you might need to use `https://nextcl
|
|||
|
||||
You can of course use a custom signing certificate, and adjust durations.
|
||||
|
||||
## Nextcloud
|
||||
#### Nextcloud
|
||||
|
||||
In Nextcloud, ensure that the `SSO & SAML Authentication` app is installed. Navigate to `Settings`, then `SSO & SAML Authentication`.
|
||||
|
||||
|
|
@ -70,7 +255,7 @@ To do this you will need to add the line `'overwriteprotocol' => 'https'` to `co
|
|||
See https://docs.nextcloud.com/server/latest/admin_manual/configuration_server/reverse_proxy_configuration.html#overwrite-parameters for additional information
|
||||
:::
|
||||
|
||||
## Group Quotas
|
||||
#### Group Quotas
|
||||
|
||||
Create a group for each different level of quota you want users to have. Set a custom attribute, for example called `nextcloud_quota`, to the quota you want, for example `15 GB`.
|
||||
|
||||
|
|
@ -91,7 +276,7 @@ In Nextcloud, go to `Settings`, then `SSO & SAML Authentication`Under `Attribute
|
|||
|
||||
- Attribute to map the quota to.: `nextcloud_quota`
|
||||
|
||||
## Admin Group
|
||||
#### Admin Group
|
||||
|
||||
To give authentik users admin access to your Nextcloud instance, you need to create a custom Property Mapping that maps an authentik group to "admin". It has to be mapped to "admin" as this is static in Nextcloud and cannot be changed.
|
||||
|
||||
|
|
|
|||
Reference in a new issue