Azure AD (SAML) authentication#

This guide describes the setup of Single Sign-On (SSO) for i-doit with SAML. Mellon is used as the authenticator against Azure AD.

Preparations#

The example configuration uses a Debian 11 server with Apache, Mellon, and i-doit already installed.

Basic configuration#

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

Install packages#

1

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

An x86 64-bit system architecture should be used

Mellon Configuration#

Create a directory under /etc/apache2 for the configuration data.

1
2

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

Create the Mellon metadata with the following command (adjust the URLs to your environment):

1

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

This command creates the following files:

1
2
3

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

Create the Mellon configuration:

1

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

Insert the following directives:

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 create a self-signed certificate (the name can be chosen freely):

1

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

Example:

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 a VHost:

1

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

Example configuration:

 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>

Enable SSO login for i-doit#

Open the System settings tab in the Admin Center and adjust the configuration as follows:

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

Azure AD (SAML)#

To obtain the required XML for the Mellon configuration, perform the following steps:

Creating a custom enterprise application#

Log in to Azure AD and navigate to Enterprise applications.

Create your own custom application.

Set up SSO.

Select the method SAML and in the next step provide the file https_tu2_samlsso.synetics.test_.xml by clicking Upload metadata file.

Save the configuration.

Then download the metadata XML -- you will need it in the further process.

Adjust the assignment so that users have access to the enterprise application.

Finally, adjust the unique user identifier so that Mellon can forward the user's email address to i-doit.

To do this, open the Single sign-on section in the enterprise application administration. In the main area you will find Attributes and Claims -- edit these.

Under Required claim, edit the first displayed claim.

Change the name identifier format to Email address and the source attribute to user.mail. Then save the configuration.

The configuration of the enterprise application in Azure AD is now complete.

Enabling the configurations on the Linux server#

Provide the metadata XML#

Place the previously created metadata XML on your Linux server in the directory /etc/apache2/mellon so that Mellon can use it.

Now test the configuration and enable all required modules.

Test the configuration#

1

sudo apache2ctl configtest

Enable modules and configs#

1
2
3
4

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

The configuration of the Linux server is now complete.

If you now open the URL https://tu2-samlsso.synetics.test in your browser, you will be redirected to the Azure AD login. After successful login, you will be taken directly to your i-doit.