Azure AD (SAML) authentication#

In this guide, we describe how to set up single sign-on (SSO) for i-doit using SAML. We will be using Mellon as an authenticator versus Azure AD via SAML ..

Preparations#

We use for the example configuration a Debian 11 server with Apache, Mellon and installed i-doit.

Basic configuration#

✔ This guide assumes that your Azure Active Directory has already been configured properly.
✔ i-doit is already pre-installed and usable.

Install packages#

1

sudo apt -y install openssl libapache2-mod-auth-mellon ntpdate

The system architecture should be x86 in 64bit.

Mellon configuration#

For this we create a directory under /etc/apache2 and put our configuration file here.

1
2

sudo mkdir -p /etc/apache2/mellon
cd /etc/apache2/mellon

With the following command we create our Mellon metadata "Customize URLs to your needs".

1

/usr/sbin/mellon_create_metadata https://tu2-samlsso.synetics.test/ "https://tu2-samlsso.synetics.test/mellon"

The command now the following files:

1
2
3

https_tu2_samlsso.synetics.test_.cert
https_tu2_samlsso.synetics.test_.key
https_tu2_samlsso.synetics.test_.xml

Now we have to create our Mellon configuration.

1

sudo nano /etc/apache2/conf-available/mellon.conf

The following directives are inserted based on the example:

1
2
3
4
5
6
7
8

<Location / >
    MellonSPPrivateKeyFile /etc/apache2/mellon/https_tu2_samlsso.synetics.test_.key
    MellonSPCertFile /etc/apache2/mellon/https_tu2_samlsso.synetics.test_.cert
    MellonSPMetadataFile /etc/apache2/mellon/https_tu2_samlsso.synetics.test_.xml
    MellonIdPMetadataFile /etc/apache2/mellon/AzureAD_metadata.xml
    MellonEndpointPath /mellon
    MellonEnable "info"
</Location>

Apache2 configuration#

First we create a self signed certificate "name can be individual".

1

openssl req -newkey rsa:3072 -new -x509 -days 3652 -nodes -out /etc/ssl/certs/mywebserver.pem -keyout /etc/ssl/private/mywebserver.key

Beispiel:

1
2
3
4
5
6
7

Country Name (2 letter code) [AU]:Your_Country
State or Province Name (full name) [Some-State]:Your_Province
Locality Name (eg, city) []:Your_City
Organization Name (eg, company) [Internet Widgits Pty Ltd]:Your_Organization
Organizational Unit Name (eg, section) []:Your Department
Common Name (e.g. server FQDN or YOUR name) []:mywebserver.example.com
Email Address []:your_email_address

Create VHost:

1

sudo nano /etc/apache2/sites-available/mywebserver.conf

Example:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

<IfModule mod_ssl.c>
    <VirtualHost _default_:443>
        DocumentRoot /var/www/html/i-doit
        <Directory /var/www/html/i-doit/>
                AllowOverride All
        </Directory>
        ServerSignature Off
        ErrorLog /var/log/apache2/error.log
        CustomLog /var/log/apache2/access.log combined
        LogLevel info ssl:warn
        SSLEngine on
        SSLCertificateFile /etc/ssl/certs/mywebserver.pem
        SSLCertificateKeyFile /etc/ssl/private/mywebserver.key
    </VirtualHost>
    <Location />
        Require valid-user
        AuthType "Mellon"
        MellonEnable "auth"
        MellonDecoder "none"
        MellonVariable "cookie"
        MellonSecureCookie On
        MellonUser "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name"
    </Location>
</IfModule>

Activate i-doit SSO#

Now we have to go to administration -> system settings and adjust the configuration as follows.

As long as the configurations on the Linux server have not been activated yet, users can still log in with the i-doit login mask and a local user.

Azure AD (SAML)#

In order to get the required XML for the Mellon configuration we have to do the following steps (example):

Create a enterprise application#

We log into Azure AD and then go to enterprise applications.

Create your own enterprise application.

Set up SSO.

Now we select the SAML method and in the next step we provide our https_tu2_samlsso.synetics.test_.xml by clicking the button upload metadata file.

Now we save the configuration.

Afterwards we download the metadata XML because it will be needed later on.

In order for the users to gain access to the enterprise application, the assignment must be adjusted.

Lastly, we need to customize the unique user identifier so that Mellon can forward the user's email address to i-doit.

To do this, we open the Single sign-on item in the administration of the enterprise application. Then we see in the main area 'Attributes and claims' and we edit them.

Now we edit under Successful claim the first claim that is displayed.

The name identifier format must be changed to email address mandatory. The source attribute must be changed to user.mail.. Then we save the configuration.

At this point, we are done configuring our enterprise application in Azure AD.

Activation of the configurations on the Linux server#

Provide metadata XML#

The previously created metadata XML must now be made available on our Linux server in the directory /etc/apache2/mellon so that Mellon can use it..

Now that we have created all the configurations so far, we can test them and activate all the necessary mods.

Test config#

1

sudo apache2ctl configtest

Activate mods and configs#

1
2
3
4

sudo a2enmod ssl
sudo a2enconf mellon.conf
sudo a2ensite mywebserver.conf
sudo systemctl restart apache2

At this point we are done with the configuration of our Linux server.

If we now open the URL again in our browser https://tu2-samlsso.synetics.test we will be redirected to the Azure AD login. After successful login we are redirected back to our i-doit and are successfully logged in.