SimpleSAMLphp Installation and Configuration
-
SimpleSAMLphp Installation and Configuration
- Prerequisites
- Download and install SimpleSAMLphp
- Upgrading from a previous version of SimpleSAMLphp
- Configuration
- Configuring Apache
- Configuring Nginx
- SimpleSAMLphp configuration: config.php
- Configuring PHP
- Enabling and disabling modules
- The SimpleSAMLphp admin interface
- Next steps
- Support
- Appendix: Installing SimpleSAMLphp in alternative locations
This document is part of the SimpleSAMLphp documentation suite.
This document covers the installation of the latest stable version of SimpleSAMLphp. If you want to install the development version, take a look at the instructions for installing SimpleSAMLphp from the repository .
Prerequisites
- A web server capable of executing PHP scripts.
- PHP version >= 8.1.0.
-
Support for the following PHP extensions:
-
Always required:
date
,dom
,fileinfo
,filter
,hash
,json
,libxml
,mbstring
,openssl
,pcre
,session
,simplexml
,sodium
,SPL
andzlib
-
When running on Linux:
posix
-
When wanting to use translations for non-English languages:
intl
-
When automatically checking for latest versions, and used by some modules:
cURL
-
When authenticating against an LDAP server:
ldap
-
When authenticating against a RADIUS server:
radius
-
When using the native PHP session handler:
session
-
When saving session information to a memcache server:
memcache
-
When using databases:
-
Always required:
PDO
-
Database driver: (
mysql
,pgsql
, ...)
-
Always required:
-
Always required:
-
Support for the following PHP packages:
-
When saving session information to a Redis server:
predis
-
When saving session information to a Redis server:
What actual packages are required for the various extensions varies between different platforms and distributions.
Download and install SimpleSAMLphp
The most recent release of SimpleSAMLphp can always be found at https://simplesamlphp.org/download .
Go to the directory where you want to install SimpleSAMLphp and extract the archive file you just downloaded:
cd /var
tar xzf simplesamlphp-x.y.z.tar.gz
mv simplesamlphp-x.y.z simplesamlphp
Upgrading from a previous version of SimpleSAMLphp
Before starting the upgrade, review the relevant upgrade notes for any relevant changes.
Extract the new version:
cd /var
tar xzf simplesamlphp-x.y.z.tar.gz
Copy the configuration files from the previous version (in case the configuration directory is inside SimpleSAMLphp, keep reading for other alternatives):
cd /var/simplesamlphp-x.y.z
rm -rf config metadata
cp -rv ../simplesamlphp/config config
cp -rv ../simplesamlphp/metadata metadata
If you have installed any third-party modules or customised the theme , you should check whether your third-party modules need upgrading and then copy or replace those directories too.
Replace the old version with the new version:
cd /var
mv simplesamlphp simplesamlphp.old
mv simplesamlphp-x.y.z simplesamlphp
If the format of the config files or metadata has changed from your previous version of SimpleSAMLphp (check the upgrade notes), you may have to update your configuration and metadata after updating the SimpleSAMLphp code.
Upgrading configuration files
A good approach is to run a
diff
between your previous
config.php
file and the new
config.php.dist
file located
the same directory, and apply relevant modifications to the new template. This will ensure that all new
entries in the latest version of config.php are included, as well as preserve your local modifications.
Upgrading metadata files
Most likely the metadata format is backwards compatible. If not, you should receive a very clear error message at
startup indicating how and what you need to update. You should look through the metadata in the
metadata-templates
directory after the upgrade to see whether recommended defaults have been changed.
Configuration
Location of configuration files
By default, SimpleSAMLphp looks for its configuration in the
config
directory in the root of its own directory. This
has some drawbacks, like making it harder to update SimpleSAMLphp or to install it as a composer dependency, or to
package it for different operating systems.
In order to avoid this limitations, it is possible to specify an alternative location for the configuration directory
by setting the
SIMPLESAMLPHP_CONFIG_DIR
environment variable to point to this location. This way, the configuration
directory doesn't need to be inside the library's directory, making it easier to manage and to update. The simplest way
to set this environment variable is to set it in your web server's configuration. See the next section for more
information.
Configuring Apache
Examples below assume that SimpleSAMLphp is installed in the default location,
/var/simplesamlphp
. You may choose
another location, but this requires a path update in a few files. See Appendix
Installing SimpleSAMLphp
in alternative locations
for more details.
The only subdirectory of
SimpleSAMLphp
that needs to be accessible from the web is
public
. There are several ways of
exposing SimpleSAMLphp depending on the way web sites are structured on your Apache web server. The following is just
one possible configuration.
Find the Apache configuration file for the virtual hosts where you want to run SimpleSAMLphp. The configuration may look like this:
<VirtualHost *>
ServerName service.example.com
DocumentRoot /var/www/service.example.com
SetEnv SIMPLESAMLPHP_CONFIG_DIR /var/simplesamlphp/config
Alias /simplesaml /var/simplesamlphp/public
<Directory /var/simplesamlphp/public>
Require all granted
</Directory>
</VirtualHost>
Note the
Alias
directive, which gives control to SimpleSAMLphp for all urls matching
http(s)://service.example.com/simplesaml/*
. SimpleSAMLphp makes several SAML interfaces available on the web; all of
them are accessible through the
public
subdirectory of your SimpleSAMLphp installation. You can name the alias
whatever you want, but the name must be specified in the
baseurlpath
configuration option in the
config.php
file of
SimpleSAMLphp as described in
the section called “SimpleSAMLphp configuration: config.php”
.
Here is an example of how this configuration may look like in
config.php
:
$config = [
[...]
'baseurlpath' => 'simplesaml/',
[...]
]
Note also the
SetEnv
directive in the Apache configuration. It sets the
SIMPLESAMLPHP_CONFIG_DIR
environment
variable, in this case, to the default location for the configuration directory. You can omit this environment
variable, and SimpleSAMLphp will then look for the
config
directory inside its own directory. If you need to move
your configuration to a different location, you can use this environment variable to tell SimpleSAMLphp where to look
for configuration files. This works only for the
config
directory. If you need your metadata to be in a different
directory too, use the
metadatadir
configuration option to specify the location.
This is just the basic configuration to get things working. For a checklist further completing your documentation, please see Maintenance and configuration: Apache .
Configuring Nginx
Examples below assume that SimpleSAMLphp is installed in the default location,
/var/simplesamlphp
. You may choose
another location, but this requires a path update in a few files. See Appendix
Installing SimpleSAMLphp
in alternative locations
for more details.
The only subdirectory of
SimpleSAMLphp
that needs to be accessible from the web is
public
. There are several ways of
exposing SimpleSAMLphp depending on the way web sites are structured on your Nginx web server. The following is just
one possible configuration.
Find the Nginx configuration file for the virtual hosts where you want to run SimpleSAMLphp. The configuration may look like this:
server {
listen 443 ssl;
server_name idp.example.com;
index index.php;
ssl_certificate /etc/pki/tls/certs/idp.example.com.crt;
ssl_certificate_key /etc/pki/tls/private/idp.example.com.key;
ssl_protocols TLSv1.3 TLSv1.2;
ssl_ciphers EECDH+AESGCM:EDH+AESGCM;
location ^~ /simplesaml {
alias /var/simplesamlphp/public;
location ~^(?<prefix>/simplesaml)(?<phpfile>.+?\.php)(?<pathinfo>/.*)?$ {
include fastcgi_params;
fastcgi_pass $fastcgi_pass;
fastcgi_param SCRIPT_FILENAME $document_root$phpfile;
# Must be prepended with the baseurlpath
fastcgi_param SCRIPT_NAME /simplesaml$phpfile;
fastcgi_param PATH_INFO $pathinfo if_not_empty;
}
}
}
SimpleSAMLphp configuration: config.php
There are a few steps that you should complete in the main configuration file,
config.php
, right away:
-
Set the
baseurlpath
configuration option. Make it point to the canonical URL of your deployment, where SimpleSAMLphp can be reached:
'baseurlpath' => 'https://your.canonical.host.name/simplesaml/',
Please note that your canonical URL should always use HTTPS in order to protect your users. Additionally, if you
are running behind a **reverse proxy** and you are offloading TLS to it, the proper way to tell SimpleSAMLphp that
its base URL should use HTTPS is to set the `baseurlpath` configuration option properly. SimpleSAMLphp deliberately
**ignores** the `X-Forwarded-*` set of headers that your proxy might be setting, so **do not rely on those**.
-
Set an administrator password. This is needed to access some of the pages in your SimpleSAMLphp installation web
interface. Plain-text passwords are not allowed, but you can generate a safe password-hash using the
bin/pwgen.php
script.
'auth.adminpassword' => 'setnewpasswordhere',
- Set a secret salt. This should be a random string. Some parts of the SimpleSAMLphp needs this salt to generate cryptographically secure hashes. SimpleSAMLphp will give an error if the salt is not changed from the default value. The command below can help you to generated a random string on (some) unix systems:
tr -c -d '0123456789abcdefghijklmnopqrstuvwxyz' </dev/urandom | dd bs=32 count=1 2>/dev/null;echo
Here is an example of the configuration option:
'secretsalt' => 'randombytesinsertedhere',
Please note that changing the secret salt may break access to services for your users .
-
Configure your data storage. You can do this by editing the
store.type
configuration option, and setting it to one of the supported values. Now configure the backend of your choice with the relevant options, if needed. -
Configure your sessions. You have to configure your sessions with the appropriate parameters so that the cookies used by SimpleSAMLphp to track users are always delivered to the software. You may do this by editing the
session.*
configuration options. Note that if you are using thephpsession
data storage, the cookie-related configuration options are configured in thesession.phpsession.*
options. -
Set technical contact information. This information will be available in the generated metadata. The e-mail address will also be used for receiving error reports sent automatically by SimpleSAMLphp. Here is an example:
'technicalcontact_name' => 'John Smith',
'technicalcontact_email' => 'john.smith@example.com',
- If you use SimpleSAMLphp in a country where English is not widespread, you may want to change the default language from English to something else:
'language.default' => 'no',
- Set your timezone
'timezone' => 'Europe/Oslo',
You can see a list of Supported Timezones at php.net .
Configuring PHP
Sending e-mails from PHP
Some parts of SimpleSAMLphp will allow you to send e-mails. For example, sending error reports to the technical admin. If you want to make use of this functionality, you should make sure your PHP installation is configured to be able to send e-mails.
By default SimpleSAMLphp uses the PHP
mail()
function, which you can configure via
php.ini
.
For more advanced configuration, including using a remote SMTP server, see the
mail.*
options in
config.php
.
Enabling and disabling modules
If you want to enable some of the modules that are installed with SimpleSAMLphp, but are disabled by default, you can do that in the configuration:
'module.enable' => [
'exampleauth' => true, // Setting to TRUE enables.
'saml' => false, // Setting to FALSE disables.
'core' => null, // Unset or NULL uses default for this module.
],
Set to
true
the modules you want to enable, and to
false
those that you want to disable.
Prior to SSP V2 you could enable or disable modules by setting empty files with names (
enable
,
disable
,
default-enable
) in the module's root directory. You need to now use the
module.enable
config option.
The SimpleSAMLphp admin interface
After installing SimpleSAMLphp, you can access the homepage of your installation, which by default does not show much information:
https://service.example.org/simplesaml/
The exact URL depends on how you set it up with your web server, and of course on your hostname.
If this works, you can now also acceas the admin module by adding
admin/
to your base URL:
https://service.example.org/simplesaml/admin/
Warning : before you can actually use SimpleSAMLphp for something useful, you need to configure it either as a Service Provider or as an Identity Provider, depending on your use case.
Here is an example screenshot of what the SimpleSAMLphp page looks like:
Check your PHP environment
At the bottom of the admin page there are some green lights. SimpleSAMLphp runs some tests to see whether the required and recommended prerequisites are met. If any of the lights are red, you may have to install some PHP extensions or external PHP packages (e.g. you need the PHP LDAP extension to use the LDAP authentication module).
Next steps
You have now successfully installed SimpleSAMLphp, and the next steps depend on whether you want to setup a Service Provider (in order to protect access to an existing application) or an Identity Provider (which you would connect to a user database where your users can authenticate). Documentation on bridging between federation protocols is found in a separate document.
- Using SimpleSAMLphp as a Service Provider (SP)
- Using SimpleSAMLphp as an Identity Provider (IdP)
- Automated Metadata Management
- Maintenance and configuration
Support
If you need help to make this work, or want to discuss SimpleSAMLphp with other users of the software, you are in luck: there is a great Open Source community around SimpleSAMLphp, and you are welcome to join! The forums are open for you to ask questions, help others by answering their questions, request improvements or contribute with code or plugins of your own.
Appendix: Installing SimpleSAMLphp in alternative locations
There may be several reasons why you want to install SimpleSAMLphp in an alternative way.
-
You are installing SimpleSAMLphp in a hosted environment where you do not have root access, and cannot change Apache configuration. You can still install SimpleSAMLphp, keep on reading!
-
You have full permissions to the server, but cannot edit web server configuration for some reason like internal policies.
The SimpleSAMLphp package contains one folder named
simplesamlphp-x.y.z
(where
x.y.z
is the version number). In
this folder there are a lot of subfolders for library, metadata, configuration, etc. One of these folders is named
public
.
Only this folder should be exposed on the web
. The recommended configuration is to put the whole
simplesamlphp
folder outside the web root, and then link to the
public
folder by using the
Alias
directive, as
described in
the section called “Configuring Apache”
. This is not the only
possible way, though.
As an example, let's see how you can install SimpleSAMLphp in your home directory on a shared hosting server.
-
Extract the SimpleSAMLphp archive in your home directory:
cd ~ tar xzf simplesamlphp-1.x.y.tar.gz mv simplesamlphp-1.x.y simplesamlphp
-
Then you can try to make a symlink into the
public_html
directory.cd ~/public_html ln -s ../simplesamlphp/public simplesaml
-
Next, you need to set the
baseurlpath
configuration option with the URL pointing to thesimplesaml
link you just created in yourpublic_html
directory. For example, if your home directory is reachable inhttps://host.example/~myaccount/
, set the base URL path accordingly:'baseurlpath' => 'https://host.example/~myaccount/simplesaml/',
Now, you can go to the URL of your installation and check if things work:
https://host.example/~myaccount/simplesaml/
Tip
Symlinking may fail, because some Apache configurations do not allow you to link to files from outside the
public_html
folder. If so, you can move the
public
folder instead of symlinking it:
cd ~/public_html
mv ../simplesamlphp/public simplesaml
Now you have the following directory structure.
-
~/simplesamlphp
-
~/public_html/simplesaml
wheresimplesaml
is thepublic
directory from thesimplesamlphp
installation directory, either moved or a symlink.
Now, we need to make a few configuration changes. First, let's edit
~/public_html/simplesaml/_include.php
:
Change the two lines from:
require_once(dirname(_FILE__, 2) . '/lib/_autoload.php');
to something like:
require_once(dirname(__FILE__, 3) . '/lib/_autoload.php');
Warning
: note that this will make upgrading SimpleSAMLphp much more difficult, since you will need to move the
public
directory and manually edit files every time you upgrade. It is also possible that this method does not work in
future versions of SimpleSAMLphp, and therefore it is discouraged and should be used only as a last resort.