Installation

Installation

Prerequisites

• Nextcloud 29 – 32 installed and running
• PHP 8.1 or higher
• user_oidc app installed and enabled
• An OIDC identity provider configured in user_oidc

Method 1: Nextcloud App Store (recommended)

The easiest way to install the app. Updates are handled automatically through the Nextcloud admin interface.

Via the admin UI:

1. Go to Administration → Apps
2. Search for "OIDC Groups Mapping"
3. Click Install

Via OCC:

php occ app:install oidc_groups_mapping

App Store page: apps.nextcloud.com/apps/oidc_groups_mapping

Verify the installation

php occ app:list | grep oidc_groups_mapping

You should see oidc_groups_mapping listed under "Enabled".

Method 2: Manual install

Use these methods if you cannot access the App Store from your server, or if you want to run the latest development version.

From release tarball

# Navigate to your Nextcloud custom apps directory
cd /var/www/html/custom_apps/

# Download the latest release
wget https://github.com/strobelpierre/nextcloud_oidc_groups_mapping/releases/latest/download/oidc_groups_mapping.tar.gz

# Extract
tar xzf oidc_groups_mapping.tar.gz

# Enable the app
php occ app:enable oidc_groups_mapping

From source

Use this if you want to contribute or run the latest development version.

cd /var/www/html/custom_apps/
git clone https://github.com/strobelpierre/nextcloud_oidc_groups_mapping.git oidc_groups_mapping
cd oidc_groups_mapping

# Install PHP dependencies (without dev)
composer install --no-dev

# Build the frontend
npm ci && npm run build

# Enable the app
php occ app:enable oidc_groups_mapping

Updating

App Store installs

Updates are available automatically through the Nextcloud admin interface:

1. Go to Administration → Apps → Updates
2. If a new version is available, click Update

Alternatively, via OCC:

php occ app:update oidc_groups_mapping

Manual (tarball) installs

cd /var/www/html/custom_apps/

# Remove old version
rm -rf oidc_groups_mapping/

# Download and extract new version
wget https://github.com/strobelpierre/nextcloud_oidc_groups_mapping/releases/latest/download/oidc_groups_mapping.tar.gz
tar xzf oidc_groups_mapping.tar.gz

Good news: This app does not use a database. Your mapping rules are stored in IAppConfig and are preserved across updates — no migrations needed.

Uninstalling

# Disable the app
php occ app:disable oidc_groups_mapping

# Remove the app directory
rm -rf /var/www/html/custom_apps/oidc_groups_mapping/

Note: Disabling the app means it will no longer intercept OIDC login events. Group mapping will revert to the default user_oidc behavior (single mappingGroups claim only). Your existing rules configuration is preserved in IAppConfig until you remove the app data.

Next steps

Head to Getting Started to configure your first mapping rules.