Keycloak with 2FA as Nextcloud backend

Blog Keycloak with 2FA as Nextcloud backend

Keycloak with 2FA as Nextcloud backend

10th Feb 2021 software Nextcloud LDAP Keycloak security

I've searched for a tutorial on how to use Keycloak as a user Backend for Nextcloud for weeks, but wasn't able to find one fitting my needs.

I wanted a solution that fulfills the following criteria:

use the correct username as the uid
be able to manage the quota of users
the least amount of running programs
use only a single protocol

This setup reduces the amount of passwords and 2FA needed for different services. It also reduces the amount of logins, as you only need to login to one account.

I used the following software:

I assume you already have set up Nextcloud and an instance of Keycloak with a realm and users with the following URLs:

Nextcloud: https://cloud.example.com
Keycloak: https://auth.example.com with realm example.com

Keycloak Configuration

Add Client in Keycloak

In the Keycloak admin console, select your realm
Create a new client: Configure > Clients > Create
- Client ID: nextcloud
Save and edit the new client
- Access Typ: confidential
- Valid Redirect URIs: https://cloud.example.com/apps/oidc_login/oidc or https://cloud.example.com/*
Copy the the secret under Credentials

Create/Modify Groups

Create groups as you like, eg. admin, and add your users to them. The groups will be mapped 1:1 to those in Nextcloud. Note that groups won't be created automatically in Nextcloud (Open PR).

Add a new attribute to the groups: Manage > Groups > GROUP_NAME > Attributes > Add

Key: nextcloudquota
Value: 549755813888 This is the size in bytes, here 512GiB

Add Mappers

Create a new Mapper: Configure > Clients > nextcloud > Mappers > Create
- Name: Nextcloud Quota
- Mapper Type: User Attribute
- User Attribute: nextcloudquota
- Token Claim Name: nextcloudquota
- Claim JSON Type: String
Create another Mapper: Configure > Clients > nextcloud > Mappers > Create
- Name: Groups Mapper
- Mapper Type: Group Membership
- Token Claim Name: groups
- Full group path: OFF

Configure Nextcloud

Install OpenID Connect Login from the App Store

Edit the config.php file (there are no UI settings) with the according settings:

<?php
$CONFIG = array (
// STANDARD NEXTCLOUD CONFIG

// Some Nextcloud options that might make sense here
'allow_user_to_change_display_name' => false,
'lost_password_link' => 'disabled',

// OIDC SPECIFIC CONFIG

// URL of provider. All other URLs are auto-discovered from .well-known
'oidc_login_provider_url' => 'https://auth.example.com/auth/realms/example.com',

// Client ID and secret registered with the provider
'oidc_login_client_id' => 'nextcloud',
// the secret you copied from Keycloak
'oidc_login_client_secret' => '$SECRET',

// Automatically redirect the login page to the provider
'oidc_login_auto_redirect' => true,

// Redirect to this page after logging out the user
'oidc_login_logout_url' => 'https://auth.example.com/auth/realms/example.com/protocol/openid-connect/logout?redirect_uri=https%3A%2F%2Fcloud.example.com%2F',

// Quota to assign if no quota is specified in the OIDC response (bytes)
// 15GB
'oidc_login_default_quota' => '549755813888',

// Hide the NextCloud password change form.
'oidc_login_hide_password_form' => true,

// Attribute map for OIDC response
'oidc_login_attributes' => array (
    'id' => 'preferred_username',
    'name' => 'name',
    'mail' => 'email',
    'quota' => 'nextcloudquota',
    'groups' => 'groups',
),

// Set OpenID Connect scope
'oidc_login_scope' => 'openid profile',

// Disable creation of new users from OIDC login
// needed since Keycloak is our only backend
'oidc_login_disable_registration' => false,

// Fallback to direct login if login from OIDC fails
// Note that no error message will be displayed if enabled
'oidc_login_redir_fallback' => false,
);

2FA in Keycloak

By default only OTP (as in the 6 digit codes) is enabled in Keycloak. We'll also enable WebAuthn, ie. hardware security tokens. We'll configure Keycloak to automatically choose the correct 2FA method.

Enable Webauthn Authenticator Registration

Open Authentication > Required Action
Select Webauthn Register as Required Action
Mark Enabled checkbox. Optionally mark Default Action checkbox if you want all new created users to be required to register WebAuthn credential

Create a new Browser Flow:

I have two options for a WebAuthn Browser Flow:

WebAuthn as 2nd Factor
WebAuthn as 1st Factor (Passwordless)

WebAuthn

Configure > Authentication > Flows > Select Browser and make a copy, call it WebAuthn for example

Edit the new copy as indented:

Delete Forms
Add Flow Webauthn Forms
- Add execution Username Password Form (REQUIRED)
- Add Flow Conditional 2FA (CONDITIONAL)
  - Add execution Condition - User Configured (REQUIRED)
  - Add execution WebAuthn Authenticator (ALTERNATIVE)
  - Add execution Condition - User Configured (REQUIRED)
  - Add execution OTP Form (ALTERNATIVE)

WebAuthn Passwordless

Configure > Authentication > Flows > Select Browser and make a copy, call it WebAuthn Passwordless for example

Edit the new copy as indented (the names of the Flows are arbitrary):

Delete Forms
Add Flow Webauthn Forms
- Add execution Username Form (REQUIRED)
- Add Flow Passwordless_or_2FA (REQUIRED)
  - Add execution WebAuthn Passwordless Authenticator (ALTERNATIVE)
  - Add Flow Password_and_2FA (ALTERNATIVE)
    - Add execution Password Form (REQUIRED)
    - Add Flow 2FA (CONDITIONAL)
      - Add execution Condition - User Configured (REQUIRED)
      - Add execution WebAuthn Authenticator (ALTERNATIVE)
      - Add execution Condition - User Configured (REQUIRED)
      - Add execution OTP Form (ALTERNATIVE)

Outlook

I want to explore the possibilities of Roles and integration with synapse.