Table of Contents generated with DocToc
SimpleSAMLphp Proxy tutorial for Techex 2017
This tutorial will take you through setting up an SP, an IdP and SAML Proxy with SimpleSAMLphp. The tutorial uses docker to minimize the amount of configuration changes and software you need to install on your machine.
The tutorial was created by
- Cirrus Identity Patrick Radtke [email protected]
- Unicon Michael Grady [email protected]
Unsure why you would even want to use a SAML Proxy? View some use cases
There can be some surprises when using a proxy. View some gotchas
New to SSP? Here is where the installation files are
/var/simplesamlphp
|-- attributemap
| |-- facebook2name.php
| |-- name2oid.php
| `-- etc
|-- cert
| |-- saml.crt
| `-- saml.pem
|-- config
| |-- authsources.php
| `-- config.php
|-- config-templates
| `-- various sample configuraltion files
|-- data (storage of temp files)
|-- dictionaries
| `-- text strings for supporting i18n
|-- lib (part the code base)
|-- metadata
| |-- saml20-idp-hosted.php
| |-- saml20-idp-remote.php
| `-- saml20-sp-remote.php
|-- modules
| |-- authfacebook (option module to use facebook for auth)
| |-- core (the core functionality)
| `-- numerous other modules
|-- templates (UI templates you can override)
|-- vendor (dependencies)
`-- www (main webapp. Modules can extend)
| Time | Topic |
|---|---|
| 1 - 1:10 | Overview |
| 1:10 - 1:40 | Setup an SP |
| 1:40 - 2:25 | Setup an IdP |
| 2:25 - 3:00 | Setup a Proxy |
| 3:00 - 3:30 | Break |
| 3:30 - 4:15 | Multiple Protocols |
| 4:15 - 5:00 | Q & A |
We've broken the tutorial into several stages. If you get stuck, see the debugging section below.
Here are some tips if you run into issues.
Periodically TestShib will clear out old metadata, and it will need to be re-added.
You can download the SP metadata and the IdP metadata, ensure the file-names are unique and end with .xml and upload to TestShib.
TestShib use file name to identify your upload. If you pick a common name it may get overridden. If the file doesn't end in .xml then it seems TestShib won't recognize the file.
If you visit SSP in the browser and see
You have not yet created the SimpleSAMLphp configuration files.
See: https://simplesamlphp.org/docs/devel/simplesamlphp-install-repo
then it means that SSP is unable to find your configuration
files. This is usually caused by running the docker run command from
the wrong folder. It should be run from the root level of the github
checkout. If you look at the run command you will see it using
arguments such as -v $PWD/some/path:/var/simplesamlphp/somepath'. You need to be in the folder such that $PWD/some/path` is a legetimate
folder with the configuration files.
Unforunately if you run docker from the wrong folder it will create those folders on your filesystem. However they will be empty, which is how you can determine if they came from the tutorial or were accidentaly created by docker.
In config.php we've disabled showerrors as a security best
practice. Feel free to re-enable this to get better error messages
displayed in your browser.
SSP is configured to log to STDOUT/STDERR so you can use docker logs
to view what is happening.
There can be a lot of log lines. You can tail the logs for a specific container, and then trigger the error to narrows down the cause
docker logs -f --tail 5 CONTAINER_NAME
172.17.0.5:443 172.17.0.2 - - [26/Sep/2017:00:12:04 +0000] "GET /simplesaml/module.php/core/authenticate.php HTTP/1.1" 200 1736 "https://github.com/cirrusidentity/ssp-proxy-tutorial/tree/master/2_IdP_Setup" "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/60.0.3112.113 Safari/537.36"
[Tue Sep 26 00:12:17.167449 2017] [:error] [pid 23] [client 172.17.0.2:44512] simplesamlphp ERR [903fcc9267] SimpleSAML_Error_Error: UNHANDLEDEXCEPTION, referer: https://idp.tutorial.stack-dev.cirrusidentity.com/simplesaml/module.php/core/authenticate.php
[Tue Sep 26 00:12:17.167679 2017] [:error] [pid 23] [client 172.17.0.2:44512] simplesamlphp ERR [903fcc9267] Backtrace:, referer: https://idp.tutorial.stack-dev.cirrusidentity.com/simplesaml/module.php/core/authenticate.php
[Tue Sep 26 00:12:17.167762 2017] [:error] [pid 23] [client 172.17.0.2:44512] simplesamlphp ERR [903fcc9267] 0 /var/simplesamlphp/www/module.php:180 (N/A), referer: https://idp.tutorial.stack-dev.cirrusidentity.com/simplesaml/module.php/core/authenticate.phpThe docker run commands in the tutorial should enable the required
SSP modules. However there are cases, where on a Windows host, the modules were not enabled.
In the below example we check if the exampleauth or the cron
module are enabled, and we see exampleauth is enabled (there is a
file named enable) while cron is not.
docker exec CONTAINER_NAME ls -l /var/simplesamlphp/modules/{exampleauth,cron}/enable
ls: cannot access /var/simplesamlphp/modules/cron/enable: No such file or directory
-rw-r--r-- 1 root root 0 Sep 15 22:40 /var/simplesamlphp/modules/exampleauth/enable
# Enable modules.
docker exec CONTAINER_NAME touch /var/simplesamlphp/modules/{exampleauth,cron}/enablenote: modules can also be enabled if there is a default-enable
file present and no disable file.
It can be easy to make a typo in the php config files rendering them unparsable.
You can check by running the php cli.
docker exec CONTAINER_NAME php -f /var/simplesamlphp/config/authsources.php
PHP Parse error: syntax error, unexpected ''tutorial-idp'' (T_CONSTANT_ENCAPSED_STRING), expecting ')' in /var/simplesamlphp/config/authsources.php on line 14