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:
- Keycloak server (OpenID Provider)
- Nextcloud server (Relying Party)
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:
- Nextcloud redirects the user to Keylcoak
- The user authenticates with the Keycloak credentials
- User is redirected back to Nextcloud with a token
- Nextcloud retrieves an access token
- Nextcloud uses the access token to retrieve user information
Setup client in Keycloak
Lets get started by setting up the Keycloak client.
- Open the Keycloak Admin Console
- Select your realm and create a new client Configure > Clients > Create
Root URL :
- Click Save and update these settings for the new client:
- Click Save and open the Roles tab and add a new role:
- Return to the clients view and open the Mappers tab
- Click Add Builtin, search for
client rolesand add it
- Open the new mapper and make these configurations:
Token Claim Name:
Add to userinfo:
This mapper will ensure that the JWT-Token contains the user roles at the right location.
- Click Save and open the Credentials tab
- Copy the Secret to an ephermal note
- Open the Scope tab and disable Full Scope Allowed
This will ensure that only the client roles are stored in the token.
- Navigate to Configure > Realm Settings > General tab and click on OpenID Endpoint Configuration
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.
- Open the App dashboard
- Install the Social Login app
- Navigate to Settings > Administration > Social login
- Set the options according your requirements or check at least these options:
[x] Prevent creating an account if the email address exists in another account
[x] Restrict login for users without mapped groups
- Save the settings
- Click on the Custom OpenID Connect plus button
- Enter the information from the open Keycloak browser tab:
User info URL (optional):
Logout URL (optional):
Client Secret: Copy from ephermal note
Groups claim (optional):
- Add a mapper with Add group mapping
- Enter in both fields:
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.
- Click on Save at the end of the page
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.
- Apply the client admin role to your personal Keycloak account
Open the command line, update the script below and run it.
# Setttings KEYCLOAK_HOST=login.example.com KEYCLOAK_USERNAME=<Keycloak username> KEYCLOAK_PASSWORD=<Keycloak password> KEYCLOAK_REALM=<Keycloak realm name> KEYCLOAK_CLIENT_SECRET=<Keycloak client secret> CLIENT_ID=nextcloud.example.com # Get token TOKEN=$(curl -s \ -d "client_id=$CLIENT_ID" \ -d "client_secret=$KEYCLOAK_CLIENT_SECRET" \ -d "username=$KEYCLOAK_USERNAME" \ -d "password=$KEYCLOAK_PASSWORD" \ -d "grant_type=password" \ "https://$KEYCLOAK_HOST/auth/realms/$KEYCLOAK_REALM/protocol/openid-connect/token" | jq -r '.access_token') # Use token to get userinfo curl \ -H "Authorization: bearer $TOKEN" \ https://$KEYCLOAK_HOST/auth/realms/$KEYCLOAK_REALM/protocol/openid-connect/userinfo
If you get a JSON formatted response from the userinfo endpoint everything looks good. Otherwise let me know in the comments.
- Open a private browser window and open Nextcloud
- Click on Login with Example
- Login with the Keycloak account
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.
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:
Token Claim Name:
If a user logs into Nextcloud the username will be
Learn more about Keycloak:
Tags: keycloak , nextcloud , openid connect , oauth
Improve this page
Show statistic for this page