Skip to content

ADFS (Active Directory) (SAML)#

Please create a complete backup before making any changes to an interface/import. If the result is not satisfactory, the backup can then be restored

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

Preparations#

The example configuration uses two servers -- a Windows Server with domain/AD and FS, and a Debian 11 server with Apache and Mellon:

FQDN IP Role OS
tu2-dc2.tu-synetics.test 10.10.60.22 AD, FS Windows
tu2-samlsso.synetics.test 10.10.60.108 Apache+Mellon Debian11

Basic configuration#

✔ The Windows server must have a configured AD that includes the AD-FS role.
✔ 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:

https\_tu2\_samlsso.synetics.test\_.cert
https\_tu2\_samlsso.synetics.test\_.key
https\_tu2\_samlsso.synetics.test\_.xml

Retrieve the AD FS metadata from your AD (adjust the URL):

1
wget https://tu2-dc2.tu-synetics.test/FederationMetadata/2007-06/FederationMetadata.xml%20-O%20/etc/apache2/mellon/FederationMetadata.xml -O /etc/apache2/mellon/FederationMetadata.xml --no-check-certificate

Now 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/FederationMetadata.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
<IfModule mod_ssl.c>
    <VirtualHost _default_:443>
        DocumentRoot /var/www/html
        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 /protected>
        Require valid-user
        AuthType "Mellon"
        MellonEnable "auth"
        MellonDecoder "none"
        MellonVariable "cookie"
        MellonSecureCookie On
    </Location>
</IfModule>

In this example, only the subdirectory /protected under /var/www/html is protected via Mellon. You can later create an additional VHost configuration to include e.g. i-doit.

Create the directory:

1
sudo mkdir -p /var/www/html/protected

Create an example HTML file to test the access later:

1
sudo nano /var/www/html/protected/index.html

Example:

1
2
3
4
5
6
7
8
<html>
    <head>
        <title>Index Page</title>
    </head>
    <body>
        <h2>This simple index page will only be accessible once your users successfully sign-in via Azure AD with their valid credentials!</h2>
    </body>
</html>

Test the configuration:

1
sudo apache2ctl configtest

Enable the required modules and configs:

1
2
3
4
sudo a2enmod ssl
sudo a2enconf mellon.conf
sudo a2ensite mywebserver.conf
sudo systemctl restart apache2

Synchronize the system time:

1
sudo ntpdate -u tu2-dc2.tu-synetics.test

The configuration of the Linux server is now complete for the time being. In the next step you will set up AD FS.

AD FS Configuration#

First download the mellon_metadata.xml from the Linux server (e.g. via WinSCP). Then open the AD FS Management and create a new Relying Party Trust:

Add Relying Party Trust

Leave Claims aware active and click Start.

Welcome

In the next step, select Import data from a file and navigate to the previously saved XML file.

Select data source

The following notice can be ignored if it appears.

AD FS Management

Enter the FQDN of your Linux server.

Specify display name

In the next step you can configure access control. To start, leave the setting at Permit everyone.

Choose access control policy

You can skip the next window -- click Next.

Ready to add trust

Click Close -- the Relying Party Trust is now created.

Finish

Now define the Claim Issuance Policies so that users can log in via email.

AD FS edit claim

A window opens -- click Add Rule.

Add rule

Select Send LDAP Attributes as Claim and click Next.

Choose rule type

Give the rule a unique name and add the mapping as shown.

Configure claim rule

Create an additional rule and select Transform an Incoming Claim.

Select rule template

Apply the configuration as follows:

Configure rule

The Relying Party Trust is now fully configured. Test the authentication:

Login page

Test SAML-SSO#

Open the URL of the server in your browser: https://mywebserver.example.com/protected

After successful login you should see the following output:

Auth users only

Install i-doit#

The installation can be performed as described in the KB article for Debian.

Enable SSO login for i-doit#

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

Important information about contacts

The email address of the respective user must be stored as the login in i-doit!

i-doit SSO setting

Adjust the VHost configuration so that SSO login works.

Disable the i-doit VHost configuration:

1
sudo a2dissite i-doit

Adjust the Mellon VHost configuration created at the beginning:

1
nano /etc/apache2/sites-enabled/tu2-samlsso.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
25
26
<IfModule mod_ssl.c>
    <VirtualHost _default_:443>
    ServerAdmin admin@example.com
    DocumentRoot /var/www/html
            <Directory /var/www/html/>
                    AllowOverride All
            </Directory>
    ServerName  fqdn.example.com
    ServerSignature Off
    ErrorLog ${APACHE_LOG_DIR}/error.log
    CustomLog ${APACHE_LOG_DIR}/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
    </Location>
</IfModule>

Restart Apache:

1
sudo systemctl restart apache2.service

The setup is complete. If you now open the URL in your browser and log in, you will be taken directly to i-doit.

Fallback to login form

If a user logs in who does not yet exist in i-doit, they will automatically be redirected to the i-doit login form and can log in with a local user.