Configure Nextcloud With SAML Auth

Summary

I have come to the realization that online documentation around configuring Nextcloud to use SAML is lacking. I am not an expert by ANY means but I know enough to get things working with some trial and error. The following post is more or less a TL;DR of what to set to enable SAML auth in Nextcloud via Keycloak.

Deployment

Versions

• Nextcloud: 14.5.0
  • SSO & SAML authentication: 6.0.1
• Keycloak: 21.1.2

Setup Nextcloud SAML

Below are the settings needed for each section of the SAML settings page, do note most settings are hidden so you will need to expand them.

Global settings

1. Select: “Use SAML auth for the Nextcloud desktop clients (requires user re-authentication)”

From this point on, do not log out of the local admin user!

General

Service Provider Data

For this next step we are going to need to create a certificate and key for Nextcloud and Keycloak, below is an example, take note of the days option and set it to fit your needs. If you set this to be too short and fail to reset the certificate before it expires you will need to reset it manually, I have a post on the here: Repairing Nextcloud SAML When Certs Expire

cd /tmp
openssl req -newkey rsa:2048 -nodes -keyout Keycloak-server.key.pem -x509 -days 365 -out Keycloak-server.crt.pem

We now have a key and cert in our /tmp directory, delete these when you are done…..

Name ID format:

Identity Provider Data

Next we need the Keycloak realms X.509 certtificate

1. Head to the realm
2. Realm settings
3. Keys
4. The public certificate of RS256 key

Attribute mapping

The user quota is not strictly needed, however, if you do not set it users will have an unlimited amount of storage allocated to them.

Security settings

Signatures and encryption offered:

1. Select:
   Indicates whether the <samlp:AuthnRequest> messages sent by this SP will be signed. [Metadata of the SP will offer this info]
2. Select:
   Indicates whether the <samlp:logoutRequest> messages sent by this SP will be signed.
3. Select:
   Indicates whether the <samlp:logoutResponse> messages sent by this SP will be signed.

Signatures and encryption required:

1. Select:
   Indicates a requirement for the <samlp:Response>, <samlp:LogoutRequest> and <samlp:LogoutResponse> elements received by this SP to be signed.
2. Select:
   Indicates a requirement for the <saml:Assertion> elements received by this SP to be signed. [Metadata of the SP will offer this info]

On the bottom left of the window you should now see a small green banner that states Metadata valid, proceed to download the metadata XML file.

This file contains the key we made earlier on in this post, as such this file contains sensitive info. Make sure it is deleted when the client is created in the next step.

Setup Keycloak

Setup Client

Import the client
Remember to remain in the realm defined in the Nextcloud config above. From the “Clients” tab, click “Import client”

1. Upload the metadata.xml
2. Add a name if you wish
3. Save

Setup Client Scopes
Select client scopes from the client, so on the left, select “Clients” –> “Client scopes”, now:

1. Delete role_list client scope
2. Edit the remaining client scope (This will be a URL)
3. Configure a new mapper
   1. User Attribute
   2. Name: username
   3. User Attribute: username
   4. Friendly Name: username
   5. SAML Attribute NameFormat: Basic
   6. Aggregate attribute values: Off
   7. Save, then go back to “Dedicated scopes”
4. Add mapper (By configuration) 1. User Attribute
   2. Name: email
   3. User Attribute: email
   4. Friendly Name: email
   5. SAML Attribute NameFormat: Basic
   6. Aggregate attribute values: Off
   7. Save, then go back to “Dedicated scopes”
5. Add mapper (By configuration) 1. User Attribute
   2. Name: quota
   3. User Attribute: quota
   4. Friendly Name: quota
   5. SAML Attribute NameFormat: Basic
   6. Aggregate attribute values: Off
   7. Save, then go back to “Dedicated scopes”
6. Add mapper (By configuration)
   1. User Attribute
   2. Name: groups
   3. User Attribute: groups
   4. Friendly Name: groups
   5. SAML Attribute NameFormat: Basic
   6. Aggregate attribute values: Off
   7. Save, then go back to “Dedicated scopes”
7. Add mapper (By configuration)
   1. Role list 2. Name: role
   3. Role attribute name: Role
   4. Friendly Name: role
   5. SAML Attribute NameFormat: Basic
   6. Single Role Attribute : On
   7. Save

Setup user

The user needs to be created in the same realm the client was created for. So from this realm select the “Users” tab on the left, then select “Add user”. Fill out the user as you see fit, keep in mind the username here will be the username in Nextcloud. After you create your user, this user will need two attributes added, so after creating the user go back. Select the “Attributes” tab, select “Add an attribute”, then create the following two attributes:

The quota parameter is not technically needed and can be omitted, however if it is not specified the user will have no storage limit. The admin group obviously gives a user admin rights, in my case I will be logging in as myself and disabling the local admin user.

Testing

Once your user has been created, DO NOT log out of the local admin user, if there is an issue with the login process you will be locked out and will most likely need to make manual edits to the database to unlock the local admin user. Open a private browser and attempt the login process with your new admin user. After you have logged into Nextcloud as the new Keycloak backed admin user, then you can log out of the local admin user account (in the non-private browser), log back in as the Keycloak admin user (via a non-private browser), then finally disable the local user. This serves a couple purposes, obviously forcing you to log out of the local admin clears the session, but more importantly it ensures that when you have logged in as the Keycloak backed admin user the permissions are set correctly, as only an admin can disable another admins account.

If you run into any issues with SAML the Nextcloud logs may help, but I have found them to not be very useful. Firefox has a plugin called SAML-tracer, and I have found this to be endlessly useful even as a complete SAML novice, it will give you the errors.

Sources

• OpenID Connect with Nextcloud and Keycloak
• Nextcloud SSO with Keycloak