How to Setup SAML-based Single Sign-On Authentication with Keycloak

In this article we will provide a step-by-step guide to configure SAML-based Single Sign-On (SSO) authentication in your Nextcloud instance.

Single Sign-On is an important step toward improving user experience if you are running Nextcloud as an application among others that serve different purposes, for example a CRM system or a support system.

In this article we will provide a step-by-step guide to configure SAML-based Single Sign-On (SSO) authentication in your Nextcloud instance.

Single Sign-On is an important step toward improving user experience if you are running Nextcloud as an application among others that serve different purposes, for example a CRM system or a support system.

The benefits are clear for both the platform operator, who has a central point to manage user identities, authentication and, to some extent, authorization; and for the user, who would b prevented of experiencing the many-passwords management problem, thus avoiding the typical bad choice of setting the same (simple) password for all the digital services he/she is entitled to log in to.

From now on in this tutorial, we will also refer to Keycloak as the Identity Provider and to Nextclod as the Service Provider, the standard nomenclature in a SSO setup where different Service Providers delegate authentication to a unique, centralized Identity Provider.

Nextcloud supports SAML-based authentication thanks to an officially supported app, SSO & SAML authentication, that is guaranteed to be compatible with recent platform versions, offers a web-based configuration panel and some advanced features, such as role-based filtering and handling of signed and/or encrypted Identity Provider responses. Nextcloud also supports OpenID-based authentication, but its configuration is not in scope of this article.

For the scope of this tutorial, the Identity Provider is Keycloak, that we have choosen as its use is widespread and it is open-source.

Software environment

The procedure described in this tutorial has been tested in the following software environment in a Local Area Network and with no reverse proxies in the middle, meaning that TLS certificates are handled locally in the systems.

If you want to try out the tutorial, you will need administrative users for both the Keycloak instance and the Nextcloud instance.

Overview

We outline here the procedure, so that you can get a grasp of what we are going to do:

1. Identity Provider configuration: we will create a realm and get a parameter that we need for the Service Provider configuration.
2. Service provider configuration: we will install and configure the app called SSO & SAML Authentication.
3. Identity Provider configuration: we will import the client definition as well as create a client scope fit for a Nextcloud-based service provider.
4. Create and configure for access a sample user in Keycloak, with his roles.
5. Test the login flow into Nextcloud with that user.
6. Troubleshooting.

Identity Provider Configuration

In Keycloak, create a new realm called localenv:

In the Service Provider configuration we will need the public X.509 certificate of this Keycloak instance. We can get it by navigating to Realm Settings->Keys and clicking on the Certificate button in the line corresponding to Algorithm RS256 and in column Public Keys:

Copy the whole string, put it between -----BEGIN CERTIFICATE---- and -----END CERTIFICATE---- tags and save it for later use.

Service Provider configuration

In Nextcloud, install the app SSO & SAML authentication. You can do that from the Web UI by searching and installing the app from the App Store:

Or from the command line, with the utility occ:

$ occ enable:user_saml
user_saml 6.5.0 enabled

Go to the SSO & SAML Authentication settings page (accesible either via navigation through admin settings or directly at /settings/admin/saml) and fill in the fields with the values specified in the table below:

At this point you should be able to download the metadata file, an XML file that you'll import in Keycloak as a client in the realm localenv.

Identity Provider configuration

Client Import and Configuration

In the Keycloak Web UI, import the client using the metadata.xml file exported from the Nextcloud instance. Navigate to Clients->Import Client and select for upload the XML file that you created earlier. Most fields will be autofilled but you can also optionally provide Name and Description if you wish. Once finished click on Save.

The new client should now be listed in the realm clients:

Attributes and Client Scopes

Keycloak gives you the possibility to customize which attributes it sends back when a client (that is a Service Provider that provides authentication to) requests authentication for a user. In this tutorial, taking into account the nature of Nextcloud as a Service Provider, we would need to send the following attributes:

• username: it will be used as the account name in Nextcloud

• email: used to store the primary email address of the user in Nextcloud

• quota: used to set the storage quota of the user in Nextcloud

• firstname, used in display name in Nextcloud

• lastname, used in display name in Nextcloud

The implementation of this setup in Keycloak is done via the creation of a client scope with the above attributes and the assignment of this client scope to the client defined for the Service Provider.

While there are other attributes that Nextcloud is able to read from the IdP response, they are out of scope of this tutorial.

Definition of attribute quota

Among the attributes that we want Keycloak to include in the response to the Nextcloud authentication request, the only one that is not pre-defined is "quota". So we will need to define it.

Go to Realm settings->User profile, then Create attribute. Fill in the values and click on Save.

Once saved you should see the quota in the list of attributes defined for the realm:

Now, define a new client scope, called nextcloud-user, by navigating to Manage-Client->Scopes. Fill in the parameters - the type must be SAML - then Save:

Once saved you should see the client scope nextcloud-user in the list of client scopes defined in the realm localenv:

It's now time to define in the client scope called nextcloud-user, the mappers, that is the attributes that will be included to authentication responses for clients that have this client scope enabled (we didn't enable it yet for our client, we will do it later).

Your mappers in the client scope nextcloud-user will look like in the following table:

Please note that lastname, email and firstname are defined from predefined mappers and quota is defined as a User Attribute, not as a User Property like the others.

As an example, in this screenshot you can check the definition of username:

It's time to add the client scope nextcloud-user to the client that we created for the Nextcloud instance. In Manage->Clients click on the client named nc.localenv.com then move to tab Client scopes. You can add the client scope nextcloud-user by clicking on Add client scope and selecting it.

Finally you can also change the mapper for client scope role_list to have the role attribute name matching the one that is expecting the Nextlcoud instance, that is roles.

As shown in the following screenshot, go to Manage->Client scopes, select role_list, then move to tab Mappers. Click on role list and modify as shown. Make sure that Single Role Attribute is on.

User creation

Before creating a user, let's create a role, that is a property that Nextcloud uses as a group. A role assigned to a user will become a group membership for the user in Nextcloud.

Navigate to Manage->Realm roles and add one or more roles In our example we add two roles, nc-group-1 and nc-group-2:

To create a user go to Manage->Users and click on Add user. Fill in all the parameters that we defined attribute mappers on, that is username, email, first name, last name and quota. Do not forget to define a password in tab Credentials and to assign at least one role to the user in tab Role mapping.

In our example the username is dwhite, the email This email address is being protected from spambots. You need JavaScript enabled to view it., first name is Daniel, last name is White and the quota is 10GB.

Please note that we have removed any predefined role for the user. This is not compulsory, but will help you keeping your Nextcloud instance clean, as all the groups the users belong to are created (if not defined yet) when the user authenticates.

Testing the login

At this point we should be able to login into Nextcloud with the user created in Keycloak. When opening the Nextcloud url, https://nc.localenv.com in our case, you should be automatically redirected to the authentication page on Keycloak (unless you have defined more than one authentication backend, in which case you will need to choose the one you want to use).

Once you logged in you can check that all the attributes defined in Keycloak have been passed through correctly to Nextcloud by connecting to the user settings page:

If you are not able to connect (the most common error is Account not provisioned) or if you don't find some attributes that you may expect, review the troubleshooting section.

Troubleshooting

If you get an Account not provisioned or other errors, the recommended way to troubleshoot is to inspect the Nextcloud log. You'll need to have the most verbose log level for that and an handy way to switch to that log level just for the purpose to troubleshoot issues with SAML authentication would be to add the following line in your config.php file:

'log.condition' => ['apps' => ['user_saml']]

Upon successful login you should see the following entries in the log (processed with grep and jq):

$ tail -f /var/www/nextcloud/data/nextcloud.log | grep saml | jq .message
"Attributes send by the IDP: {"lastname":["White"],"username":["dwhite"],"firstname":["Daniel"],"email":["This email address is being protected from spambots. You need JavaScript enabled to view it."],"quota":["10GB"],"roles":["nc-group-1","nc-group-2"]}"
"Authentication successful"
"Email attribute content: This email address is being protected from spambots. You need JavaScript enabled to view it."
"Display name attribute content: Daniel White"
"Quota attribute content: 10GB"
"Group attribute content: ["nc-group-1","nc-group-2"]"
"Updating attributes for existing user"
"Email address not updated"
"Display name not updated"
"Quota updated"
"Checking group SAML_nc-group-1 for removal"
"Checking group SAML_nc-group-2 for removal"
"Checking group SAML_nc-group-1 for addition"
"Checking group SAML_nc-group-2 for addition"
"Incoming groups updated"
"Session values set"
"User found, last login timestamp updated"

The system is reporting which attributes have been sent by the Identity Provider and if they have been parsed correctly and transformed into user properties for the user in Nextcloud.

Conclusion

In this article we have outlined a step-by-step procedure to setup Single Sign-On authentication in Nextcloud using a widespread Identity Provider, Keycloak.

The goal of the tutorial is to help you in getting started with the integration. As you saw the setup requires the definition of many parameters but, luckily, these parameters can be managed from the graphical interfaces of Nextcloud and Keycloak. This procedure is just a starter though. If you are interested in implementing this in production in your organization, there are many other topics that need to be understood and addressed: high availability, optimization of user first authentication experience, roles definition policy in Keycloak, secure deployment, group-based filtering, deployment architecture and more