====== Single-Sign-On into Odoo using Admidio as a SAML 2.0 Identity Provider ======

Starting with version 5.0, Admidio can be used by other applications to authenticate users against Admidios user base. These instructions will guide you through the process of connecting Odoo 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]].

We will describe SAML login via the free [[https://apps.odoo.com/apps/modules/17.0/auth_saml|"SAML2 Authentication"]] app. Unfortunately, that app does not auto-provision users (ie. create a new user if an Admidio user successfully logs in via SAML - the users have to be manually created in Odoo and connected to a SAML username), nor does it provide group sync (i.e. using Admidio groups to grant permission in Odoo).

===== Prerequisites =====

Throughout the document we will assume you have both Admidio and Odoo already set up properly at https://admidio.local/ and https://odoo.local/. Please modify these URLs to your actual installation.
 
As a first step, one needs to **configure Admidio to act as an SAML 2.0 Identity Provider** (IdP). This has to be done once and is not specific to any client. Please follow this guide: [[en:2.0:single_sign_on|#a_basic_setup_for_admidio_as_a_saml_id_provider]]
{{ :en:2.0:sso:sso_saml_01-05_setup_admidio_preferences.png?direct&600 |}}

Basically, one (1) needs to **create a cryptographic key** to sign message and **choose a unique EntityID**.
The page preferences https://admidio.local/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.

===== Quick Overview =====

Setting up a client (SAML "Service Provider" - short SP) to use Admidio's user accounts for logging in consists of two steps. If both the IdP (Admidio in our case) and the SP (Odoo in this document) support metadata loading, the setup is very straightforward and easy. Otherwise, one has to copy URLs manually to the client, but Admidio already provides these in a single place, so this situation is not as bad, either.

  * At the **Service Provider (SP)** - Odoo in our case - **install the extension** to support SAML login.
  * Configure it either with Admidio's link to the **metadata file**, or enter the EntityID, the Single-Sign-On Endpoint, the SLO Endpoint and the public certificate manually (Admidio provides a simple table to copy these values from).
  * Choose whether sent messages **should be signed and/or encrypted** (these features require an additional private key and certificate for the SP!), and whether received messages are checked for signatures or encryption is expected. 
  * In **Admidio**, **create a new SAML client**. If the SP provides a **metadata URL**, paste it and let Admidio automatically load the configuration from the SP. One can also manually paste these settings.
    * 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 SP**, as well as the ACS URL and the SLO response URL. These values must be provided by the client.
  * In Admidio, also choose whether sent messages should be **signed or encrypted**. The crypto key generated in the general SAML setup will be used.
  * Optionally select which **profile fields should be mapped** to SAML attributes and sent to the client, and configure which **group memberships** should be transmitted.

===== Odoo-specific instructions =====

==== Configuring the Service Provider (Odoo) ====

A free SAML plugin is [[https://apps.odoo.com/apps/modules/17.0/auth_saml|SAML2 Authentication]] that provides login and user field mapping, but does not support group sync.

<div style="text-align: center;">
{{ :en:2.0:sso:sso_saml_odoo_01_install_saml_plugin.png?direct |}} </div>


After installing this app, go to "Settings" -> "Users & Companies" -> "SAML Providers" and create a new provider.

{{ :en:2.0:sso:sso_saml_odoo_02_odoo_setup_samlprovider.png?direct |}}

While the app supports IdP metadata import from Admidio, the corresponding metadata xml file is not automatically loaded, but the xml contents need to be pasted. Download the metadata xml file from the link given in Admidio's preferences (typically https://[YOUR_DOMAIN]/modules/sso/index.php/saml/metadata), open the file and copy the xml contents to Odoo's configuration:

{{ :en:2.0:sso:sso_saml_odoo_03_odoo_setup_samlprovider_metadata.png?direct |}}

Once the metadata xml is pasted, Odoo will pre-fill most settings:

{{ :en:2.0:sso:sso_saml_odoo_04_odoo_setup_samlprovider_basics.png?direct |}}

One key setting is the SP entityID, which is pre-filled as "odoo". Since the entityID should be a unique identifier (but can be freely chosen), it is recommended to use a more specific ID like the URL of your installation. The entityID will be configured in Admidio, too, and must match exactly!

Odoo also requires a private key / public certificate pair to sign messages sent to the Admidio IdP. These need to be uploaded into the Odoo SAML config as individual files in PEM format and can be generated by openssl's command line tools, by sites like https://www.samltool.com/self_signed_certs.php or in Admidio's key administration. Simply create a new Key for Odoo (RSA 2048 bits). The certificate can be copied directly from the key's edit page, but the private key is not available in Admidio's GUI for security reason. Instead, it can be downloaded (secured with a password!) from the list of keys in Admidio:

{{ :en:2.0:sso:sso_saml_02-03a_nc_saml_keysetup1.png?direct&400 |}}

After downloading the .p12 file, Applications like [[https://keystore-explorer.org/|KeyStore Explorer]] can be used to read the private key and copy the private key and the certificate in PEM format into a file and upload them into Odoo's SAML configuration. As signature algorithm choose either SHA1 or the more modern SHA256.

{{:en:2.0:sso:sso_saml_02-03b_nc_saml_keystoreexplorer1.png?direct&400|}}{{:en:2.0:sso:sso_saml_02-03c_nc_saml_keystoreexplorer2.png?direct&400|}}




Once these basic SAML settings are done, I would recommend to set up the SP in Admidio, and do the remaining settings (transmitted fields, as well as signing/encryption requirements) in parallel in Odoo and Admidio. 


If the basic settings are valid and saved, the Odoo plugin provides a link to the client (SP) metadata XML file right above the certificat upload field. Copy that URL, so it can be pasted into Admidio for auto-configuration  of the SAML access (right-click on the link and copy the link location to the clipboard).



==== Setting up the Client (SP) in Admidio ====


Now, return to Admidio's SSO preferences page, go to the "Single-Sign-On Client Administration" (the button right above the "Save" button), and create a new client.
{{ :en:2.0:sso:sso_saml_03-00_admidio_saml_preferences.png?direct&400 |}}


Paste the metadata URL copied from Odoo into the corresponding input field at the top and click "Load Client Metadata". This should load all settings from Nextcloud and pre-fill the following fields correctly. Only the Client Name needs to be entered. Choose any name to clearly identify the client in the list of SAML clients. There is no functionality depending on the name.
{{ :en:2.0:sso:sso_saml_odoo_06_admidio_client.png?direct |}}



==== Further configuration in Odoo: Fields, Security / Signing ====

The configuration of both Odoo and Admidio's SAML provides settings to want / require messages to be cryptographically signed to prevent security attacks. Choose your desired level of security, but make sure that the settings are consistent:
{{ :en:2.0:sso:sso_saml_odoo_05_odoo_setup_samlprovider_crypto.png?direct |}}

The plugin's configuration page also provides a mapping of SAML attributes to Odoo fields. Again, Admidio provides a similar mapping. Whatever information should be transferred from Admidio to Odoo should be configured. The actual SAML / IdP field name is not relevant, only the source Admidio field and the target Odoo field: 
{{ :en:2.0:sso:sso_saml_odoo_07_field_mapping.png?direct |}}


==== Setup Users and Connect them to their Admidio Username ====

Odoo's SAML app only allows connecting existing users to a SAML account from Admidio. It does not have any functionality to create new users when an unknown account successfully logs in via SAML.

This means that one has to manually create all users that should have access to Odoo first, and then assign each one their proper SAML username. Only after that, single-sign-on via Admidio is possible.

First, you have to configure Admidio to use the "Login name - usr_login_name" as the "User ID field". 
{{ :en:2.0:sso:sso_saml_odoo_11_admidio_useridfield.png?direct |}}

Create each user, and in in the "Edit user" form, switch to the "SAML" tab, where you can create a new connection to a SAML account (click "Add a line", select the Admidio IdP on the left and enter the Admidio username on the right). 

{{ :en:2.0:sso:sso_saml_odoo_10_connect_user.png?direct |}}

==== Setup completed, test Single-Sign-On ====
Admidio and Odoo should now be set up to use Admidio for logging in to Odoo. If you log out of Odoo (or open Odoo in an incognito browser window) and go to the Odoo admin location, you should see the login screen with the choice of logging in with password or via SAML.
{{ :en:2.0:sso:sso_saml_odoo_08_odoo_loginform.png?direct |}}


After choosing SAML login and loggin in with a user from Admidio, you should be logged in to Nextcloud.
{{ :en:2.0:sso:sso_saml_odoo_09_admidio_loginform.png?direct |}}



==== Caveats and Things to Consider ====

  * Odoo does NOT automatically create a new user account if a successful login from an unknown Admidio account occurs. Instead, one first has to create a new user (or connect an existing user) and connect that user with the proper Admidio user account name. In Admidio's SAML client config, you can select whether to use the numeric user ID, the login name or the email as "User ID field". Whatever you choose determines which value must be entered in Odoo's user connection field.
  * To install the SAML plugin, odoo needs the "pysaml2" library installed first. It can for example be installed from the shell with <code>php3 install pysaml2</code>
  * If odoo is behind a reverse proxy (e.g. Nginx Proxy Manager), correct proxy settings both in Odoo and the proxy itself is vital to make sure that the SAML endpoints in the metadata file and the actually called endpoints actually use https. Otherwise, login will fail without a helpful error message.
    * In `odoo.conf` set <code>proxy_mode = 1</code>
    * Make sure the reverse proxy sends all proper proxy headers, including X-FORWARDED-HOST, which is used by odoo to detect a reverse proxy setup. Nginx Proxy Manager by default does not send this header. It is also not easily possible to add this header in the "Advanced" tab of the Proxy Host in NPM. Instead, one has to add Custom Location for "/" and set the X-Forwarded-Host header there via <code>proxy_set_header X-Forwarded-Host $host;</code> You need to duplicate the forwarding host information from the main host:{{ :en:2.0:sso:sso_saml_odoo_12_npm_x-forwarded-host.png?direct&400 |}}