EMX Local SSO Setup | Documentation

EMX utilizes the SimpleSAMLphp library to enable single-sign-on. This requires a few modifications to support. The following commands should be ran as root.

1. Update the apache configuration

Edit the apache site conf file. For debian linux, this is located at /etc/apache2/sites-available/emx.conf. For redhat and centOS, this file is located at /etc/httpd/sites-available/emx.conf

Below the line:

DocumentRoot "/var/www"

Add the following:

 SetEnv SIMPLESAMLPHP_CONFIG_DIR /var/www/v3/app/config/saml-config
 Alias /simplesaml /var/www/vendor/simplesamlphp/simplesamlphp/public

Next, below the line:

</Directory>

Add the following:

<DirectoryMatch "/var/www/vendor/simplesamlphp/simplesamlphp/public">
    DirectoryIndex index.php
    Require all granted
    RewriteEngine Off
</DirectoryMatch>

Finally, run service apache2 restart if on debian, or service httpd restart if otherwise.

2. Create SimpleSAMLphp configuration files

Create configuration directory:

mkdir /var/www/v3/app/config/saml-config

Setup cache directory. If using redhat/centOS, replace www-data below with apache:

mkdir -p /var/cache/simplesamlphp/admin
chown -R www-data:www-data /var/cache/simplesamlphp
chmod -R 775 /var/cache/simplesamlphp

Create authsources.php file, replace “YOUR HOST NAME” with the hostname of your local EMX, use https if you are using SSL:

cat <<'EOT' >> /var/www/v3/app/config/saml-config/authsources.php
<?php

$config = [

    // This is a authentication source which handles admin authentication.
    'admin' => [
        'core:AdminPassword',
    ],

    // An authentication source which can authenticate against SAML 2.0 IdPs.
    'default-sp' => [
        'saml:SP',

        // The entity ID of this SP.
        'entityID' => 'http://YOUR HOST NAME',

        'NameIDPolicy' => [
            'Format'      => 'urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress',
            'AllowCreate' => false,
        ],

        'authproc' => [
            20 => [
                'class' => 'saml:NameIDAttribute',
                'attribute' => 'email',
                'format'    => '%V'
            ]
        ]
    ]
];
EOT

Optional: enable certificate for service provider

mkdir /var/www/v3/app/config/saml-config/cert
cd /var/www/v3/app/config/saml-config/cert
openssl req -newkey rsa:3072 -new -x509 -days 3652 -nodes -out saml.crt -keyout saml.pem

Add references to generated certs to authsources.php:

Before:

'NameIDPolicy' => [

Add:

'privatekey' => 'saml.pem',
'certificate' => 'saml.crt',

Create config.php

Create config.php by copying reference:

cp /var/www/vendor/simplesamlphp/simplesamlphp/config/config.php.dist /var/www/v3/app/config/saml-config/config.php

Modify the config.php file, find and adjust the following property (use https if you are using ssl):

'baseurlpath' => 'http://YOUR HOST NAME/simplesaml/'

Find and adjust metadatadir:

'metadatadir' => '/var/www/v3/app/config/saml-config/metadata',

If using a certificate, find and adjust certdir:

'certdir' => '/var/www/v3/app/config/saml-config/cert',

Generate a secure password:

/var/www/vendor/simplesamlphp/simplesamlphp/bin/pwgen.php

Take the output hash and update this config.php property:

'auth.adminpassword' => 'GENERATED PASSWORD'

Generate salt

tr -c -d '0123456789abcdefghijklmnopqrstuvwxyz' </dev/urandom | dd bs=32 count=1 2>/dev/null;echo

Take the output and update this config.php property:

'secretsalt' => 'randombytesinsertedhere'

Adjustment if running HTTP

If you are not using ssl, you will need to adjust the following cookie setting in config.php:

'session.cookie.samesite' => 'Lax',

3. Add identity provider data

You should now be able to login to the simpleSAMLphp admin dashboard at the following URL:

YOUR HOST NAME/simplesaml/admin

You will use the password you generated in the previous step.

When configuring identity providers, ensure that their name Id format is set to email.

In the federation tab, you will see a link to your service provider metadata. You will utilize this metadata to setup your identity providers. The identity provider will have metadata of its own. If this is in an XML format, you will utilize the dashboard tool “XML to SimpleSAMLphp metadata converter"

Copy the output, then generate a directory for the identity provider metadata:

mkdir /var/www/v3/app/config/saml-config/metadata

Create the identity provider file:

cat <<'EOT' >> /var/www/v3/app/config/saml-config/metadata/saml20-idp-remote.php
<?php
//Paste PHP metadata item here
EOT

4. Link email domain to identity provider

mysql -uemx -p
use emx;

Run the following query, replacing each value below with what is appropriate:

INSERT INTO `saml_sources` (`name`, `entityId`, `domain`)
VALUES
	('NAME FOR IDP', 'IDP Entity ID', 'EMAIL DOMAIN');

Exit mysql.

5. Test

You can either use the test tab in the SimpleSAMLphp dashboard, or you can attempt to login directly to EMX. When you type in an email with a domain inserted above, it should redirect you to the associated identity provider.