| |
| en:2.0:single_sign_on:oidc_mailman3 [2025/05/30 14:01] – created kainhofer | en:2.0:single_sign_on:oidc_mailman3 [2025/05/30 15:22] (current) – kainhofer |
|---|
| 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 Mailman3 to Admidio to use Admidio's login. For general instructions, and other apps, please visit the [[en:2.0:single_sign_on|general Single-Sign-On overview page]]. | 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 Mailman3 to Admidio to use Admidio's login. For general instructions, and other apps, please visit the [[en:2.0:single_sign_on|general Single-Sign-On overview page]]. |
| |
| Mailman3 provides [[https://docs.mailman3.org/en/latest/config-web.html#configure-social-login|OpenID Connect login] out of the box using the [[https://docs.allauth.org/en/latest/index.html|django-allauth library]]. | Mailman3 provides [[https://docs.mailman3.org/en/latest/config-web.html#configure-social-login|OpenID Connect login]] out of the box using the [[https://docs.allauth.org/en/latest/socialaccount/providers/openid_connect.html|django-allauth library]]. |
| |
| |
| ===== Quick Overview ===== | ===== Quick Overview ===== |
| |
| 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, Mailman3 in our case) needs to be set up with the data about the OpenID Provider (OP). One has to manually paste the Admidio endpoint URLs of the OpenID provider into the client's configuration. Admidio provides copy buttons in the preferences screen, so this 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. | Setting up a client (OpenID "Relying Party" - short RP) to use Admidio's user accounts for logging in consists of two steps: (1) The Mailman3 client (RP) needs to be set up for the OpenID Provider (OP), which can be done by providing the Discovery URL. (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: | The concrete steps are: |
| * At the **Relying Party (RP)** - Mailman3 in our case - **install the extension** to support OpenID login. | * At Mailman3 (the **Relying Party (RP)**) **install/activate the extension** to support OpenID login. |
| * Configure it with Admidio's **Discovery URL** in the settings. Auto-discovery means that the JSON file provided by Admidio will always contain the current endpoint URLs for authorization, token, userinfo, jwks, etc. Admidio already provides this information out of the box | * Configure it with Admidio's **Discovery URL** in the settings. Mailman will retrieve all required settings there. |
| * Also, choose which scopes (groups of profile fields) should be requested from Admidio ("openid" is required; Since the OpenID Mailman3 plugin does not support groups mapping, the "groups" scope is not relevant and has no use, but other profile fields might be useful. | * Also, choose which scopes (groups of profile fields) should be requested from Admidio ("openid" is required; "groups" are not supported, but other scopes like "profile" and "email" might be useful). |
| * In **Admidio**, **create a new OpenID client**. | * In **Admidio**, **create a new OpenID client**. |
| * Choose an easily understood **label for the client** (only used in Admidio's list of clients and in the login form, but has no technical use) | * Choose an **label for the client** (displayed in the login form, but no technical use) |
| * Enter the **ClientID from the RP**, Copy the created Client Secret (you will later need to paste it into the Mailman3 configuration), and enter the **Redirect URI** for the RP. The latter includes the provider_id and has the form ''https://[YOUR_MAILMAN]/accounts/[PROVIDER_ID]/login/callback/''. | * Enter the **ClientID from the RP**, copy the created Client Secret, and enter the **Redirect URI** for the RP. The latter includes the provider_id and has the form ''https://[YOUR_MAILMAN]/accounts/[PROVIDER_ID]/login/callback/''. |
| * 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 Mailman3. | * 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 Mailman3. |
| |
| |
| ===== Mailman3 Login via OpenID using the django-allauth OpenID functionality ===== | ===== Mailman3 Login via OpenID using the django-allauth OpenID functionality ===== |
| |
| |
| |
| ==== Setting up Mailman3 for OpenID login ==== | ==== Setting up Mailman3 for OpenID login ==== |
| </code> | </code> |
| |
| Also make sure the ''/opt/mailman-web/urls.py'' contains the correct routes to the allauth plugin: | Also make sure the ''/opt/mailman-web/urls.py'' contains the correct routes to the allauth plugin (usually this should already be set up): |
| <code python> | <code python> |
| urlpatterns = [ | urlpatterns = [ |
| ==== Configuring the IdP settings for the Relying Party (Mailman3) ==== | ==== Configuring the IdP settings for the Relying Party (Mailman3) ==== |
| |
| The OpenID Provider can be configured in Mailman3 either textually in the ''/opt/mailman-web/settings_local.py'' configuration file or via the graphic Django UI available at ''https://[YOUR_MAILMAN]/admin/''. Both methods are equivalent. However, Mailman currently only supports one OpenID provider at the same time. If you set up two or more providers, an error message about duplicate objects will be triggered ('MultipleObjectsReturned at /accounts/login/'). | The OpenID Provider can be configured in Mailman3 either textually in the ''/opt/mailman-web/settings_local.py'' configuration file or via the graphic Django UI available at ''https://[YOUR_MAILMAN]/admin/''. Both methods are equivalent. If you set up two (even identical) providers, an error message about duplicate objects will be triggered ('MultipleObjectsReturned at /accounts/login/'). |
| |
| To set up the OpenID provider with the admin GUI, go to the Django admin backend ''https://[YOUR_MAILMAN]/admin/'' and log in as Mailman admin. | * To set up the OpenID provider with the admin GUI, go to the Django admin backend ''https://[YOUR_MAILMAN]/admin/'' and log in as Mailman admin. |
| |
| * Go to the Accounts section and select "Social Apps", where you can add a new OpenID provider through Admidio: | * Go to the Accounts section and select "Social Apps", where you can add a new OpenID provider through Admidio (see below where the individual settings can be copied from): |
| {{ :en:2.0:sso:sso_mailman3_oidc_02_mailman_socialapp.png?direct&600 |}} | {{ :en:2.0:sso:sso_mailman3_oidc_02_mailman_socialapp.png?direct&600 |}} |
| {{ :en:2.0:sso:sso_mailman3_oidc_03_mailman_socialappsettings.png?direct&600 |}} | {{ :en:2.0:sso:sso_mailman3_oidc_03_mailman_socialappsettings.png?direct&600 |}} |
| |
| * It is now a good idea to keep two browser windows open with Admidio and Mailman3'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 Mailman3 configuration. | * It is now a good idea to keep two browser windows open with Admidio and Mailman3's configuration so one can easily select and copy the settings. |
| |
| |
| After saving the changes (both in Mailman3 and Admidio), the apps should should now be set up for single-sign-on in Mailman3. | After saving the changes (both in Mailman3 and Admidio), the apps should should now be set up for single-sign-on in Mailman3. |
| |
| ===== Setting up additional Administrator Accounts ===== | ==== Configuration in settings_local.py ==== |
| |
| OpenID Login in Mailman3 does not work for the main administrator, but only for "additional administrator acounts". They can be set up as main administrator in the "Tools & Settings" area: | Rather than the graphic setup in django's admin backend, one can also setup the OpenID provider in Mailman's ''settings_local.py''. The corresponding entry to the above example is:<code py> |
| | SOCIALACCOUNT_PROVIDERS = { |
| | "openid_connect": { |
| | "OAUTH_PKCE_ENABLED": True, |
| | "APPS": [ |
| | { |
| | "provider_id": "admidio", |
| | "name": "OpenID via Admidio", |
| | "client_id": "https://mailman.local/", |
| | "secret": "zfHdTe2nFqg4HyM/18fcyxTmpxTVk4L9", |
| | "settings": { |
| | "server_url": "https://admidio.local/modules/sso/index.php/oidc/.well-known/openid-configuration", |
| | "token_auth_method": "client_secret_post", |
| | "oauth_pkce_enabled": True, |
| | }, |
| | }, |
| | ] |
| | } |
| | } |
| | </code> |
| | In this example, the pkce and token_auth settings are optional. For a list of all available options see the [[https://docs.allauth.org/en/latest/socialaccount/providers/openid_connect.html|django-allauth documentation]]. |
| |
| {{:en:2.0:sso:sso_mailman_oidc_03_mailman_additionaladministrators.png?direct&300|}}{{:en:2.0:sso:sso_mailman_oidc_04_mailman_additionalaccounts.png?direct&600|}} | ===== Setup completed, test Single-Sign-On ===== |
| |
| The email address will be used to match logins to existing additional admin accounts. | Admidio and Mailman3 should now be set up to use Admidio for logging in to Mailman3. If you log out of Mailman3 (or open an incognito browser window) and try to log in again, you will be shown the Admidio login screen and then redirected back to Mailman3 after a successful login. |
| |
| | {{:en:2.0:sso:sso_mailman3_oidc_05_mailman_loginform.png?direct&400|}}{{:en:2.0:sso:sso_mailman3_oidc_06_admidio_loginform.png?direct&400|}} |
| |
| ===== Setup completed, test Single-Sign-On ===== | If a new account is created, one is asked to confirm the email adress. |
| | |
| Admidio and Mailman3 should now be set up to use Admidio for logging in to Mailman3. If you log out of Mailman3 and try to log in again, you will be shown the Admidio login screen and then redirected back to Mailman3 after a successful login. | |
| |
| {{:en:2.0:sso:sso_mailman_oidc_05_mailman_loginform.png?direct&600|}}{{:en:2.0:sso:sso_mailman_oidc_06_admidio_loginform.png?direct&600|}} | On a successfull login, the connection to the OpenID account will be stored in the user profile. For existing Mailman users, one can connect the mailman account with an OpenID account in the profile, too: |
| |
| {{ :en:2.0:sso:sso_mailman_oidc_07_mailman_loginsuccess.png?direct&600 |}} | {{:en:2.0:sso:sso_mailman3_oidc_07_mailman_profile.png?direct&400|}} |
| |
| |
