====== SAML Single Sign-On with Pandora FMS ======

{{indexmenu_n>12}}

**SAML** is an open standard for authentication and authorization based on XML. **Pandora FMS** can function as a service provider with its internal SAML identity provider.

<WRAP center round important 90%>

Administrators always authenticate against the local database.

</WRAP>

Several steps need to be completed before you can use SAML in Pandora FMS.

1. Have a [[#ks1|SAML server]] running.
2. [[#ks2|Configure the settings in Pandora FMS]].
3. If planning to use [[#ks3|Azure with SAML]], configure that server.

<wrap #ks1 />
===== Installing SimpleSAMLphp 2.0 =====

Download SimpleSAMLphp version 2.3.2 from its official repository:

<WRAP center round download 90%>

https://github.com/simplesamlphp/simplesamlphp/releases/tag/v2.3.2

</WRAP>

Then, upload it to the **Pandora FMS server**. If the PFMS server has internet access and **wget** is installed, you can use the following command in a directory with sufficient space and write permissions:

<code bash>
wget https://github.com/simplesamlphp/simplesamlphp/releases/download/v2.3.2/simplesamlphp-2.3.2-full.tar.gz
</code>

Extract the downloaded file with:

<code bash>
tar -xvf simplesamlphp-2.3.2-full.tar.gz
</code>

Move the folder to its final location:

<code bash>
mv simplesamlphp-2.3.2 /opt/simplesamlphp
</code>

To share access with Pandora FMS, create the following symbolic link:

<code bash>
ln -s /opt/simplesamlphp/public /var/www/html/simplesamlphp
</code>

**SimpleSAMLphp** relies on the ''config.php'' file for its configuration. With the final location set above, rename the default template:

<code bash>
mv /opt/simplesamlphp/config/config.php.dist /opt/simplesamlphp/config/config.php
</code>

Thus, you will have the full path of the configuration file as:

<file>
/opt/simplesamlphp/config/config.php
</file>

Use your favorite text editor to modify the following values (note that you should replace ''pandora.local'' with the PFMS web console URL and keep the comma at the end of the line as part of instruction blocks):

<code | /opt/simplesamlphp/config/config.php>
'baseurlpath' => 'https://pandora.local/simplesamlphp/',
'auth.adminpassword' => '123pandora',
</code>

<WRAP center round info 90%>
\\
  * Note that you must replace ''pandora.local'' with the PFMS web console URL and keep the comma at the end of the line as part of instruction blocks.
  * Always use a URL instead of an IP address. Following the case of using ''pandora.local'', this "//URL//" should be added to the ''/etc/hosts'' file of the operating system (note: for educational purposes only).
\\
</WRAP>

Save the changes to the file and exit to the command line.

<WRAP center round important 90%>

If any permission errors occur due to cache, apply the following:

<code bash>
mkdir /var/cache/simplesamlphp && chown apache:apache /var/cache/simplesamlphp
</code>

\\

</WRAP>

This will get **SimpleSAMLphp** up and running and should display the home page at the URL ''<nowiki>https://pandora.local/simplesamlphp/</nowiki>'' (replace ''pandora.local'' with the PFMS web console URL).

<WRAP center round info 90%>

If connecting via HTTP instead of HTTPS, authentication will fail until the Apache web server is configured to listen on the secure port ''443''.

</WRAP>

{{ wiki:pfms-saml-image_28.png  }}

To access **SimpleSAMLphp** administration, first rename the ''authsources.php.dist'' file:

<code bash>
mv /opt/simplesamlphp/config/authsources.php.dist /opt/simplesamlphp/config/authsources.php
</code>

Copy the contents of the XML downloaded earlier, paste it, and process it; this will generate a PHP configuration text which should be copied **and added** into the ''/opt/simplesamlphp/metadata/saml20-idp-remote.php'' file. Then save these additions and exit the file editing.

You can access the admin interface via the URL ''<nowiki>https://pandora.local/simplesamlphp/admin/</nowiki>'' (replace ''pandora.local'' with the PFMS web console URL):

{{ wiki:pfms-saml-image_30.png  }}

<wrap #ks2 />
===== Configuring Pandora FMS with SAML =====

Menu <wrap :en>**Management → Setup → Setup → Authentication**</wrap>.

The following values are common:

{{ :wiki:pfms-saml-image_70.png  }}

Some notable fields:

  * **SAML Group Name Attribute**: SAML field where the group name is found (while auto-creating remote users is enabled).
  * **SimpleSAML Path**: Directory where the ''simplesamlphp'' folder is located.
  * **Source SAML**: Name of ''authsource'', e.g., ''example-userpass''.
  * **SAML Email Attribute**: SAML field where the user's email is found (while auto-creating remote users is enabled).

<WRAP center round info 90%>

Before configuring any third-party service with SAML, it is recommended to [[:en:documentation:pandorafms:technical_annexes:45_simplesaml_2_local|test and verify locally]] the installed **SimpleSAMLphp**.

</WRAP>

<wrap #ks3 />
===== Configuring Azure with SAML =====

In Azure® services, go to the **Extra ID** section:

{{ wiki:pfms-saml-image_40.png  }}

Then go to **Enterprise Applications**:

{{ wiki:pfms-saml-image_42.png  }}

Create a new application (or use an existing one):

{{ wiki:pfms-saml-image_44.png  }}

Go to Single Sign-On:

{{ wiki:pfms-saml-image_46.png  }}

Edit the basic SAML configuration:

{{ wiki:pfms-saml-image_48.png  }}

Fill in the following fields with the application ID, the address of the installed **SimpleSAMLphp** (replace ''pandora.local'' with the PFMS web console URL), and the address to which Azure® should redirect after the session is closed:

{{ wiki:pfms-saml-image_50.png  }}

Download the XML metadata file which will be used later:

{{ wiki:pfms-saml-image_52.png  }}

Finally, save the ID from the previous step and the URL of the extra identifier:

{{ wiki:pfms-saml-image_54.png  }}

<wrap #ks3_1 />
==== Configuration in SimpleSAMLphp ====

Edit the ''/opt/simplesamlphp/config/authsources.php'' file with the following values:

{{ wiki:pfms-saml-image_56.png  }}

Then, go to the SimpleSAMLphp website, under the **Federation** menu, and then to the **Tools** section for XML to PHP conversion:

{{ wiki:pfms-saml-image_58.png  }}

Rename ''saml20-idp-remote.php.dist'' to:

<code bash>
mv /opt/simplesamlphp/metadata/saml20-idp-remote.php.dist /opt/simplesamlphp/metadata/saml20-idp-remote.php
</code>

Copy the content of the previously downloaded XML, paste it, and process it; this will generate a PHP configuration text which should be copied and pasted into the ''/opt/simplesamlphp/config/authsources.php'' file **replacing all its content**.

If everything is correct, proceed to test:

{{ wiki:pfms-saml-image_60.png  }}

Obtaining the following result:

{{ wiki:pfms-saml-image_62.png  }}

The email and user identifier can be extracted from the attributes returned by Azure® during the previous test:

{{ :wiki:pfms-saml-image_80.png  }}

{{ :wiki:pfms-saml-image_90.png  }}
 
For advanced configuration, you can deepen the //mapping// of properties or select a default one if no match is found:

{{ :wiki:pfms-saml-image_100.png  }}

[[:en:documentation:start|Back to the Pandora FMS documentation index]]