Single-Sign-On into Nextcloud using Admidio as an OpenID Provider

Starting with version 5.0, Admidio can be used by other applications to authenticate users against Admidio's user base. These instructions will guide you through the process of connecting Nextcloud to Admidio to use Admidio's login. For general instructions, and other apps, please visit the general Single-Sign-On overview page.

Nextcloud provides several apps that offer OpenID Connect login to Nextcloud:

Throughout the document we will assume you have both Admidio and Nextcloud already set up properly at https://admidio.local/ and https://nextcloud.local/. Please modify these URLs to your actual installation.

As a first step, one needs to configure Admidio to act as an OpenID Provider (OP). This has to be done once and is not specific to any particular client. Please folow this guide:

Basically, one needs to enable OpenID Connect (OIDC). The Issuer URL should in most cases be left blank, which means Admidio's public URL will be used as issuer URL.

The page https://admidio.local/adm_program/modules/preferences.php?panel=sso also provides the link to the automatic discovery URL, and the individual settings for clients that do not support auto-configuration via metadata.

Setting up a client (OpenID „Relying Party“ = „RP“) to use Admidio's user accounts for log-in consists of two steps:

1. The client (RP, Nextcloud in our case) needs to be set up with the data about the OpenID Provider (OP). If the plugin supports auto-discovery, paste the .well-known/openid-configuration URL from Admidio into the plugin config. Otherwise one has to manually paste the endpoint URLs of the OpenID provider. Since Admidio provides those URLs with copy buttons in the preferences screen, even the manual configuration is rather straightforward.
2. Admidio needs to be told about the client. In particular, the entity ID and the redirect URL must be given, and a custom-generated (random) secret must be copied to the client configuration.

The concrete steps are:

• At the Relying Party (RP) - Nextcloud in our case - install the extension to support OpenID login.
  • Configure it either with Admidio's discovery URL (if supported), or enter the EntityID and the URL endpoints for authentication, token and userinfo.
  • Also, choose which scopes (groups of profile fields) should be requested from Admidio („openid“ is required; If Admidio's groups/roles should be mapped to the client's groups, the „groups“ scope is also required).
• In Admidio, create a new OpenID client.
  • Choose an easily understood label for the client (only used in Admidio's list of clients, but has no technical use)
  • Enter the ClientID from the RP, copy the created Client Secret (you will later need to paste it into the Nextcloud configuration), and enter the Redirect URI for the RP. The latter can be found on the plugin's configuration page in Nextcloud.
  • Many open source OIDC clients do not support encryption (PKCE, which is a security mechanism that prevents attackers from obtaining access unless their application started the initial login). By default, PKCE is required by Admidio, so in this case make sure that the requirement checkbox is turned off. Otherwise you will get an error.
  • In Admidio, map the user ID, username, email and fullname to fields that are included in the OpenID login response (so-called „claims“) and enter the corresponding claim names in Nextcloud.

The most convenient OpenID Connect support for Nextcloud is provided by the „OpenID Connect user backend (user_oidc)“ plugin. It supports multiple OpenID Providers, support for groups, fields mapping, automatic user-creation on login and auto-discovery of settings. Its configuration is done in Nextcloud's preferences UI.

For convenient mapping of OIDC claims to Nextcloud profile fields, use the OIDC Claim Mapping plugin. To map admidio groups to Nextcloud groups in a visual style, use the OIDC Groups Mapping plugin.

First, install the OpenID Connect user backend app in Nextcloud:

After installation it can be configured by an administrator in Nextcloud's preferences in the menu item „Administration“ → „OpenID Connect“.

• Create a new Provider by clicking on the „+“.

The configuration of the provider in Nextcloud is now best done in parallel with the client configuration in Admidio.

It is now a good idea to keep two browser windows open with Admidio and Nextcloud's configuration so one can easily select and copy the settings. Admidio even provides little „copy“ buttons/icons to copy the various settings to the clipboard for easy pasting into the Nextcloud configuration.

Return to Admidio's SSO preferences page, go to the „Single-Sign-On Client Administration“ (the button right below the endpoint URLs and above the „Save“ button), and create a new client.

• Nextcloud's user_oidc plugin uses the Discovery URL (of the form https://[YOUR_ADMIDIO]/modules/sso/index.php/oidc/.well-known/openid-configuration) from Admidio to configure most of the general OpenID Connect settings automatically. Copy the Discovery URL from the top of the OIDC client page in Admitio into NextCloud's „Discovery endoint“ field. All other endpoints shown in Admidio's preferences screen are provided in the discovery document and don't need to be copied manually.

• The Client Name is the label of the client in Admidio's client list, it can be anything you like.
• The „Client ID“ and „Client Secret“ in Admidio and Nextcloud have to match exactly. The ID is typically the client's URL, although some clients allow any unique identifier. The Client Secret should be a random string and will serve like a password. Admidio will create one and allow it to be copied to the client. Afterwards it is only stored as a hash in the database and can not be recovered any more. However, one can always create a new Client Secret in Admidio and copy that to the client's configuration.
• Nextcloud will display its Redirect URL at the very top of the form, which needs to be copied to Admidio's OpenID client configuration.

• Enter the scopes you desire in the Nextcloud config and make sure that Admidio's config matches it. At least openid must be included (Admidio will implicitly add it). If group support is desired, the „groups“ scope must be included (and the corresponding groups claim mapped, and group support selected in the Nextcloud config).

• In addition, Nextcloud also provides settings to map OpenID claims (defined profile fields with a fixed name, defined in the OpenID standard) to the Nextcloud user's profile data. None of them are required, but they can be mapped, if profile information should be transferred from Admidio to Nextcloud:

After saving the changes (both in Nextcloud and Admidio), the apps should should now be set up for single-sign-on in Nextcloud.

The „**OpenID Connect Login**“ plugin for Nextcloud provides OpenID login with support for groups, field mapping, automatic user-creation on login and auto-discovery of settings. Its configuration is done entirely in Nextcloud's config/config.php file, there is no graphical user interface.

• First, install the OpenID Connect Login app in Nextcloud:

• Open Nextcloud's configuration file config/config.php in a text editor and insert the following configuration options into the array at the end of the file:

  <?php
  $CONFIG = array (
  [...]
   
    // Configuration for nextcloud-oidc-login 
    //    Source/Documentation: https://github.com/pulsejet/nextcloud-oidc-login
    // Configuration is done in the config.php file ONLY
    'allow_user_to_change_display_name' => false,
    'lost_password_link' => 'disabled',
   
    // URL of provider. All other URLs are auto-discovered from .well-known
    'oidc_login_provider_url' => 'https://admidio.local/modules/sso/index.php/oidc',
    'oidc_login_button_text' => 'OpenID with Admidio (login_oidc)',
   
    'oidc_login_client_id' => 'https://nextcloud.local/login_oidc',
    'oidc_login_client_secret' => 'eZ9QTb7BIcGLUrKadeMQel8/dZyPiqNS',
   
    'oidc_login_logout_url' => 'https://nextcloud.local/',
    'oidc_login_end_session_redirect' => true,
    'oidc_login_hide_password_form' => false,
    'oidc_login_use_id_token' => false,
    'oidc_login_attributes' => array (
        'id' => 'sub',
        'name' => 'fullname',
        'mail' => 'email',
        'groups' => 'groups',
        'is_admin' => 'groups_admin',
    ),
    'oidc_login_scope' => 'openid profile email address phone groups custom',
    'oidc_login_disable_registration' => false,
    // 'oidc_login_redir_fallback' => true,
    'oidc_login_tls_verify' => true,
    'oidc_create_groups' => true,
    'oidc_login_webdav_enabled' => true,
    'oidc_login_password_authentication' => true,
    'oidc_login_public_key_caching_time' => 86400,
    'oidc_login_min_time_between_jwks_requests' => 10,
    'oidc_login_well_known_caching_time' => 86400,
    'oidc_login_code_challenge_method' => 'S256',
  );

The plugin supports some more settings (as described on its homepage), which you can insert as needed.

• It is now a good idea to keep a browser windows with the Admidio configuration open alongside a text editor for Nextcloud's config/config.php file, so one can easily select and copy the settings. Admidio even provides little „copy“ buttons/icons to copy the various settings to the clipboard for easy pasting into the Nextcloud configuration.
• First, return to Admidio's SSO preferences page, copy the „Discovery URL“ (ending in .well-known/openid-configuration, but remove that part when pasting!) and insert it into the configuration file with the key \'oidc_login_provider_url\':

    'oidc_login_provider_url' => 'https://admidio.local/modules/sso/index.php/oidc',

• Then go to the „Single-Sign-On Client Administration“ (the button right below the endpoint URLs and above the „Save“ button), and create a new client.

• The Admidio OpenID client settings correspond to the config file entries:
  • Choose a unique client ID (typically the URL of the nextcloud installation), paste it in both Admidio and Nextcloud, and copy the Client Secret from Admidio to nextcloud.
  • The redirect URL is https://[YOUR_NEXTCLOUD]/apps/oidc_login/oidc
  • The attribute mapping should map the 'id' to OpenID's 'sub' claim (Admidio's „User ID field“ setting).
  • Choose which scopes (i.e. groups of profile data fields) you want to transfer from Admidio to Nextcloud. 'openid' MUST be included in the Nextcloud configuration. If group support is desired, 'groups' needs to be included, similarly for 'email'. If you use custom claim names, the 'custom' scope must be included, too.
  • In Admidio you can choose which profile fields should be mapped to OpenID claims. OpenID Connect defines several dedicated claim names, but you can use any other claim name, include the 'custom' scope and map that custom claim name in Nextcloud's configuration.
  • Nextcloud's oidc_login plugin supports groups. It will use the groups provided by Admidio verbatim, so if you need particular group names, the group names mapping can be done in Admidios OpenID client configuration. Nextcloud can create new groups automatically, but that can be turned off, too.

That's it, login via OpenID Connect should now be possible with Admidio's user accounts.

Nextcloud's **Social Login** plugin is distributed together with Nextcloud with the purpose of allowing login to Nextcloud using user accounts from social networks like Google, Facebook, Twitter, GitHub, etc. However, most of these use the OpenID Connect standard (or the OAuth 2.0 standard, on which OpenID is based), so it also allows generic OpenID providers to be used as login backend for Nextcloud.

One drawback of the sociallogin plugin compared to the user_oidc and oidc_login plugins described above is that the sociallogin plugin does not reuse existing user accounts and groups, but always creates custom accounts with the prefix configured for the account. This means that it is not possible for a local account to connect an OpenID account to log in to the existing account. Other plugins also use that approach for security reasons, but they allow turning off that behavior.

• First, make sure the **Social Login** plugin is installed and enable in Nextcloud:

• After installation it can be configured by an administrator in Nextcloud's preferences in the menu item „Administration“ → „Social Login“. Next to the „Custom OpenID Connect“ header, click the „+“ link to create a new OpenID provider. The Internal name is the identifier that is used in the (Redirect) URL and must not contain special characters, spaces, etc. The Title is the human-readable name that will be displayed in the login button.
• The Authorize, Token and User Info URLs can be copied from Admidio's SSO preferences section:

• All other settings are client-specific, so we first need to create the OpenID client in Admidio.

It is now a good idea to keep two browser windows open with Admidio and Nextcloud's configuration so one can easily select and copy the settings. Admidio even provides little „copy“ buttons/icons to copy the various settings to the clipboard for easy pasting into the Nextcloud configuration.

Return to Admidio's SSO preferences page, go to the „Single-Sign-On Client Administration“ (the button right below the endpoint URLs and above the „Save“ button), and create a new client.

• The Client Name is the label of the client in Admidio's client list and on the login screen, it can be anything you like.
• The „Client ID“ and „Client Secret“ in Admidio and Nextcloud have to match exactly. The ID is typically the client's URL, although some clients allow any unique identifier. The Client Secret should a random string and will serve like a password. Admidio will create one and allow it to be copied to the client. Afterwards it is only stored as a hash in the database and not be recovered any more. However, one can create a new Client Secret in Admidio and copy that to the client's configuration.
• Enter the scopes you desire in the Nextcloud config and make sure that Admidio's config matches it. At least openid must be included (Admidio will implicitly add it). If group support is desired, the „groups“ scope must be included (and the corresponding groups claim mapped, and group support selected in the Nextcloud config).
• In Admidio, choose which field should be sent to and used by the Nextcloud Plugin to uniquely identify users. This would typically be the login name, although the user ID or UUID area also possible.
• Nextcloud will not display its Redirect URL. However, the documentation of the plugin states that the link of the login button should be used as redirect URL. Typically this will be https://[YOUR_NEXTCLOUD]/apps/sociallogin/custom_oidc/[INTERNAL_NAME].
• The social login plugin does not support transfer of profile fields from Admidio to Nextcloud, but in practice this is rarely needed, anyway.

• At the top of its configuration page, Nextcloud's social login plugin provides settings to fine-tune the login behavior, like allow auto-creation of users and groups, restricting access, and tweaking the display in the login form:

After saving the changes (both in Nextcloud and Admidio), the apps should should now be set up for single-sign-on in Nextcloud.

Admidio and Nextcloud should now be set up to use Admidio for logging in to Nextcloud. If you log out of Nextcloud and try to log in again, you will be shown the Admidio login screen and then redirected back to Nextcloud. The login buttons for each of the three possible OpenID plugins look very similar and work similar.

After successful login to Admidio, the user will be redirected back to Nextcloud and logged in.

Even though login looks idential for all three, internally, there are difference in how the login is registered.

• The user_oidc plugin registers the user as belonging to the user_oidc backend, and properly assigns the groups from Admidio.
• The oidc_login plugin also assigns the global Nextcloud groups, but registers users as „normal“ users created in Nextcloud's database rather than via OIDC. This is just an internal nuisance and should not have any effect in practice.
• However, the sociallogin plugin insists on prepending a prefix to both the username and the groups to ensure all users and groups are unique. Unfortunately this prevents users that have several backend accounts to share the Nextcloud account and log in through different providers (e.g. a Google and an Admidio account used to log in to the same Nextcloud account).