Janik von Rotz

4 min read

OpenID Connect with Nextcloud and Keycloak

Keycloak and Nextcloud are both popular open source software. The first is an identity provider and broker, the second one is collaboration platform. Instead of having multiple accounts on several online platforms, you want to have one identity and log into multiple platforms. This is the job of the OpenID Connect protocol and is supported by Keycloak. In this guide I walk you through the steps of connecting Nextcloud with Keycloak to support a seamless single sign-on experience.

In our scenario we have these hosts and configurations:

I assume both services are configured and running without issues.

The authentication flow

What we want to achieve is quite common.

The authentication flow goes like this:

  1. Nextcloud redirects the user to Keylcoak
  2. The user authenticates with the Keycloak credentials
  3. User is redirected back to Nextcloud with a token
  4. Nextcloud retrieves an access token
  5. Nextcloud uses the access token to retrieve user information

Setup client in Keycloak

Lets get started by setting up the Keycloak client.

Client ID: nextcloud.example.com
Client Protocol: openid-connect
Root URL : https://nextcloud.example.com

Access Type: confidential

Role Name: admin

Token Claim Name: roles
Add to userinfo: ON

This mapper will ensure that the JWT-Token contains the user roles at the right location.

This will ensure that only the client roles are stored in the token.

Keep this browser tab open. We need it for the Nextcloud configuration.

Configure social login in Nextcloud

Now it is time to set up the Nextcloud social login.

[x] Prevent creating an account if the email address exists in another account
[x] Restrict login for users without mapped groups

Internal name: keycloak
Title: Example
Authorize url: https://login.example.com/auth/realms/example.com/protocol/openid-connect/auth
Token url: https://login.example.com/auth/realms/example.com/protocol/openid-connect/token
User info URL (optional): https://login.example.com/auth/realms/example.com/protocol/openid-connect/userinfo
Logout URL (optional): https://login.example.com/auth/realms/example.com/protocol/openid-connect/logout?redirect_uri=https%3A%2F%2Fnextcloud.example.com
Client Id: nextcloud.example.com
Client Secret: Copy from ephermal note
Scope: openid
Groups claim (optional): roles
Button style: Keycloak

If you would choose to let Nextcloud create the required groups from the userinfo, it would prefix all group names with keycloak-. We want to avoid this and therefore have to map every single group in Nextcloud.

If you get a success message from Nextcloud we are ready to test the login.

Test the login

First we are going to verify the token and userinfo.

If you get a JSON formatted response from the userinfo endpoint everything looks good. Otherwise let me know in the comments.

If you see a the Nextcloud intro, congratulation! You have successfully used Keycloak to log into Nextcloud with OpenID Connect.

Final note: The great benefit of using OpenID Connect over SAML is that you can still set a password for the user account and login using the email.


Cryptic Username

By default the username is generated using the keycloak- prefix, the Keycloak user id and the actual Keycloak username. To avoid this schema you need to override the sub property of the userinfo. Create a mapper for the client:

Name: sub
Mapper Type: User Prooperty
Property: username
Token Claim Name: sub

If a user logs into Nextcloud the username will be keycloak-$KEYCLOAK_USENRAME.

Further Readings

Learn more about Keycloak:

Categories: Identity and Access Management
Tags: keycloak , nextcloud , openid connect , oauth
Improve this page
Show statistic for this page