Authenticating Nextcloud with Keycloak using OpenID Connect

A few months ago I started over on my home server with a fresh install of CentOS 7.6 (now updated to 7.7). I haven’t had a ton of time to work on it all at once, so I’ve been adding services one by one as I need them enough to make time for setup.

To get away from having a different login for every different thing I installed Keycloak was one of the first things I set up. Keycloak is an open source identity and access management tool that provides single-sign on with OpenID Connect and SAML. OpenID Connect was easy enough to set up with Jenkins and Gitea (using the appropriate plugins), but when I set up NextCloud I couldn’t find a tutorial (or any documentation really) for the plugin that offered OpenID Connect as an authentication mechanism. This post will document my path to getting a working OpenID Connect login added to my NextCloud instance.

Software Versions

Because I’m only working against a single configuration and don’t know how generally it will apply across other versions, here’s the list of the software I’m using for this post.

Getting Started

I’ll assume from here that all the above pieces are installed and configured for general use, just not hooked up together. From memory: Keycloak needs a realm set up with at least one user that will be set up for Nextcloud and Nextcloud needs the Social Login app installed and enabled on the Apps page.

Keycloak

Go to the Realm Settings page and open the “OpenID Endpoint Configuration” link in a new tab to bring up the .well-known/openid-configuration page. You’ll want the information from this page later to configure the Social Login plugin in Nextcloud.

Open the Clients page and click the create button. Select:

Client IDnextcloud
Client Protocolopenid-connect
Root URLhttps://<URL here>/nextcloud/

Click Save. On the next page (Settings) set:

Access Typeconfidential

Click Save, then click on the Roles tab. Add a new role named “admin”. Click Save, then go to the Mappers tab and add a protocol mapper as follows:

Namerole
Mapper TypeUser Client Role
Client IDnextcloud
Token Claim Namenextcloud-roles
Claim JSON TypeString

Click save, then add the admin role to a Keycloak user as appropriate so admin access is available through the Keycloak authentication. You can verify the mapping and user by going back to clients > nextcloud > Client Scopes > Evaluate, selecting the user, then viewing the Generated Access Token.

Go to the Credentials tab to find the client secret that will be needed in Nextcloud.

Nextcloud

As a Nextcloud administrator user, go to the Settings > Administration > Social login page.

My preferred settings for the first section with reasoning:

  • Disable auto create new users: unchecked to allow users to be created from Keycloak without needing a separate user created in Nextcloud
  • Allow users to connect social logins with their account: unchecked because no users were created on Nextcloud directly.
  • Prevent creating an account if the email address exists in another account: checked
  • Update user profile every login: checked so user changes on Keycloak propagate on next use
  • Do not prune not available user groups on login: unchecked to propagate Keycloak changes on next use
  • Automatically create groups if they do not exists: unchecked to keep Social login from adding groups with the “keycloak-” prefix. I would have this checked if group names didn’t have a prefix added.
  • Restrict login for users without mapped groups: unchecked because all of my Keycloak users currently have access to Nextcloud, even if they don’t have a specific group assigned.
  • Disable notify admins about new users: unchecked

Be sure to click Save: nothing will warn you if you leave the page without saving.

Add a “Custom OpenID Connect” entry (many of these entries will refer to entries in the .well-known/openid-configuration page you opened earlier in Keycloak):

Internal Namekeycloak
Title Keycloak (OIDC)
Authorize url<.well-known entry: authorization_endpoint>
Token url<.well-known entry: token_endpoint>
User info URL <.well-known entry: userinfo_endpoint>
Logout URL <.well-known entry: end_session_endpoint>
Client Idnextcloud
Client Secret<Secret from the Credentials tab in Keycloak>
Scopeopenid
Groups claimnextcloud-roles

If you want to redirect to a specific page (instead of having it load a blank page when it goes to the logout URL) add: ?redirect_uri=<encodedRedirectUri> to the end, where <encodedRedirectUri> is a URI-encoded path to the page to load after logout.

Any roles listed in “nextcloud-roles” will be prefixed by “keycloak-” when they are converted into group names. I suspect, but haven’t confirmed, that it’s from the internal name of the connector. I had to add mappings from each of my roles to the group intended, though in the mapping there isn’t a prefix added, so “admin” -> “admin” correctly assigned users to the admin group. This is why I disabled “Automatically create groups if they do not exist” in the Social login settings.

Again, scroll all the way to the bottom of the page and click Save. Be sure the popup by the banner tells you that the page has saved.

Now go to your Personal > Social login settings page and from the Social login connect > Available providers section click on the Keycloak (OIDC) button. This will either bring you to your keycloak login page or, if you’re already logged in, simply add an entry for keycloak to your user.

Debugging

The easiest way I found to test was to have one tab logged in to the Keycloak administrator pages, one tab logged into my Nextcloud admin account, and a private window that I could log in and out of as needed as I tweaked controls for both parts.

Here a couple of the problems I ran into and why they were showing up:

ProblemResolution
No login button next to
SSO & SAML logins
Social login buttons are added to the
Direct log in page
Error: No id_token was found. Scope was set incorrectly, resulting in the
wrong data being read by Nextcloud.

Conclusion

At this point I have everything functioning so I can either connect social login to my current accounts or create accounts on Keycloak and have them be created in Nextcloud when used to log in, as well as assigning the admin group based on user role from Keycloak.

I may soon configure the login page to automatically redirect to the Keycloak OIDC connector (set ‘social_login_auto_redirect’ => true setting in config.php), but for now I’ll accept an extra click or two to log in, at least until I’ve used it for long enough for all of my sessions to time out and be logged back in.

Rothenburg ob der Tauber

For Labor Day we took a trip over to Rothenburg ob der Tauber, a town in the Bavarian region of Germany that still has a medieval walled city at its center.

The gate defenses are still intact, with multiple layers of walls to pass through and large gates to close across the way. Here’s the west gate from the outside and one of the southern gates from the inside:

The city was considered to be the ideal German “Home Town” by the Nazis. It was damaged by bombing during World War II, but donations from all over the world helped to rebuild it after the war. On the inside of the walkway around the top of the wall are stones with names and locations of donors. Below are the steps up to the walkway at a gate on the northern side of the city (Klingentor) and the view of a couple of the towers on the east side (Galentor and Röderturm) from inside the walkway. Röderturm is on the inside of a gate that has a bridge over a dry moat, but we didn’t get a picture of that on this trip.

In the center of town is St.Jakobskirche, or St. James’s Church is in the middle of Rothenburg. We didn’t go in on this trip, but we got a good view of it from the wall walk at the end of our visit.

Many of the buildings we saw were of the traditional “Half-Timbered” construction, where large pieces of timber were joined together to make the frame, then the gaps were filled in with a non-structural material, leaving the timber frame exposed on the outside of the building.

There were a number of fountains in Rothenburg. This one is the herrnbrunnen, which has a crowned mermaid with two fish tails on top. The inscription on it marks it as being from 1595, and it’s where bakers who were found to be fraudulent were dunked as a punishment.

All over Germany we’ve seen window boxes full of flowers outside houses, or when the weather isn’t as nice rows of potted flowers just inside windows. We don’t usually stop to take pictures of them, but this one caught my eye as being an interesting pattern.