Skip to content

ADFS (Active Directory) (SAML and Mellon)#

In this tutorial, we describe how to set up single sign-on (SSO) for i-doit using SAML. In this example, we use Mellon as an authenticator against LDAP-AD-FS.

Preparations#

We use two servers for the sample configuration, a Windows server with domain/AD and FS and a Debian 11 server with Apache and Mellon:

FQDN IP Rolle 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

The system architecture should be x86 in 64bit.

Mellon Konfiguration#

We are creating a directory for this under /etc/apache2 and store our configuration data here.

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

With the following command we create our Mellon metadata "Please adjust URLs"

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

This now creates the following files

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

Now we need to fetch the AD-FS metadata from our AD "Please adjust URLs"

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 we need to create our Mellon configuration.

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

Insert the following configuration directives 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/FederationMetadata.xml
    MellonEndpointPath /mellon
    MellonEnable "info"
</Location>

Apache2 Konfiguration#

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

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

1
sudo nano /etc/apache2/sites-available/mywebserver.con

Example:

 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 directory protected via Mellon is protected under /var/www/html. So we can create another VHost config later to install e.g. i-doit.

Creating the directory:

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

Create an example html to test the call later on:

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 configuration:

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

Synchronize time:

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

At this point, we are done with the configuration of the Linux server for the time being and can now turn our attention to our AD.

Konfiguration AD-FS#

First download the file mellon_metadata.xml from the Linux server e.g. via WinSCP and save it.

Add Relying Party Trust

Claims aware remains active and then on Start

Welcome

In the next step we select "import data ...." and navigate to our previously saved XML

Select data source

The following note can be ignored if it appears.

AD FS Management

Now we enter the FQDN from our Linux server.

Specify display name

In the next step we can control accesses, for the sake of simplicity we leave it at Permit everyone for now.

Choose access control policy

We can also disregard the next window and just click next.

Ready to add trust

Finally only Close and the Party Trust is created

Finish

Now we need to define Claim Issuance Policies so that our user can also log in via mail.

AD FS edit claim

Now a window opens and we click on Add Rule.

Add rule

Now we select Send LDAP Attributes as Claim and click Next

Choose rule type

We give the rule a unique name and add the mapping as shown.

Configure claim rule

Then we create another rule and select Transform an Incoming Claim

Select rule template

Please configure as follows:

Configure rule

Now we have a fully configured Relying Party Trust and can test the authentication once.

Login page

Test SAML-SSO#

Open the URL from the server once in the browser Example: https://mywebserver.example.com/protected

After successful registration, we should receive the following output.

Auth users only

Installation i-doit#

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

SSO login for i-doit#

For this we have to go to the Administration -> System settings and adjust the configuration as follows. Important information about contacts: It is mandatory that the e-mail address of the respective user is stored as login in i-doit!

i-doit SSO setting

Since we currently followed our instructions or KB, we need to adjust the VHost configuration so that we can now log in via SSO

Disable i-doit Vhost

1
sudo a2dissite i-doit

Customize Mellon Vhost 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>

Finally restart Apache once

1
sudo systemctl restart apache2.service

Finished!

If we now open the URL again in our browser and log in, we will be taken directly to the i-doit

Fallback to Logon Screen

If a user logs in who does not yet exist in i-doit, then this user is automatically redirected to the i-doit login screen and can log in with a local user.