241 lines
9.2 KiB
Plaintext
241 lines
9.2 KiB
Plaintext
simpleSAMLphp Advanced Features
|
|
===============================
|
|
|
|
<!--
|
|
This file is written in Markdown syntax.
|
|
For more information about how to use the Markdown syntax, read here:
|
|
http://daringfireball.net/projects/markdown/syntax
|
|
-->
|
|
|
|
|
|
|
|
<!-- {{TOC}} -->
|
|
|
|
simpleSAMLphp documentation
|
|
---------------------------
|
|
|
|
This document is part of the simpleSAMLphp documentation suite.
|
|
|
|
- [List of all simpleSAMLphp documentation](http://simplesamlphp.org/docs)
|
|
|
|
|
|
This document assumes that you already have a installation of
|
|
simpleSAMLphp running, configured and working. This is the next
|
|
step :)
|
|
|
|
|
|
Bridging between protocols
|
|
--------------------------
|
|
|
|
A bridge between two protocols is built using both an IdP and an SP, connected together.
|
|
To let a SAML 2.0 SP talk to a SAML 1.1 IdP, you build a simpleSAMLphp bridge from a SAML 2.0 IdP and a SAML 1.1 SP.
|
|
The SAML 2.0 SP talks to the SAML 2.0 IdP, which hands the request over to the SAML 1.1 SP, which forwards it to the SAML 1.1 IdP.
|
|
|
|
If you have followed the instructions for setting up an SP, and have configured an authentication source, all you need to do is to add that authentication source to the IdP.
|
|
|
|
**Example of bridge configuration**
|
|
|
|
In `metadata/saml20-idp-hosted.php`:
|
|
|
|
'auth' => 'default-sp',
|
|
|
|
In `config/authsources.php`:
|
|
|
|
'default-sp' => array(
|
|
'saml:SP',
|
|
),
|
|
|
|
|
|
|
|
Attribute control
|
|
-----------------
|
|
|
|
Filtering, mapping, etc can be performed by using existing or create new *Authentication Processing Filters*. For more information, read:
|
|
|
|
* [Authentication Processing Filters in SimpleSAMLphp](simplesamlphp-authproc)
|
|
|
|
|
|
|
|
Automatic update of SAML 2.0 Metadata XML from HTTPS
|
|
----------------------------------------------------
|
|
|
|
The `metarefresh` module is the preferred method for doing this.
|
|
Please see the [metarefresh documentation](simplesamlphp-automated_metadata).
|
|
|
|
|
|
|
|
Auth MemCookie
|
|
--------------
|
|
|
|
It is possible to integrate simpleSAMLphp with [Auth MemCookie](http://authmemcookie.sourceforge.net/). This allows you to integrate simpleSAMLphp with web applications written in another language than PHP.
|
|
|
|
Auth MemCookie works by reading authentication data from a memcache server and setting environment variables based on attributes in this data. It also allows you to use the default Apache access control features to restrict access to your site.
|
|
|
|
The simpleSAMLphp Auth MemCookie module can be found in `www/authmemcookie.php` and the configuration should be stored in `config/authmemcookie.php`. You may have to copy this file from `config-template/authmemcookie.php`.
|
|
|
|
To use Auth MemCookie, you need to do the following steps:
|
|
|
|
1. Install and configure simpleSAMLphp for running as an SP.
|
|
2. Install and configure a memcache server.
|
|
3. Install and configure Auth MemCookie. Go to the
|
|
[Auth MemCookie homepage](http://authmemcookie.sourceforge.net/)
|
|
for downloads and installation instructions. The following example
|
|
(from `extra/auth_memcookie.conf`) may be useful when configuring
|
|
Auth MemCookie:
|
|
|
|
<Location />
|
|
# This is a list of memcache servers which Auth MemCookie
|
|
# should use. It is a ','-separated list of
|
|
# host:port-pairs.
|
|
# Note that this list must list the same servers as the
|
|
# 'authmemcookie.servers'-option in config.php in the
|
|
# configuration for simpleSAMLphp.
|
|
Auth_memCookie_Memcached_AddrPort "127.0.0.1:11211"
|
|
|
|
# This must be set to 'on' to enable Auth MemCookie for
|
|
# this directory.
|
|
Auth_memCookie_Authoritative on
|
|
|
|
# This adjusts the maximum number of data elements in the
|
|
# session data. The default is 10, which can be to low.
|
|
Auth_memCookie_SessionTableSize "40"
|
|
|
|
# These two commands are required to enable access control
|
|
# in Apache.
|
|
AuthType Cookie
|
|
AuthName "My Login"
|
|
|
|
# This command causes apache to redirect to the given
|
|
# URL when we receive a '401 Authorization Required'
|
|
# error. We redirect to "/simplesaml/authmemcookie.php",
|
|
# which initializes a login to the IdP.
|
|
ErrorDocument 401 "/simplesaml/authmemcookie.php"
|
|
|
|
</Location>
|
|
|
|
<Location /secret>
|
|
# This allows all authenticated users to access the
|
|
# directory. To learn more about the 'Require' command,
|
|
# please look at:
|
|
# http://httpd.apache.org/docs/2.0/mod/core.html#require
|
|
Require valid-user
|
|
</Location>
|
|
|
|
4.
|
|
Configure the simpleSAMLphp Auth MemCookie module by editing
|
|
`config/authmemcookie.php`. You must set the `username` option to a
|
|
valid attribute name. All other can most likely be left at their
|
|
default values.
|
|
|
|
5.
|
|
Enable the simpleSAMLphp Auth MemCookie module by setting
|
|
`enable.authmemcookie` to *`true`* in `config/config.php`.
|
|
|
|
6.
|
|
To test the installation, you can add the following script as your
|
|
`/secret/index.php` directory:
|
|
|
|
<html><body><table>
|
|
<?php
|
|
foreach($_SERVER as $key=>$value) {
|
|
echo('<tr><td>' . htmlspecialchars($key) . '</td><td>' . htmlspecialchars($value) . '</td></tr>');
|
|
}
|
|
?>
|
|
</table></body></html>
|
|
|
|
You should now be able to go to `http://yourserver/secret/` to test
|
|
the configuration. You should be redirected to your IdP, and after
|
|
entering your username and password you should be taken back to
|
|
`http://yourserver/secret/`. The resulting page should list all
|
|
environment variables set by Apache, including the ones set by Auth
|
|
MemCookie.
|
|
|
|
|
|
|
|
|
|
Metadata signing
|
|
----------------
|
|
|
|
simpleSAMLphp supports signing of the metadata it generates. Metadata signing is configured by four options:
|
|
|
|
- `metadata.sign.enable`: Whether metadata signing should be enabled or not. Set to `TRUE` to enable metadata signing. Defaults to `FALSE`.
|
|
- `metadata.sign.privatekey`: Name of the file with the private key which should be used to sign the metadata. This file must exist in in the `cert` directory.
|
|
- `metadata.sign.privatekey_pass`: Passphrase which should be used to open the private key. This parameter is optional, and should be left out if the private key is unencrypted.
|
|
- `metadata.sign.certificate`: Name of the file with the certificate which matches the private key. This file must exist in in the `cert` directory.
|
|
|
|
These options can be configured globally in the `config/config.php`-file, or per SP/IdP by adding them to the hosted metadata for the SP/IdP. The configuration in the metadata for the SP/IdP takes precedence over the global configuration.
|
|
|
|
There is also an additional fallback for the private key and the certificate. If `metadata.sign.privatekey` and `metadata.sign.certificate` isn't configured, simpleSAMLphp will use the `privatekey`, `privatekey_pass` and `certificate` options in the metadata for the SP/IdP.
|
|
|
|
|
|
|
|
|
|
Session checking function
|
|
-------------------------
|
|
|
|
Optional session checking function, called on session init and loading, defined with 'session.check_function' in config.php.
|
|
|
|
Example code for the function with GeoIP country check:
|
|
|
|
|
|
public static function checkSession($session, $init = FALSE) {
|
|
$data_type = 'example:check_session';
|
|
$data_key = 'remote_addr';
|
|
|
|
$remote_addr = NULL;
|
|
if (!empty($_SERVER['REMOTE_ADDR'])) {
|
|
$remote_addr = (string)$_SERVER['REMOTE_ADDR'];
|
|
}
|
|
|
|
if ($init) {
|
|
$session->setData($data_type, $data_key, $remote_addr, SimpleSAML_Session::DATA_TIMEOUT_SESSION_END);
|
|
return;
|
|
}
|
|
|
|
if (!function_exists('geoip_country_code_by_name')) {
|
|
SimpleSAML_Logger::warning('geoip php module required.');
|
|
return TRUE;
|
|
}
|
|
|
|
$stored_remote_addr = $session->getData($data_type, $data_key);
|
|
if ($stored_remote_addr === NULL) {
|
|
SimpleSAML_Logger::warning('Stored data not found.');
|
|
return FALSE;
|
|
}
|
|
|
|
$country_a = geoip_country_code_by_name($remote_addr);
|
|
$country_b = geoip_country_code_by_name($stored_remote_addr);
|
|
|
|
if ($country_a === $country_b) {
|
|
if ($stored_remote_addr !== $remote_addr) {
|
|
$session->setData($data_type, $data_key, $remote_addr, SimpleSAML_Session::DATA_TIMEOUT_SESSION_END);
|
|
}
|
|
|
|
return TRUE;
|
|
}
|
|
|
|
return FALSE;
|
|
}
|
|
|
|
|
|
|
|
|
|
Support
|
|
-------
|
|
|
|
If you need help to make this work, or want to discuss
|
|
simpleSAMLphp with other users of the software, you are fortunate:
|
|
Around simpleSAMLphp there is a great Open source community, and
|
|
you are welcome to join! The forums are open for you to ask
|
|
questions, contribute answers other further questions, request
|
|
improvements or contribute with code or plugins of your own.
|
|
|
|
- [simpleSAMLphp homepage](https://simplesamlphp.org)
|
|
- [List of all available simpleSAMLphp documentation](http://simplesamlphp.org/docs/)
|
|
- [Join the simpleSAMLphp user's mailing list](http://rnd.feide.no/content/simplesamlphp-users-mailinglist)
|
|
- [Visit and contribute to the simpleSAMLphp wiki](https://ow.feide.no/simplesamlphp:start)
|
|
|
|
|
|
|
|
|