MetaMan

MetaMan (short for Metadata Manager) is Laravel-based web application intended for managing and storing SAML metadata for identity federations within Git version control system.

Requirements

This application is written in Laravel 10 and uses PHP Enumerations thus it requires PHP version 8.1.0 or newer.

Authentication is expected to be managed by locally running Shibboleth Service Provider, so Apache web server is highly recommended as there is an official Shibboleth module for it. There is also an unofficial Shibboleth SP module for nginx web server, however, it has not been tested and so it is not recommended.

• PHP 8.1.0+
• Shibboleth SP 3.x
• Apache 2.4
• Supervisor 4.1

The above mentioned requirements can be easily achieved by using Ubuntu 22.04 LTS (Jammy Jellyfish). For those running older Ubuntu or Debian, Ondřej Surý's PPA repository might be very appreciated.

Setup

In order for the Envoy script to be really useful and do what it is designed for, you must setup Apache, PHP, Shibboleth SP and Supervisor at the destination host first.

(To prepare a server for MetaMan, I am using an Ansible playbook that is currently not publicly available due to being part of our larger and internal mechanism, but I am willing to share it and most probably will do that in the future.)

Apache

Install Apache using apt.

apt install apache2

Then get a TLS certificate. If you would like to avoid paying to a Certificate Authority, use Certbot to get a certificate from Let's Encrypt for free. Then configure Apache securely according to Mozilla SSL Configuration Generator using the following stub.

<VirtualHost *:80>
    ServerName      server.example.org
    Redirect        permanent / https://server.example.org
</VirtualHost>

<VirtualHost _default_:443>
    ServerName      server.example.org
    DocumentRoot    /home/web/metaman/current/public/

    # TLS settings

    <Directory /home/web/metaman/current/public>
        AllowOverride All
    </Directory>

    <Location />
        AuthType shibboleth
        ShibRequestSetting requireSession 0
        <RequireAll>
            Require shibboleth
        </RequireAll>
    </Location>

    <Location /Shibboleth.sso>
        SetHandler shib
    </Location>
</VirtualHost>

It is also highly recommended to allow web user (the user defined in config file in the TARGET_USER variable, i.e. the one under which MetaMan application is saved in /home directory) to reload and restart PHP-FPM. It helps with minimizing outage during deployment of a new version. Edit /etc/sudoers.d/web accordingly:

web ALL=(ALL) NOPASSWD:/bin/systemctl reload php8.1-fpm,/bin/systemctl restart php8.1-fpm

PHP

PHP 8.1 is present as an official package in recommended Ubuntu 22.04 LTS (Jammy Jellyfish).

apt install php-fpm

Then follow information in your terminal.

a2enmod proxy_fcgi setenvif
a2enconf php8.1-fpm
systemctl restart apache2

(In case you still run on older Ubuntu version or Debian distribution with not so current PHP version, you might find Ondřej Surý's repository highly useful.)

Shibboleth SP

Install and configure Shibboleth SP.

apt install libapache2-mod-shib

There is a documentation (in Czech language, though) available at eduID.cz federation web page.

You should add AttributeChecker (MetaMan requires uniqueId, mail and cn attributes) and AttributeExtractor (to obtain useful information from federation metadata).

<ApplicationDefaults entityID="https://server.example.org/shibboleth"
    REMOTE_USER="uniqueId"
    sessionHook="/Shibboleth.sso/AttrChecker"
    metadataAttributePrefix="Meta-"
    cipherSuites="DEFAULT:!EXP:!LOW:!aNULL:!eNULL:!DES:!IDEA:!SEED:!RC4:!3DES:!kRSA:!SSLv2:!SSLv3:!TLSv1:!TLSv1.1">

    <Sessions lifetime="28800" timeout="3600" relayState="ss:mem"
        checkAddress="false" handlerSSL="true" cookieProps="https"
        redirectLimit="exact">

        <!-- Attribute Checker -->
        <Handler type="AttributeChecker" Location="/AttrChecker" template="attrChecker.html"
            attributes="uniqueId mail cn" flushSession="true"/>

    </Sessions>

    <!-- Extract information from SAML metadata -->
    <AttributeExtractor type="Metadata" DisplayName="displayName"
        InformationURL="informationURL" OrganizationURL="organizationURL">
        <ContactPerson id="Technical-Contact" contactType="technical" formatter="$EmailAddress"/>
    </AttributeExtractor>

</ApplicationDefaults>

Then tweak attrChecker.html, localLogout.html and metadataError.html so users are informed properly when any issue occurs. If you need any help, check GÉANT's documentation regarding attribute checking.

Supervisor

Supervisor is a process monitor for the Linux operating system and helps you with queuing jobs to background processes. The setup is fairly easy and documented by Laravel.

Install supervisor.

apt install supervisor

Prepare configuration file for your worker.

[program:laravel-worker]
process_name=%(program_name)s_%(process_num)02d
command=php /home/web/metaman/current/artisan queue:work
autostart=true
autorestart=true
user=www-data
numprocs=1
redirect_stderr=true
stdout_logfile=/home/web/laravel-worker.log
stopwaitsecs=3600

Reread configuration and start the process.

supervisorctl reread
supervisorctl update
supervisorctl start laravel-worker:*

Installation

The easiest way to install MetaMan is to use Laravel Envoy script that is included in this repository.

Laravel Envoy is currently available only for macOS and Linux operating systems. However, on Windows you can use Windows Subsystem for Linux. Of course, you can also use a virtualized Linux system inside, for example, a VirtualBox machine.

The destination host should be running Ubuntu 22.04 LTS (Jammy Jellyfish) with PHP 8.1. If that is not the case, take care and tweak PHP-FPM service in Envoy.blade.php and in Apache configuration accordingly.

Clone this repository:

git clone https://github.com/CESNET/metaman

Install PHP dependencies:

composer install

Prepare a configuration file for your deployment using envoy.example template.

cp envoy.example envoy

Tweaking envoy file to your needs should be easy as all the variables within the file are self explanatory. Then just run the deploy task.

./vendor/bin/envoy run deploy

Tasks

There are three different tasks available — deploy, rollback and cleanup.

deploy

The deploy task simply deploys the current MetaMan version available at GitHub into timestamped directory and makes a symbolic link current. This helps you with rolling back to the previous version.

./vendor/bin/envoy run deploy

rollback

The rollback task is there to help you roll back to the previous version if there is an issue with the current one. It just finds the previous timestamped directory and changes current symbolic link to that directory.

./vendor/bin/envoy run rollback

In case you would like to go back even further, just ssh into your web server and create a symbolic link to any version you have still available there.

cleanup

The cleanup task helps you keeping your destination directory clean by leaving only three latest versions (i.e. timestamped directories) available and deletes all the older versions.

./vendor/bin/envoy run cleanup

Why no stories?

Laravel Envoy allows to use "stories" to help with grouping a set of tasks. Eventually, it makes the whole script much more readable as well as reusable.

There is one downside with stories, though. If your SSH agent requests confirming every use of your key (a highly recommended best practice!), you must confirm the key usage for every single Envoy story. I find it very annoying so therefore I have decided not to use stories after all.