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.
- CentOS 7.7
- Keycloak 6.0.1
- NextCloud 16.0.5
- Plugin: Social Login 2.2.3
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 ID | nextcloud |
|---|---|
| Client Protocol | openid-connect |
| Root URL | https://<URL here>/nextcloud/ |
Click Save. On the next page (Settings) set:
| Access Type | confidential |
|---|
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:
| Name | role |
|---|---|
| Mapper Type | User Client Role |
| Client ID | nextcloud |
| Token Claim Name | nextcloud-roles |
| Claim JSON Type | String |
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 Name | keycloak |
|---|---|
| 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 Id | nextcloud |
| Client Secret | <Secret from the Credentials tab in Keycloak> |
| Scope | openid |
| Groups claim | nextcloud-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:
| Problem | Resolution |
|---|---|
| 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.