Single-Sign-On into Joomla 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 Joomla to Admidio to use Admidio's login. For general instructions, and other apps, please visit the general Single-Sign-On overview page.

Throughout the document we will assume you have both Admidio and Joomla already set up properly at https://admidio.local/ and https://joomla.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 Joomla. Please follow this guide: #a_basic_setup_for_admidio_as_an_oidc_id_provider

Basically, one (1) needs to create a cryptographic key to sign message and choose a unique EntityID. The page https://admidio.local/adm_program/modules/preferences.php?panel=sso also provides the link to the metadata xml, and the individual settings in case a client does not support auto-configuration via metadata.

Setting up a client (OpenID “Relying Party” - short RP) to use Admidio's user accounts for logging in consists of two steps: (1) The client (RP, Joomla in our case) needs to be set up with the data about the OpenID Provider (OP). Typically this is done via the metadata provided in the discovery URL of the provider. 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 straigtforward. (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) - Joomla 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 indo Joomla's configuration), and enter the Redirect URI for the RP. Typically the latter can be found either on the RP's configuration page or in the documentation.
• Optionally select (both in Admidio and the RP) which profile fields should be mapped to OpenID claims (attributes) and sent to the client, and configure which group memberships should be transmitted.

OpenID Connect login in Joomla is provided by the miniOrange OAuth Client extension. Simply install it in Joomla's extension manager from the Joomla Extension Directory.

This plugin is available as a (very stripped-down) free version and an (expensive) paid version that supports all OpenID Connect features. The free version only allows login to Joomla through Admidio. Features missing from the free version are: (1) automati creation of new users, (2) automatic plugin configuration from the discovery URL, (3) group mapping for permissions in Joomla, (4) attribute/field mapping for profile data, (5) single-log out from all other apps connected through OpenID with Admidio, (6) login to the administration backend with OpenID.

Configure the plugin in Joomla's Administration area in the menu section “Components” → “miniOrange OAuth Client” → “Configure OAuth”.

• First, create a new connection to Admidio via the “Custom Application” button:
• Select https for the redirect URL and copy the URL (we will paste it into Admidio's configuration):
• For step 2, return to Admidio's SSO preferences and copy the URLs for the Authorization and Token endpoints from Admidio to Joomla's plugin conf.
• The other fields in step 2 will be filled after a new OpenID client is created in Admidio in the next section.

It is now a good idea to keep two browser windows open 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 Joomla's 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, it can be anything you like. It will be shown to the users in the headline of the login form.
• The “Client ID” is used to uniquely identify the Joomla installation when a login request is received by Admidio. In principle, it can be any unique identifier, but it is customary to use the base URL of the installation. Just make sure that exactly the same Client ID is used in Joomla and Admidio (even trailing slashes have to match exactly!).
• 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 not be recovered any more. However, one can create a new Client Secret in Admidio and copy that to the client's configuration.
• The “Redirect URL” in Admidio's config should be the Redirect / Callback URL of Step 1 of the Joomla configuration (typically https://[YOUR_INSTALLATION])
• Enter the scopes you desire in Joomla's config and make sure that Admidio's config matches them. At least openid must be included (Admidio will implicitly add it). As the free plugin does not support advanced fields mapping or group mappin, only the “email” and “profile” scopes are relevant and should be selected (otherwise the email and username will not be sent to Joomla).

After saving the settings both in Admidio and Joomla, the Joomla plugin is ready for a test run and the final touches of the configuration:

• First, you MUST test the configuration. This will redirect you to a login form in Admidio, and after a successful login back to Joomla, where the data provided by Admidio will be displayed together with a success message. If anything was wrongly configured, a corresponding error message will be triggered.

• Once this initial connection test is successful, the last setting is the mapping of the email and username in the lower half of the form of Step 3 in Joomla.

After saving, the configuration of the OpenID plugin is finished.

Although the plugin configuration is finished, the plugin does not automatically replace Joomla's login form with the OpenID login link, which is shown in Step 4. Rather, one has to create a custom Joomla module or menu item that uses the provided login link as target.

• Either create a new custom module (“Content” → “Site Modules” → “+ New” → “Custom Module”) and create a link with the URL shown in Step 4.

• Alternatively, you can also insert a new menu item with item type “System Links” → “URL”. Let this menu item again point to the Login URL shown in Step 4

You should now have login links on your page.

Admidio and Joomla should now be set up to use Admidio for logging in to Joomla. The normal Joomla login form will still be shown and does NOT redirect to Admidio for login. Rather, it can be used for login with local Joomla accounts, which still can exist in addition to OpenID (or SAML) SSO.

If you log out of Joomla and try to log in again, you will be shown the Admidio login screen and then redirected back to Joomla.

• The free version of the miniOrange plugin is very limited, allowing only login for existing joomla users (with their Admidio passwords at the admidio site). Each user must first be created manually in Joomla!
• The free version also does not allow transferring any group information from Admidio to Joomla, or other profile fields.
• Currently, there are no full-featured, free Single-Sign-On solutions for Joomla that support field and group mapping for permissions in Joomla. The miniOrange plugins we described here provide only basic SSO functionality, while the useful features are available only in the paid versions. Given the high costs of these versions and considering the tight budget most non-profit associations face, the paid version is usually way to expensive to even consider…