hazza/resourcespace
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity

first commit

Browse Source
This commit is contained in:
Hendra Go
2025-07-18 16:20:14 +07:00
commit 98af45c018
16382 changed files with 3148096 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

12
plugins/simplesaml/lib/docs/README Normal file
View File

@@ -0,0 +1,12 @@
Updated: January 15th, 2015
All you need to know to install and configure simpleSAMLphp is available at:
https://simplesamlphp.org/docs/
simpleSAMLphp homepage:
https://simplesamlphp.org/
simpleSAMLphp mailinglist (for support):
https://simplesamlphp.org/lists

7
plugins/simplesaml/lib/docs/conf.py Normal file
View File

@@ -0,0 +1,7 @@
import sphinx_rtd_theme
extensions = [
'sphinx_rtd_theme',
]
html_theme = "sphinx_rtd_theme"

36
plugins/simplesaml/lib/docs/index.md Normal file
View File

@@ -0,0 +1,36 @@
# SimpleSAMLphp Documentation
* Installation and upgrading
* [Installing SimpleSAMLphp](simplesamlphp-install)
* [Upgrade notes](simplesamlphp-upgrade-notes)
* [Installation from the repository](simplesamlphp-install-repo)
* [Changelog](simplesamlphp-changelog)
* Using SimpleSAMLphp as a SAML Service Provider
* [Service Provider Quickstart](simplesamlphp-sp)
* [Hosted SP Configuration Reference](./saml:sp)
* [IdP remote reference](simplesamlphp-reference-idp-remote)
* [SP API reference (for your application)](simplesamlphp-sp-api).
* [Configuring HTTP-Artifact](./simplesamlphp-artifact-sp)
* [Using scoping](./simplesamlphp-scoping)
* [Holder-of-Key profile](simplesamlphp-hok-sp)
* Using SimpleSAMLphp as a SAML Identity Provider
* [Identity Provider QuickStart](simplesamlphp-idp)
* [IdP hosted reference](simplesamlphp-reference-idp-hosted)
* [SP remote reference](simplesamlphp-reference-sp-remote)
* [Use case: Setting up an IdP for Google Workspace (G Suite / Google Apps)](simplesamlphp-googleapps)
* [Configuring HTTP-Artifact](./simplesamlphp-artifact-idp)
* [Identity Provider Advanced Topics](simplesamlphp-idp-more)
* [Holder-of-Key profile](simplesamlphp-hok-idp)
* Further topics
* [Maintenance and configuration](simplesamlphp-maintenance) - covers session handling, php configuration etc.
* [Automated Metadata Management](/docs/contrib_modules/metarefresh/simplesamlphp-automated_metadata)
* [Key rollover](./saml:keyrollover)
* [Authentication Processing Filters](simplesamlphp-authproc) - attribute filtering, attribute mapping, consent, group generation etc.
* [State Information Lost](simplesamlphp-nostate) - more about this common error message
* [Advanced features](simplesamlphp-advancedfeatures) - covers bridging protocols, attribute filtering, etc.
* [Developer documentation](simplesamlphp-developer-information) - code overview and other docs for new and returning developers
* SimpleSAMLphp Modules
* [Documentation for specific modules](/docs/contributed_modules.html)
* [Theming SimpleSAMLphp](simplesamlphp-theming)
* [Creating authentication sources](./simplesamlphp-authsource)
* [Create your own customized modules](simplesamlphp-modules)

BIN
plugins/simplesaml/lib/docs/resources/simplesamlphp-googleapps/googleapps-cert.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 104 KiB

BIN
plugins/simplesaml/lib/docs/resources/simplesamlphp-googleapps/googleapps-menu.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 7.5 KiB

BIN
plugins/simplesaml/lib/docs/resources/simplesamlphp-googleapps/googleapps-sso.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 11 KiB

BIN
plugins/simplesaml/lib/docs/resources/simplesamlphp-googleapps/googleapps-ssoconfig.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 77 KiB

BIN
plugins/simplesaml/lib/docs/resources/simplesamlphp-install/screenshot-installationpage.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 304 KiB

BIN
plugins/simplesaml/lib/docs/resources/simplesamlphp-sp/screenshot-example.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 256 KiB

144
plugins/simplesaml/lib/docs/simplesamlphp-advancedfeatures.md Normal file
View File

@@ -0,0 +1,144 @@
# SimpleSAMLphp Advanced Features
[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`:
```php
'auth' => 'default-sp',
```
In `config/authsources.php`:
```php
'default-sp' => [
'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](/docs/contrib_modules/metarefresh/simplesamlphp-automated_metadata).
## Using simpleSAMLphp on a web server requiring the use of a web proxy
Some modules in simpleSAMLphp may require fetching HTTP/HTTPS content from external websites (e.g. the metarefresh module needs to fetch the metadata from an external source).
simpleSAMLphp can be configured to send HTTP/S requests via such a proxy. The proxy can be configured in the config/config.php option "proxy". Should the proxy require authentication, this can be configured with "proxy.auth".
The default is not to use a proxy ('proxy' = null) and no username and password are used ('proxy.auth' = false).
## 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`: Location of the private key data which should be used to sign the metadata.
- `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`: Location of certificate data which matches the private key.
- `metadata.sign.algorithm`: The algorithm to use when signing metadata for this entity. Defaults to RSA-SHA256. Possible values:
- `http://www.w3.org/2000/09/xmldsig#rsa-sha1`
*Note*: the use of SHA1 is **deprecated** and will be disallowed in the future.
- `http://www.w3.org/2001/04/xmldsig-more#rsa-sha256`
The default.
- `http://www.w3.org/2001/04/xmldsig-more#rsa-sha384`
- `http://www.w3.org/2001/04/xmldsig-more#rsa-sha512`
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:
```php
public static function checkSession(\SimpleSAML\Session $session, bool $init = false)
{
$data_type = 'example:check_session';
$data_key = 'remote_addr';
$remote_addr = strval($_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](https://simplesamlphp.org/docs/)
- [Join the SimpleSAMLphp user's mailing list](https://simplesamlphp.org/lists)

101
plugins/simplesaml/lib/docs/simplesamlphp-artifact-idp.md Normal file
View File

@@ -0,0 +1,101 @@
Adding HTTP-Artifact support to the IdP
=======================================
This document describes the necessary steps to enable support for the HTTP-Artifact binding on a SimpleSAMLphp IdP:
1. Configure SimpleSAMLphp to use memcache to store the session.
2. Enable support for sending artifacts in `saml20-idp-hosted`.
3. Add the webserver certificate to the generated metadata.
Memcache
--------
To enable memcache, you must first install and configure memcache on the server hosting your IdP.
You need both a memcache server and a the PHP memcached client (extension).
How this is done depends on the distribution.
If you are running Debian or Ubuntu, you can install this by running:
```bash
apt install memcached php-memcached
```
simpleSAMLphp also supports the legacy `php-memcache` (without `d`) variant.
*Note*: For security, you must make sure that the memcache server is inaccessible to other hosts.
The default configuration on Debian is for the memcache server to be accessible to only the local host.
Once the memcache server is configured, you can configure simplesamlphp to use it to store sessions.
You can do this by setting the `store.type` option in `config.php` to `memcache`.
If you are running memcache on a different server than the IdP, you must also change the `memcache_store.servers` option in `config.php`.
Enabling artifact on the IdP
----------------------------
To enable the IdP to send artifacts, you must add the `saml20.sendartifact` option to the `saml20-idp-hosted` metadata file:
```php
$metadata['https://example.org/saml-idp'] = [
[....]
'auth' => 'example-userpass',
'saml20.sendartifact' => true,
];
```
Add new metadata to SPs
-----------------------
After enabling the Artifact binding, your IdP metadata will change to add a ArtifactResolutionService endpoint.
You therefore need to update the metadata for your IdP at your SPs.
`saml20-idp-remote` metadata for SimpleSAMLphp SPs should contain something like:
```php
'ArtifactResolutionService' => [
[
'index' => 0,
'Location' => 'https://idp.example.org/simplesaml/saml2/idp/ArtifactResolutionService.php',
'Binding' => 'urn:oasis:names:tc:SAML:2.0:bindings:SOAP',
],
],
```
SP metadata on the IdP
----------------------
An SP using the HTTP-Artifact binding must have an AssertionConsumerService endpoint supporting that binding.
This means that you must use the complex endpoint format in `saml20-sp-remote` metadata.
In general, that should look something like:
```php
'AssertionConsumerService' => [
[
'Binding' => 'urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST',
'Location' => 'https://sp.example.org/simplesaml/module.php/saml/sp/saml2-acs.php/default-sp',
'index' => 0,
],
[
'Binding' => 'urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Artifact',
'Location' => 'https://sp.example.org/simplesaml/module.php/saml/sp/saml2-acs.php/default-sp',
'index' => 2,
],
],
```
(The specific values of the various fields will vary depending on the SP.)
Certificate in metadata
-----------------------
Some SPs validates the SSL certificate on the ArtifactResolutionService using the certificates in the metadata.
You may therefore have to add the webserver certificate to the metadata that your IdP generates.
To do this, you need to set the `https.certificate` option in the `saml20-idp-hosted` metadata file.
That option should refer to a file containing the webserver certificate.
```php
$metadata['https://example.org/saml-idp'] = [
[....]
'auth' => 'example-userpass',
'saml20.sendartifact' => true,
'https.certificate' => '/etc/apache2/webserver.crt',
];
```

29
plugins/simplesaml/lib/docs/simplesamlphp-artifact-sp.md Normal file
View File

@@ -0,0 +1,29 @@
Using HTTP-Artifact from a SimpleSAMLphp SP
===========================================
This document describes how to use the HTTP-Artifact binding to receive authentication responses from the IdP.
Which binding the IdP should use when sending authentication responses is controlled by the `ProtocolBinding` in the SP configuration.
To make your Service Provider (SP) request that the response from the IdP is sent using the HTTP-Artifact binding, this option must be set to the HTTP-Artifact binding.
In addition to selecting the binding, you must also add a private key and certificate to your SP.
This is used for SSL client authentication when contacting the IdP.
To generate a private key and certificate, you may use the `openssl` commandline utility:
openssl req -newkey rsa:3072 -new -x509 -days 3652 -nodes -out sp.example.org.crt -keyout sp.example.org.pem
You can then add the private key and certificate to the SP configuration.
When this is done, you can add the metadata of your SP to the IdP, and test the authentication.
Example configuration
---------------------
'artifact-sp' => [
'saml:SP',
'ProtocolBinding' => 'urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Artifact',
'privatekey' => 'sp.example.org.pem',
'certificate' => 'sp.example.org.crt',
],
See the [SP configuration reference](./saml:sp) for a description of the options.

180
plugins/simplesaml/lib/docs/simplesamlphp-authproc.md Normal file
View File

@@ -0,0 +1,180 @@
# Authentication Processing Filters in SimpleSAMLphp
[TOC]
In SimpleSAMLphp, there is an API where you can *do stuff* at the IdP after authentication is complete, and just before you are sent back to the SP. The same API is available on the SP, after you have received a successful Authentication Response from the IdP and before you are sent back to the SP application.
Authentication processing filters postprocess authentication information received from authentication sources. It is possible to use this for additional authentication checks, requesting the user's consent before delivering attributes about the user, modifying the user's attributes, and other things which should be performed before returning the user to the service provider they came from.
Examples of neat things to do using Authentication Processing Filters:
* Filter out a subset of available attributes that are sent to a SP.
* Modify the name of attributes.
* Generate new attributes that are composed of others, for example eduPersonTargetedID.
* Ask the user for consent, before the user is sent back to a service.
* Implement basic Access Control on the IdP, limiting access for some users to some SPs.
## How to configure Auth Proc Filters
*Auth Proc Filters* can be set globally, or to be specific for only one SP or one IdP. That means there are five locations where you can configure *Auth Proc Filters*:
* Globally in `config.php`
* On the SP: Specific for only the SP in `authsources.php`
* On the SP: Specific for only one remote IdP in `saml20-idp-remote`
* On the IdP: Specific for only one hosted IdP in `saml20-idp-hosted`
* On the IdP: Specific for only one remote SP in `saml20-sp-remote`
*Note*: An Auth Proc Filter will not work in the "Test authentication sources" option in the web UI of a SimpleSAMLphp IdP. It will only be triggered in conjunction with an actual SP. So you need to set up an IdP *and* and SP when testing your filter.
The configuration of *Auth Proc Filters* is a list of filters with priority as *index*. Here is an example of *Auth Proc Filters* configured in `config.php`:
```php
'authproc.idp' => [
10 => [
'class' => 'core:AttributeMap',
'addurnprefix'
],
20 => 'core:TargetedID',
50 => 'core:AttributeLimit',
90 => [
'class' => 'consent:Consent',
'store' => 'consent:Cookie',
'focus' => 'yes',
'checked' => true
],
],
```
This configuration will execute *Auth Proc Filters* one by one, with the priority value in increasing order. When *Auth Proc Filters* is configured in multiple places, in example both globally, in the hosted IdP and remote SP metadata, then the list is interleaved sorted by priority.
The most important parameter of each item on the list is the *class* of the *Auth Proc Filter*. The syntax of the class is `modulename:classname`. As an example the class definition `core:AttributeLimit` will be expanded to look for the class `\SimpleSAML\Module\core\Auth\Process\AttributeLimit`. The location of this class file *must* then be: `modules/core/src/Auth/Process/AttributeLimit.php`.
You will see that a bunch of useful filters is included in the `core` and `saml` modules, but there are
many others published as [SimpleSAMLphp modules)[https://simplesamlphp.org/modules/] you can install. Beyond that, you are
encouraged to create your own filters and share with the community. If you have
created a cool *Auth Proc Filter* that does something useful, let us know, and
we may add it on the Modules overview.
When you know the class definition of a filter, and the priority, the simple way to configure the filter is:
```php
20 => 'core:TargetedID',
```
This is analogous to:
```php
20 => [
'class' => 'core:TargetedID'
],
```
Some *Auth Proc Filters* have optional or required *parameters*. To send parameters to *Auth Proc Filters*, you need to choose the second of the two alternatives above. Here is an example of provided parameters to the consent module:
```php
90 => [
'class' => 'consent:Consent',
'store' => 'consent:Cookie',
'focus' => 'yes',
'checked' => true,
],
```
### Filters in `config.php`
Global *Auth Proc Filters* are configured in the `config.php` file. You will see that the config template already includes an example configuration.
There are two config parameters:
* `authproc.idp` and
* `authproc.sp`
The filters in `authproc.idp` will be executed at the IdP side regardless of which IdP and SP entity that is involved.
The filters in `authproc.sp` will be executed at the SP side regardless of which SP and IdP entity that is involved.
### Filters in metadata
Filters can be added both in `hosted` and `remote` metadata. Here is an example of a filter added in a metadata file:
```php
$metadata['https://example.org/saml-idp'] = [
'host' => '__DEFAULT_',
'privatekey' => 'example.org.pem',
'certificate' => 'example.org.crt',
'auth' => 'feide',
'authproc' => [
40 => 'core:TargetedID',
],
]
```
The example above is in `saml20-idp-hosted`.
## Preconditional filters
Any filter can be configured with a precondition that will determine whether or not a filter should run.
The condition is represented as a string that will be evaluated, similar to the `core:PHP` filter. It also has
the `$attributes` and `$state` variable available for use.
The code must return either `true` to run the filter, or `false` to skip it.
```php
'authproc' => [
40 => 'core:TargetedID',
'%precondition' => 'return $attributes["displayName"] === "John Doe";',
],
```
## Auth Proc Filters included in the SimpleSAMLphp distribution
The following filters are included in the SimpleSAMLphp distribution:
* [`core:AttributeAdd`](./core:authproc_attributeadd): Add attributes to the response.
* [`core:AttributeCopy`](./core:authproc_attributecopy): Copy existing attributes to the response.
* [`core:AttributeAlter`](./core:authproc_attributealter): Do search-and-replace on attributevalues.
* [`core:AttributeLimit`](./core:authproc_attributelimit): Limit the attributes in the response.
* [`core:AttributeMap`](./core:authproc_attributemap): Change the name of the attributes.
* [`core:AttributeValueMap`](./core:authproc_attributevaluemap): Map attribute values to new values and attribute name.
* [`core:Cardinality`](./core:authproc_cardinality): Ensure the number of attribute values is within the specified multiplicity.
* [`core:CardinalitySingle`](./core:authproc_cardinalitysingle): Ensure the correct cardinality of single-valued attributes.
* [`core:GenerateGroups`](./core:authproc_generategroups): Generate a `group` attribute for the user.
* [`core:LanguageAdaptor`](./core:authproc_languageadaptor): Transferring language setting from IdP to SP.
* [`core:PHP`](./core:authproc_php): Modify attributes with custom PHP code.
* [`core:ScopeAttribute`](./core:authproc_scopeattribute): Add scope to attribute.
* [`core:ScopeFromAttribute`](./core:authproc_scopefromattribute): Create a new attribute based on the scope on a different attribute.
* [`core:StatisticsWithAttribute`](./core:authproc_statisticswithattribute): Create a statistics logentry.
* [`core:TargetedID`](./core:authproc_targetedid): Generate the `eduPersonTargetedID` attribute.
* [`core:WarnShortSSOInterval`](./core:authproc_warnshortssointerval): Give a warning if the user logs into the same SP twice within a few seconds.
* [`saml:AttributeNameID`](./saml:nameid): Generate custom NameID with the value of an attribute.
* [`saml:AuthnContextClassRef`](./saml:authproc_authncontextclassref): Set the authentication context in the response.
* [`saml:ExpectedAuthnContextClassRef`](./saml:authproc_expectedauthncontextclassref): Verify the user's authentication context.
* [`saml:FilterScopes`](./saml:filterscopes): Filter attribute values with scopes forbidden for an IdP.
* [`saml:NameIDAttribute`](./saml:nameidattribute): Create an attribute based on the NameID we receive from the IdP.
* [`saml:PersistentNameID`](./saml:nameid): Generate persistent NameID from an attribute.
* [`saml:PersistentNameID2TargetedID`](./saml:nameid): Store persistent NameID as eduPersonTargetedID.
* [`saml:TransientNameID`](./saml:nameid): Generate transient NameID.
* [`saml:SubjectID`](./saml:authproc_subjectid): Generate SubjectID.
* [`saml:PairwiseID`](./saml:authproc_pairwiseid): Generate PairwiseID.
See the [Third-party modules](https://simplesamlphp.org/modules) page on the SimpleSAMLphp website
for externally hosted modules that may provide a processing filter.
## Writing your own Auth Proc Filter
Look at the included *Auth Proc Filters* as examples. Copy the classes into your own module and start playing around.
Authentication processing filters are created by creating a class under `Auth/Process/` in a module. This class is expected to subclass `\SimpleSAML\Auth\ProcessingFilter`. A filter must implement at least one function - the `process(&$request)`-function. This function can access the `$request`-array to add, delete and modify attributes, and can also do more advanced processing based on the SP/IdP metadata (which is also included in the `$request`-array). When this function returns, it is assumed that the filter has finished processing.
If a filter for some reason needs to redirect the user, for example to show a web page, it should save the current request. Upon completion it should retrieve the request, update it with the changes it is going to make, and call `\SimpleSAML\Auth\ProcessingChain::resumeProcessing`. This function will continue processing the next configured filter.
Requirements for authentication processing filters:
* Must be derived from the `\SimpleSAML\Auth\ProcessingFilter`-class.
* If a constructor is implemented, it must first call the parent constructor, passing along all parameters, before accessing any of the parameters. Only the $config parameter can be accessed.
* The `process(array &$state)`-function must be implemented. If this function completes, it is assumed that processing is completed, and that the $state array has been updated.
* If the `process`-function does not return, it must at a later time call `\SimpleSAML\Auth\ProcessingChain::resumeProcessing` with the new request state. The request state must be an update of the array passed to the `process`-function.
* No pages may be shown to the user from the `process`-function. Instead, the request state should be saved, and the user should be redirected to a new page. This must be done to prevent unpredictable events if the user for example reloads the page.
* No state information should be stored in the filter object. It must instead be stored in the request state array. Any changes to variables in the filter object may be lost.
* The filter object must be serializable. It may be serialized between being constructed and the call to the `process`-function. This means that, for example, no database connections should be created in the constructor and later used in the `process`-function.
Don't hestitate to ask on the SimpleSAMLphp mailinglist if you have problems or questions, or want to share your *Auth Proc Filter* with others.

92
plugins/simplesaml/lib/docs/simplesamlphp-authsource.md Normal file
View File

@@ -0,0 +1,92 @@
# Creating authentication sources
All authentication sources are located in the `src/Auth/Source/` directory in a module, and the class name is `\SimpleSAML\Module\<module>\Auth\Source\<name>`.
The authentication source must extend the `\SimpleSAML\Auth\Source` class or one of its subclasses.
The "entry point" of an authentication source is the `authenticate()`-function.
Once that function is called, the authentication module can do whatever it wishes to do.
There are only two requirements:
- Never show any pages to the user directly from within the `authenticate()`-function.
(This will lead to problems if the user decides to reload the page.)
- Return control to SimpleSAMLphp after authenticating the user.
If the module is able to authenticate the user without doing any redirects, it should just update the state-array and return.
If the module does a redirect, it must call `\SimpleSAML\Auth\Source::completeAuth()` with the updated state array.
Everything else is up to the module.
If the module needs to redirect the user, for example because it needs to show the user a page asking for credentials, it needs to save the state array.
For that we have the `\SimpleSAML\Auth\State` class.
This is only a convenience class, and you are not required to use it (but its use is encouraged, since it handles some potential pitfalls).
## Saving state
The `\SimpleSAML\Auth\State` class has two functions that you should use:
`saveState($state, $stage)`, and `loadState($id, $stage)`.
The `$stage` parameter must be an unique identifier for the current position in the authentication.
It is used to prevent a malicious user from taking a state you save in one location, and give it to a different location.
The `saveState()`-function returns an id, which you should pass to the `loadState()`-function later.
## Username/password authentication
Since username/password authentication is quite a common operation, a base class has been created for this.
This is the `\SimpleSAML\Module\core\Auth\UserPassBase` class, which is can be found as `modules/core/lib/Auth/UserPassBase.php`.
The only function you need to implement is the `login($username, $password)`-function.
This function receives the username and password the user entered, and is expected to return the attributes of that user.
If the username or password is incorrect, it should throw an error saying so:
throw new \SimpleSAML\Error\Error(\SimpleSAML\Error\ErrorCodes::WRONGUSERPASS);
"[Implementing custom username/password authentication](./simplesamlphp-customauth)" describes how to implement username/password authentication using that base class.
## Generic rules & requirements
- Must be derived from the `\SimpleSAML\Auth\Source`-class.
**Rationale**:
- Deriving all authentication sources from a single base class allows us extend all authentication sources by extending the base class.
- If a constructor is implemented, it must first call the parent constructor, passing along all parameters, before accessing any of the parameters.
In general, only the $config parameter should be accessed when implementing the authentication source.
**Rationale**:
- PHP doesn't automatically call any parent constructor, so it needs to be done manually.
- The `$info`-array is used to provide information to the `\SimpleSAML\Auth\Source` base class, and therefore needs to be included.
- Including the `$config`-array makes it possible to add generic configuration options that are valid for all authentication sources.
- The `authenticate(array &$state)`-function must be implemented.
If this function completes, it is assumed that the user is authenticated, and that the `$state`-array has been updated with the user's attributes.
**Rationale**:
- Allowing the `authenticate()`-function to return after updating the `$state`-array enables us to do authentication without redirecting the user.
This can be used if the authentication doesn't require user input, for example if the authentication can be done based on the IP-address of the user.
- If the `authenticate`-function does not return, it must at a later time call `\SimpleSAML\Auth\Source::completeAuth` with the new state array.
The state array must be an update of the array passed to the `authenticate`-function.
**Rationale**:
- Preserving the same state array allows us to save information in that array before the authentication starts, and restoring it when authentication completes.
- No pages may be shown to the user from the `authenticate()`-function.
Instead, the state should be saved, and the user should be redirected to a new page.
**Rationale**:
- The `authenticate()`-function is called in the context of a different PHP page.
If the user reloads that page, unpredictable results may occur.
- No state information about any authentication should be stored in the authentication source object.
It must instead be stored in the state array.
Any changes to variables in the authentication source object may be lost.
**Rationale**:
- This saves us from having to save the entire authentication object between requests.
Instead, we can recreate it from the configuration.
- The authentication source object must be serializable.
It may be serialized between being constructed and the call to the `authenticate()`-function.
This means that, for example, no database connections should be created in the constructor and later used in the `authenticate()`-function.
**Rationale**:
- If parsing the configuration and creating the authentication object is shown to be a bottleneck, we can cache an initialized authentication source.

2360
plugins/simplesaml/lib/docs/simplesamlphp-changelog-1.x.md Normal file
View File

File diff suppressed because it is too large Load Diff

506
plugins/simplesaml/lib/docs/simplesamlphp-changelog.md Normal file
View File

@@ -0,0 +1,506 @@
# SimpleSAMLphp changelog
[TOC]
This document lists the changes between versions of SimpleSAMLphp.
See the [upgrade notes](https://simplesamlphp.org/docs/stable/simplesamlphp-upgrade-notes.html) for specific information about upgrading.
## Version 2.3.7
Released TBD
## Version 2.3.6
Released 2025-02-17
* Fixed PHP 8.4 deprecation notices
* Fixed infinite recursion (#2367)
* Fixed "Undefined array key" warning in RequestedAuthnContextSelector if no RAC is present in the request
* Fixed an unintended BC-break in `simplesamlphp/assert` that caused composer dependency issues
* Updated several dependencies
* Started testing on PHP 8.4
`ldap`
* Verify attribute value is a string before calling strlen (simplesamlphp/simplesamlphp-module-ldap#64) (v2.4.4)
## Version 2.3.5
Released 2024-12-02
* Fix a regression that would cause the translations for modules to revert to English
## Version 2.3.4
Released 2024-12-02
`Security`
* A security bug was patched in the `saml2-library` that allowed for XXE during the parsing
of SAML2-messages (CVE-2024-52596)
`Other fixes`
* Attributes translations are now in the "attributes" domain (#2328).
* Add `index` directive to Nginx example configuration (#2329).
* Better error message when using legacy endpoints format (#2335).
* Some minor improvements to the changes in 2.3.3.
## Version 2.3.3
Released 2024-11-16
* Fix `st`-language by updating the ICU-files (#2305)
* Fix docs and configuration examples regarding SSO-endpoints.
`admin`
* Fix regression in metadata converter clipboard-button (#2253)
* Fix typo that caused the metadata file-upload to be hidden (#2271)
`discopower`
* Throw a meaningful exception when tags contain illegal characters (v1.4.1)
`ldap`
* Fix a missing negation that rendered multi-ldap broken (v2.3.7)
## Version 2.3.2
Released 2024-09-06
* Fixed a regression that led to fonts & icons not being loaded correctly (#2237)
* Fixed a regression that caused the languages in the language-bar to be all in English.
`admin`
* Only load metadata-converter.js when file-upload is enabled.
## Version 2.3.1
Released 2024-09-05
* Fixed accidental backwards incompatibility for plain-text admin passwords (#2212)
* Fixed support for `pt-br` and `zh-tw` dialects (#2216)
* Run ob_end_clean() on configuration file parsing error (#2219)
* Fixed an incorrect exception message when string-style endpoints are used.
* Reduced all of the overhead logging related to HEAD/OPTIONS requests (#2234).
`admin`
* Fix metadata-viewer to output a valid PHP array
* Fix text-overflow of the metadata-converter output-box
Chores:
* Solved deprecation notices in CI regarding the use of the Twig spaceless-filter (#2229)
## Version 2.3.0
Released 2024-08-20
* The SubjectID authproc-filter now has a new option `hashed`, which if set to true
will automatically hash the unique part of the ID. This will also automatically
make the unique part of the ID in compliance with the specs (#2006)
* Add microsecond support to the FileLoggingHandler (#2084)
* Session ID's are now hashed when stored in a database (#2106)
* Improved HTML 5 compatibility (#2162)
* Fix: preloaded resource not used (#2207)
* BC-break (unintentional): plain-text admin-password are no longer allowed (#2113)
`authorize`
* Feature: allow a user to reauthenticate with a different account (simplesamlphp/simplesamlphp-module-authorize#17) (v1.5.0)
* Feature: show user what account he's using when authorization fails (simplesamlphp/simplesamlphp-module-authorize#20) (v1.6.0)
* Fix: fix faulty translation (v1.6.1)
`consent`
* Update Luxembourgish translations (v1.4.0)
`negotiate`
* Add support for SPNEGO channel binding (v2.3.1)
`sqlauth`
* Add username_regex option - run regular expression over username before querying the
database (simplesamlphp/simplesamlphp-module-sqlauth#11) (v1.3.0)
## Version 2.2.3
Released 2024-08-20
* Added a missing use-statement that would cause a 'class not found' exception.
* Improved Luxembourgish (LB) translations (#2129, #2140)
* Fix regression introduced in v2.2.2 regarding autofilling usernames.
* Restore the possibility to set `trusted.url.domains` to null
* Improved documentation on cachedir-setting (#2153)
* Fix bug in post.twig (#2161)
* Fix MDQ cache file bugs (#2200)
`adfs`
* Fixed metadata download to become a proper xml-file
* Prevent metadata-download from ever being cached
`authorize`
* Fixed logout button (simplesamlphp/simplesamlphp-module-authorize#16) (v1.4.1)
`ldap`
* Fixed a bug that would throw an unhandled exception to the user if they would enter
a non-existing organization and `username_organization_method` is set to `allow` or `force` (v2.3.6).
`metarefresh`
* Fixed incorrect parsing of configuration (v1.2.2)
`radius`
* Fixed security bug known as Blast-Radius (CVE-2024-3596) (simplesamlphp/simplesamlphp-module-radius#10) (v2.0.2)
## Version 2.2.2
:warning: IMPORTANT NOTE :warning:
Due to a mistake, this bugfix-release can turn out to become a backwards-incompatibility for those who override the loginuserpass.twig in their custom theme.
Please update your theme to reflect the changes in [this commit](https://github.com/simplesamlphp/simplesamlphp/pull/2022/commits/691199e9b963a2861d731e6583555c7a8df39992) before updating.
Released 2024-04-30
* Fix regression when setting the host-variable in `saml20-idp-hosted` (was #1922)
* Fix posting the form to the incorrect endpoint when using an authsource based on UserPassOrgBase (#2022)
* Fix RequestedAuthnContextSelector for case with multiple RACs in request
* Add xml opening-tag to SP-metadata for consistency with IdP-metadata (#2048)
* Fixed a PHP 8.3 compliance issue in the logout handler (#2047)
* Improve parsing of base64-encoded strings
* Autofill username when Entra ID hints it in the HTTP parameters
`admin`
* Set custom security header to properly display phpinfo-page
* Hide file-upload button for metadata-converter if uploads are disabled at PHP-level
`exampleauth`
* Fix controller for External-authsource
`ldap`
* Fix exception being thrown when password is empty
`saml2 library`
Fixed a bug where base64 encoded strings were not decoded using the `strict` flag, leading
to an incorrect error message.
`sqlauth`
* Add username_regex option (simplesamlphp/simplesamlphp-module-sqlauth#11) (v1.3.0)
## Version 2.2.1
Released 2014-03-17
* Fix regression in bin/initMDSPdo.php (was #1892)
* Fix regression in translations, causing a fallback to English (#2009 + #2010)
`sqlauth`
* Add multi-query support (simplesamlphp/simplesamlphp-module-sqlauth#9) (v1.2.0)
## Version 2.2.0
Released 2024-03-08
* Make error codes easier to extend (#1870)
* Updated eduPerson attributes in attribute maps (#1948)
* Add regex support for attribute names in AttributeLimit authproc filter (#1971)
* Reverted the .mo files change introduced in 2.1.x
* NOTE: 'core:StatisticsWithAttribute' filter was removed from SimpleSAMLphp, but is still
available from the [statistics](https://github.com/simplesamlphp/simplesamlphp-module-statistics)-module.
It was previously enabled in the default configuration file (config/config.php.dist), so
many lightly configured installations will have it enabled by default. Please check your
config/config.php (and anywhere else you have authprocs configured) that you've either
disabled "core:StatisticsWithAttribute" or migrated to "statistics:StatisticsWithAttribute"
before upgrading to SimpleSAMLphp 2.2.0.
## Version 2.1.4
Released 2024-02-29
* Fix static call for non-static method in bin/importPdoMetadata.php (#1969)
* Validate AuthState before processing it (#1706)
* Fix possible incompatible dependency-set (#1981)
## Version 2.1.3
Released 2024-02-12
* Fix backwards compatibility for mandatory cachedir-setting introduced in 2.1.2
Deprecations:
* The core:StatisticsWithAttribute authproc-filter has been deprecated. It is now available
in the 'statistics' module (v1.2+) as 'statistics:StatisticsWithAttribute', while only the
'core:StatisticsWithAttribute' filter will be removed from SimpleSAMLphp in a future release.
## Version 2.1.2
Released 2024-02-05
* Restore possibility to use HTTP-Artifact on AuthnRequests (regression from 2.0.4)
* Fixed undefined variable exception when using MS SQL store (#1917 + #1918)
* Fix legacy-endpoints to not send responses twice
* Fix exception when using iframe-logout (#1936)
* Look for the schema files in the right place (#1929)
* Fixed file logging handler to not fail on the first write after file-creation (#1877)
* Fixed a warning in the RequestedAuthnContextSelector
`adfs`
* Fixed incorrect use of StreamedResponse (v2.1.3)
`core`
* Fixed a broken template for the WarnShortSSOInterval authproc-filter (#1920)
* Fixed the order of the routes so that the least specific error-controller is hit last (#1923)
`ldap`
* Restored 1.x functionality to be able to fetch operational attributes (v2.3.0)
* Fixed undesirable side-effect introduced in v2.3.0 (v2.3.1)
* Restore the ability to read attributes using a privileged account (v2.3.2)
`saml`
* Disable caching for metadata-endpoint when protect.metadata is true (#1926)
`saml2 library`
* Fix serialization for the NameID element
* Fix inheritance - There is no relation between BaseID and NameID
NOTE: Clear your session store after updating, because old serialized sessions can no longer be unserialized
## Version 2.1.1
Released 2023-11-28
* Fix static call for non-static method in bin/initMDSPdo.php (#1892)
* Restore logout-behaviour for IdP's that do not send a saml:NameID in their LogoutRequest (#1894)
* Fix code error in docs (#1895)
* Fixed a TypeError when accessing the module.php endpoint without specifying a module (#1907)
* Fixed the precondition-functionality for more complex authproc-filters (#1905)
* Reverted a case of 'constructor property promotion' in SAMLParser, causing the validators to be empty (#1904)
* Drop ext-intl in favour of a polyfill (#1908)
`multiauth`
* Fix TypeError due to missing keys in source array (#1900)
## Version 2.1.0
Released 2023-10-30
* Functionality that before was provided by the sanitycheck-module is now implicit.
The module has been archived and should no longer be used. (#1843)
* Add support for conditional authproc-filters (#1836)
* Add support for TLS configuration for Redis Store (#1828)
* Add support for Metadata Deployment Profile for errorURL (#1841)
* Raised minimum Symfony version to 6.0
* Raise minimum PHP version to 8.0
* Specified the allowed HTTP methods for each route
* Our dependency on `composer/composer` was dropped in favour of a packaged phar-file (#1857)
* The `bin/pwgen.php` script was improved to used stronger encryption (#1849)
* Fixed a missing Accept-header for metadata queries (#1865)
* Changed the UNIQUE constraint for the SP LogoutStore database to PRIMARY KEY to
prevent confusing warnings in Drupal (#1862)
* Add Accept HTTP headers to MDQ queries (#1865)
### Chores
* The custom error- and exception handlers were moved to their very own classes (#1858)
## Version 2.0.8
Released 2023-11-28
* Fix static call for non-static method in bin/initMDSPdo.php (#1892)
* Restore logout-behaviour for IdP's that do not send a saml:NameID in their LogoutRequest (#1894)
* Fix code error in docs (#1895)
* Fixed a TypeError when accessing the module.php endpoint without specifying a module (#1907)
* Drop ext-intl in favour of a polyfill (#1908)
`multiauth`
* Fix TypeError due to missing keys in source array (#1900)
## Version 2.0.7
Released 2023-10-30
* Fixed a missing Accept-header for metadata queries (#1865)
* Update vulnerable composer (CVE-2023-43655; not affected)
* Fixed a potential XSS-through-DOM (3x; not affected)
* Fixed a warning in the RequestedAuthnContextSelector
## Version 2.0.6
Released 2023-09-07
* Fixed a legacy endpoint causing to break iframe-logout (#1846)
* Fixed an incorrect return-type in RunnableResponse
* Fix for admin.protectmetadata=true - it would show a blank page
* Fix default for entity attributes NameFormat in XML metadata to be 'URI'.
* Fix error message when invoking SSO endpoint without the required parameters.
* Security header regression
* Fixed a regression that made it impossible to configure metadata-signing on individual hosted IdP's (#1792)
## Version 2.0.5
Released 2023-07-31
* Fixed link pointing to legacy endpoint (#1833)
* Updated German translations (#1814)
* Do not drop UIInfo from SSP array style metadata (#1808)
* Fixed incorrect return types
* Added removeEntry-method to MetadataStorageHandlerPdo (#1823)
* Fixed SLO with signed response (#1812)
* Fixed broken MetaDataStorageHandlerSerialize
* Usernames are now trimmed (#1829)
* Never expose the cron-API if secret is not properly configured (#1831)
* Fixed a bug where IdP-initiated SLO using the HTTP-POST binding wasn't properly dealt with
`admin`
* Updated French translations (#1824)
`cron`
* Log a warning if secret is not properly configured (#1831)
`metarefresh`
* Added support for PDO storage (v0.11.0)
## Version 2.0.4
Released 2023-05-12
* The source that was selected by the SourceSelector is now available in the state.
* The zone that was selected by the SourceIPSelector is now available in the state.
* The defaultSource for the SourceIPSelector can now be set to `null`. If none of the zones
are matched, a NotFound exception will be thrown.
* It is now possible to set a default AuthnContext in the RequestedAuthnContextSelector.
* Fixed a bug in MDQ metadata expiration
* Resolved a possible object injection vulnerability in MDQ metadata cache
* Restored the possibility to use HTTP-Artifact binding on AuthnRequests
* Removed unused private method MetaDataStorageSource::getDynamicHostedUrl (leftover from entityid generation)
* Bumped simplesamlphp-assets-base
`ldap`
* Fixed loading the options-array from configuration (v2.1.6)
* Properly escape user-input in ldap filters (v2.1.7)
`saml2`
* Fixed a static call to a non-static function that caused a broken artifact binding (v4.6.8)
## Version 2.0.3
Released 2023-03-29
* Fix exception when translation-file does not exist
* Correct host in generated URLS for IdPs with 'host' config in admin/federation (#1774, #1781)
* Restore dev-autoloader (#1795)
`authyubikey`
* The module wasn't fully compatible with SSP 2.0 yet (v2.0.1)
`cas`
* Fixed a broken controller (simplesamlphp/simplesamlphp-module-cas#6) (v1.1.2)
`saml2debug`
* Fixed a broken controller (simplesamlphp/simplesamlphp-module-saml2debug#4) (v1.0.5)
## Version 2.0.2
Released 2023-03-10
* Fixed the broken 2.0.1 release by restoring an accidentally removed file
## Version 2.0.1
Released 2023-03-10
* The language-menu on mobile devices was fixed
* Fix some issues with logout (#1776, #1780, #1785)
* The `loginpage_links` functionality for authsources was restored and documented (#1770, #1773)
* Several issues regarding the use of the back-button were fixed (#1720)
* Many fixes in documentation
* Fixed config/authsources.php.dist so you can just rename it for new deployments to get you started (#1771)
* Fixed UTF-8 encoding for metadata output
* Fixed incompatibility with SSP 2.0 for the following modules;
* consent
* consentadmin
* consentsimpleadmin
* exampleattributeserver
* expirycheck
* memcachemonitor
* memcookie
* metaedit
* negotiate
* negotiateext
* preprodwarning
* saml2debug
* sanitycheck
* sqlauth
`authtwitter`
* A legacy route was added for backwards compatibility
* Docs have been updated
`ldap`
* Fixed the possibility to return ALL attributes (simplesamlphp/simplesamlphp-module-ldap#39)
* Restored the possibility to use anonymous bind (simplesamlphp/simplesamlphp-module-ldap#41)
`negotiate`
* Added support for multi-realm environments
`statistics`
* Fixed missing script-tag to load jQuery
* Fixed static calls to SSP utilities
* Docs have been updated
## Version 2.0.0
Released 2023-02-23
* Many changes, upgrades and improvements since the 1.x series.
* Most notably the new templating system based on Twig, a new
localization system based on gettext.
* Most modules have been moved out of the core package but can
easily be installed on-demand as required via composer.
* Better conformance by default to the SAML2INT standard.
* Code cleanups, improvements and simplifications.
* Improved test coverage and more use of standard libraries.
* Compatibility with modern versions of PHP.
* Various new features, including:
* SAML SubjectID and Pairwise ID support
* Accepting unsolicited responses can be disabled by setting `enable_unsolicited` to `false` in the SP authsource.
* Certificates and private keys can now be retrieved from a database
* Support for Redis sentinel was added.
* Please read the upgrade notes for 2.0 because this release breaks
backwards compatibility in a number of places.

416
plugins/simplesaml/lib/docs/simplesamlphp-customauth.md Normal file
View File

@@ -0,0 +1,416 @@
Implementing custom username/password authentication
====================================================
This is a step-by-step guide for creating a custom username/password [authentication source](./simplesamlphp-authsource) for SimpleSAMLphp.
An authentication source is responsible for authenticating the user, typically by getting a username and password, and looking it up in some sort of database.
[TOC]
Create a custom module
----------------------
All custom code for SimpleSAMLphp should be contained in a [module](./simplesamlphp-modules).
This ensures that you can upgrade your SimpleSAMLphp installation without overwriting your own code.
In this example, we will call the module `mymodule`.
It will be located under `modules/mymodule`.
First we need to create the module directory:
```bash
cd modules
mkdir mymodule
```
Now that we have our own module, we can move on to creating an authentication source.
Creating a basic authentication source
--------------------------------------
Authentication sources are implemented using PHP classes.
We are going to create an authentication source named `mymodule:MyAuth`.
It will be implemented in the file `modules/mymodule/src/Auth/Source/MyAuth.php`.
To begin with, we will create a very simple authentication source, where the username and password is hardcoded into the source code.
Create the file `modules/mymodule/src/Auth/Source/MyAuth.php` with the following contents:
```php
<?php
namespace SimpleSAML\Module\mymodule\Auth\Source;
class MyAuth extends \SimpleSAML\Module\core\Auth\UserPassBase
{
protected function login(string $username, string $password): array
{
if ($username !== 'theusername' || $password !== 'thepassword') {
throw new \SimpleSAML\Error\Error(\SimpleSAML\Error\ErrorCodes::WRONGUSERPASS);
}
return [
'uid' => ['theusername'],
'displayName' => ['Some Random User'],
'eduPersonAffiliation' => ['member', 'employee'],
];
}
}
```
Some things to note:
- The classname is `\SimpleSAML\Module\mymodule\Auth\Source\MyAuth`.
This tells SimpleSAMLphp to look for the class in `modules/mymodule/src/Auth/Source/MyAuth.php`.
- Our authentication source subclasses `\SimpleSAML\Module\core\Auth\UserPassBase`.
This is a helper-class that implements much of the common code needed for username/password authentication.
- The `login` function receives the username and password the user enters.
It is expected to authenticate the user.
If the username or password is correct, it must return a set of attributes for the user.
Otherwise, it must throw the `\SimpleSAML\Error\Error('WRONGUSERPASS');` exception.
- Attributes are returned as an associative array of `name => values` pairs.
All attributes can have multiple values, so the values are always stored in an array.
Configuring our authentication source
-------------------------------------
Before we can test our authentication source, we must add an entry for it in `config/authsources.php`.
`config/authsources.php` contains a list of enabled authentication sources.
The entry looks like this:
```php
'myauthinstance' => [
'mymodule:MyAuth',
],
```
You can add it to the beginning of the list, so that the file looks something like this:
```php
<?php
$config = [
'myauthinstance' => [
'mymodule:MyAuth',
],
/* Other authentication sources follow. */
];
```
`myauthinstance` is the name of this instance of the authentication source.
(You are allowed to have multiple instances of an authentication source with different configuration.)
The instance name is used to refer to this authentication source in other configuration files.
The first element of the configuration of the authentication source must be `'mymodule:MyAuth'`.
This tells SimpleSAMLphp to look for the `\SimpleSAML\Module\mymodule\Auth\Source\MyAuth` class.
We also need to enable our new module in `config/config.php`.
`config/config.php` contains a list of enabled modules.
We want to add our new module to the list of other enabled modules. We can add it to the beginning of the list, so the enabled modules section looks something like this:
```php
'module.enable' => [
'mymodule' => true,
/* Other enabled modules follow. */
],
```
Testing our authentication source
---------------------------------
Now that we have configured the authentication source, we can test it by accessing "authentication"-page of the SimpleSAMLphp web interface.
By default, the web interface can be found on `http://yourhostname.com/simplesaml/`.
(Obviously, "yourhostname.com" should be replaced with your real hostname.)
Then select the "Authentication"-tab, and choose "Test configured authentication sources".
You should then receive a list of authentication sources from `config/authsources.php`.
Select `myauthinstance`, and log in using "theusername" as the username, and "thepassword" as the password.
You should then arrive on a page listing the attributes we return from the `login` function.
Next, you should log out by following the log out link.
Using our authentication source in an IdP
-----------------------------------------
To use our new authentication source in an IdP we just need to update the IdP configuration to use it.
Open `metadata/saml20-idp-hosted.php`.
In that file you should locate the `auth`-option for your IdP, and change it to `myauthinstance`:
```php
<?php
/* ... */
$metadata['https://example.org/saml-idp'] = [
/* ... */
/*
* Authentication source to use. Must be one that is configured in
* 'config/authsources.php'.
*/
'auth' => 'myauthinstance',
/* ... */
];
```
You can then test logging in to the IdP.
If you have logged in previously, you may need to log out first.
Adding configuration to our authentication source
-------------------------------------------------
Instead of hardcoding options in our authentication source, they should be configurable.
We are now going to extend our authentication source to allow us to configure the username and password in `config/authsources.php`.
First, we need to define the properties in the class that should hold our configuration:
```php
private $username;
private $password;
```
Next, we create a constructor for the class.
The constructor is responsible for parsing the configuration and storing it in the properties.
```php
public function __construct($info, $config)
{
parent::__construct($info, $config);
if (!is_string($config['username'])) {
throw new Exception('Missing or invalid username option in config.');
}
$this->username = $config['username'];
if (!is_string($config['password'])) {
throw new Exception('Missing or invalid password option in config.');
}
$this->password = $config['password'];
}
```
We can then use the properties in the `login` function.
The complete class file should look like this:
```php
<?php
class MyAuth extends \SimpleSAML\Module\core\Auth\UserPassBase
{
private $username;
private $password;
public function __construct($info, $config)
{
parent::__construct($info, $config);
if (!is_string($config['username'])) {
throw new Exception('Missing or invalid username option in config.');
}
$this->username = $config['username'];
if (!is_string($config['password'])) {
throw new Exception('Missing or invalid password option in config.');
}
$this->password = $config['password'];
}
protected function login(string $username, string $password): array
{
if ($username !== $this->username || $password !== $this->password) {
throw new \SimpleSAML\Error\Error(\SimpleSAML\Error\ErrorCodes::WRONGUSERPASS);
}
return [
'uid' => [$this->username],
'displayName' => ['Some Random User'],
'eduPersonAffiliation' => ['member', 'employee'],
];
}
}
```
We can then update our entry in `config/authsources.php` with the configuration options:
```php
'myauthinstance' => [
'mymodule:MyAuth',
'username' => 'theconfigusername',
'password' => 'theconfigpassword',
],
```
Next, you should go to the "Test configured authentication sources" page again, and test logging in.
Note that we have updated the username & password to "theconfigusername" and "theconfigpassword".
(You may need to log out first before you can log in again.)
A more complete example - custom database authentication
--------------------------------------------------------
The [sqlauth:SQL](./sqlauth:sql) authentication source can do simple authentication against SQL databases.
However, in some cases it cannot be used, for example because the database layout is too complex, or because the password validation routines cannot be implemented in SQL.
What follows is an example of an authentication source that fetches an user from a database, and validates the password using a custom function.
This code assumes that the database contains a table that looks like this:
```sql
CREATE TABLE userdb (
username VARCHAR(32) PRIMARY KEY NOT NULL,
password_hash VARCHAR(64) NOT NULL,
full_name TEXT NOT NULL);
```
An example user (with password "secret"):
```sql
INSERT INTO userdb (username, password_hash, full_name)
VALUES('exampleuser', 'QwVYkvlrAMsXIgULyQ/pDDwDI3dF2aJD4XeVxg==', 'Example User');
```
In this example, the `password_hash` contains a base64 encoded SSHA password.
A SSHA password is created like this:
```php
$password = 'secret';
$numSalt = 8; /* Number of bytes with salt. */
$salt = '';
for ($i = 0; $i < $numSalt; $i++) {
$salt .= chr(mt_rand(0, 255));
}
$digest = sha1($password . $salt, true);
$password_hash = base64_encode($digest . $salt);
```
The class follows:
```php
<?php
class MyAuth extends \SimpleSAML\Module\core\Auth\UserPassBase
{
/* The database DSN.
* See the documentation for the various database drivers for information about the syntax:
* http://www.php.net/manual/en/pdo.drivers.php
*/
private $dsn;
/* The database username, password & options. */
private $username;
private $password;
private $options;
public function __construct($info, $config)
{
parent::__construct($info, $config);
if (!is_string($config['dsn'])) {
throw new Exception('Missing or invalid dsn option in config.');
}
$this->dsn = $config['dsn'];
if (!is_string($config['username'])) {
throw new Exception('Missing or invalid username option in config.');
}
$this->username = $config['username'];
if (!is_string($config['password'])) {
throw new Exception('Missing or invalid password option in config.');
}
$this->password = $config['password'];
if (isset($config['options']) {
if (!is_array($config['options'])) {
throw new Exception('Missing or invalid options option in config.');
}
$this->options = $config['options'];
}
}
/**
* A helper function for validating a password hash.
*
* In this example we check a SSHA-password, where the database
* contains a base64 encoded byte string, where the first 20 bytes
* from the byte string is the SHA1 sum, and the remaining bytes is
* the salt.
*/
private function checkPassword($passwordHash, $password)
{
$passwordHash = base64_decode($passwordHash, true);
if (empty($passwordHash)) {
throw new \InvalidArgumentException("Password hash is empty or not a valid base64 encoded string.");
}
$digest = substr($passwordHash, 0, 20);
$salt = substr($passwordHash, 20);
$checkDigest = sha1($password . $salt, true);
return $digest === $checkDigest;
}
protected function login(string $username, string $password): array
{
/* Connect to the database. */
$db = new PDO($this->dsn, $this->username, $this->password, $this->options);
$db->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION);
/* Ensure that we are operating with UTF-8 encoding.
* This command is for MySQL. Other databases may need different commands.
*/
$db->exec("SET NAMES 'utf8'");
/* With PDO we use prepared statements. This saves us from having to escape
* the username in the database query.
*/
$st = $db->prepare('SELECT username, password_hash, full_name FROM userdb WHERE username=:username');
if (!$st->execute(['username' => $username])) {
throw new Exception('Failed to query database for user.');
}
/* Retrieve the row from the database. */
$row = $st->fetch(PDO::FETCH_ASSOC);
if (!$row) {
/* User not found. */
SimpleSAML\Logger::warning('MyAuth: Could not find user ' . var_export($username, true) . '.');
throw new \SimpleSAML\Error\Error(\SimpleSAML\Error\ErrorCodes::WRONGUSERPASS);
}
/* Check the password. */
if (!$this->checkPassword($row['password_hash'], $password)) {
/* Invalid password. */
SimpleSAML\Logger::warning('MyAuth: Wrong password for user ' . var_export($username, true) . '.');
throw new \SimpleSAML\Error\Error(\SimpleSAML\Error\ErrorCodes::WRONGUSERPASS);
}
/* Create the attribute array of the user. */
$attributes = [
'uid' => [$username],
'displayName' => [$row['full_name']],
'eduPersonAffiliation' => ['member', 'employee'],
];
/* Return the attributes. */
return $attributes;
}
}
```
Configured in `config/authsources.php`:
```php
'myauthinstance' => [
'mymodule:MyAuth',
'dsn' => 'mysql:host=sql.example.org;dbname=userdatabase',
'username' => 'db_username',
'password' => 'secret_db_password',
],
```
And enabled in `config/config.php`:
```php
'module.enable' => [
'mymodule' => true,
/* Other enabled modules follow. */
],
```

101
plugins/simplesaml/lib/docs/simplesamlphp-database.md Normal file
View File

@@ -0,0 +1,101 @@
# SimpleSAML\Database
[TOC]
## Purpose
This document covers the SimpleSAML\Database class and is only relevant to anyone writing code for SimpleSAMLphp, including modules, that require a database connection.
The Database class provides a single class that can be used to connect to a database which can be shared by anything within SimpleSAMLphp.
## Getting Started
If you are just using the already configured database, which would normally be the case, all you need to do is get the global instance of the Database class.
```php
$db = \SimpleSAML\Database::getInstance();
```
If there is a requirement to connect to an alternate database server (ex. authenticating users that exist on a different SQL server or database) you can specify an alternate configuration.
```php
$config = new \SimpleSAML\Configuration($myconfigarray, "mymodule/lib/Auth/Source/myauth.php");
$db = \SimpleSAML\Database::getInstance($config);
```
That will create a new instance of the database, separate from the global instance, specific to the configuration defined in $myconfigarray. If you are going to specify an alternate config, your configuration array must contain the same keys that exist in the primary config (database.dsn, database.username, database.password, database.prefix, etc).
## Database Prefix
Administrators can add a prefix to all the table names that this database classes accesses and you should take that in account when querying. Assuming that a prefix has been configured as "sp_":
```php
$table = $db->applyPrefix("saml20_idp_hosted");
```
$table would be set to "sp_saml20_idp_hosted"
## Querying The Database
You can query the database through two public functions read() and write() which are fairly self-explanitory when it comes to determining which one to use when querying.
### Writing to The Database
Since the database class allows administrators to configure primary and secondary database servers, the write function will always use the primary database connection.
The write function takes 2 parameters: SQL, params.
```php
$table = $db->applyPrefix("test");
$values = [
'id' => 20,
'data' => 'Some data',
];
$query = $db->write("INSERT INTO $table (id, data) VALUES (:id, :data)", $values);
```
The values specified in the $values array will be bound to the placeholders and will be executed on the primary. By default, values are binded as PDO::PARAM_STR. If you need to override this, you can specify it in the values array.
```php
$table = $db->applyPrefix("test");
$values = [
'id' => [20, PDO::PARAM_INT],
'data' => 'Some data',
];
$query = $db->write("INSERT INTO $table (id, data) VALUES (:id, :data)", $values);
```
You can also skip usage of prepared statements. You should **only** use this if you have a statement that has no user input (ex. CREATE TABLE). If the params variable is explicitly set to false, it will skip usage of prepared statements. This is only available when writing to the database.
```php
$table = $db->applyPrefix("test");
$query = $db->write("CREATE TABLE IF NOT EXISTS $table (id INT(16) NOT NULL, data TEXT NOT NULL)", false);
```
### Reading The Database
Since the database class allows administrators to configure primary and secondary database servers, the read function will randomly select a secondary server to query. If no secondaries are configured, it will read from the primary.
The read function takes 2 parameters: SQL, params.
```php
$table = $db->applyPrefix("test");
$values = [
'id' => 20,
];
$query = $db->read("SELECT * FROM $table WHERE id = :id", $values);
```
The values specified in the $values array will be bound to the placeholders and will be executed on the selected secondary. By default, values are binded as PDO::PARAM_STR. If you need to override this, you can specify it in the values array.
```php
$table = $db->applyPrefix("test");
$values = [
'id' => [20, PDO::PARAM_INT],
];
$query = $db->read("SELECT * FROM $table WHERE id = :id", $values);
```

168
plugins/simplesaml/lib/docs/simplesamlphp-developer-information.md Normal file
View File

@@ -0,0 +1,168 @@
# SimpleSAMLphp developer information
<!--
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]
This document is intended to provide an overview of the code for developers.
It should be readable to new developers and developers who contribute as
time allows and may have forgotten some details over time.
## Overview
This is a living document and various sections and additions are being made
as my knowledge of the SSP code and environment expands. Hopefully this can help
others find their way around the code a bit quicker.
The `master` branch is where active development of the next release is
taking place. If you would like to contribute an update to and
existing release please checkout the branch for that release, for
example to make a contribution to the v2.1.1 release you would
checkout the [simplesamlphp-2.1
branch](https://github.com/simplesamlphp/simplesamlphp/tree/simplesamlphp-2.1).
## Libraries that SimpleSAMLphp uses and planned changes
Many dependencies are listed in the require clause of the composer.json such as Symfony, Twig, and simplesamlphp/saml2.
As at early 2024 there is a plan to move from using robrichards/xmlseclibs to using the newly written [xml-security
library](https://github.com/simplesamlphp/xml-security). The integration of xml-security started in the v5 of the saml2 library.
The saml2 library is already a dependency of SimpleSAMLphp and is brought in with composer as a [dependency here.](https://github.com/simplesamlphp/simplesamlphp/blob/15019f97eb1b4041859582b8b6f39fe432b603af/composer.json#L66C21-L66C29).
## Build process
There are two main release targets for each release: slim and full.
This is done by the
[build-release.yml](https://github.com/simplesamlphp/simplesamlphp/blob/master/.github/workflows/build-release.yml)
script. The full version also contains some [simplesamlphp
modules](https://github.com/simplesamlphp/simplesamlphp/blob/master/.github/build/full.json).
The build will also include some files in the vendor directory in the
full build that are not in the slim build.
If the SimpleSAMLphp code relies on other repositories on the [simplesamlphp](https://github.com/simplesamlphp) site then
they are brought in using composer as shown for example for the [saml2 library](https://github.com/simplesamlphp/simplesamlphp/blob/435ce92874a789101495504cd6c4da600fb01334/composer.json#L73).
## Code checks
The github actions perform some linting and checks on the php code.
The linting is done with super-linter and the php checks with phpcs.
You can run the phpcs checks locally by executing `phpcs` in the root
of the git repository. If you would like your simpler issues to be
solved for you execute `phpcbf` which will update the code to remedy
as many issues as it can.
## CSS and common asset setup
The common assets such as CSS in SimpleSAMLphp, for example, that
stored in public/assets/base/css/stylesheet.css comes from the
[simplesamlphp-assets-base](https://github.com/simplesamlphp/simplesamlphp-assets-base)
package.
The dependencies are updated using github actions in
simplesamlphp-assets-base. Select a recent branch such as release-2.2
and dig into the .github directory for details.
## Following a simple login
The `SimpleSAML\Auth\Simple` class takes the authentication_source
name and can be used to find a login URL with `getLoginURL()`. The
getLoginURL method takes the return URL as it's only parameter. The
URL returned from `getLoginURL()` will be a request to module.php and
include the return URL information.
The module.php code `Module::process`. The `process` method uses
Symfony to dispatch the request. This may result in a call to
modules/core/src/Controller/Login.php in `Login::loginuserpass()`. The
code flows through `handleLogin()` which may call
`UserPassBase::handleLogin(authstateid, username, password)`. The
`handleLogin` method looks up the `$as = Auth\Source` and passes the
login credentials to the `$as->login( username, password )` method.
For an SQL based login this would be in
modules/sqlauth/src/Auth/Source/SQL.php and the `SQL::login` method.
This `login` method either returns the user attributes on success or
throws an exception on login failure.
## Documentation
The core of the simplesamlphp.org website is taken from
[simplesamlphp.github.io](https://github.com/simplesamlphp/simplesamlphp.github.io).
The [docs subdirectory](https://simplesamlphp.org/docs/) is built from
the [docs
subdirectory](https://github.com/simplesamlphp/simplesamlphp/tree/master/docs)
of the main repository on github.
### Documentation updates
There are two main repositories for documentation. The website itself
comes from one place and everything that is under the "Documentation"
menu uses another process
<https://simplesamlphp.org/docs/stable/index.html>.
The website lives in <https://github.com/simplesamlphp/simplesamlphp.github.io>
That only has a "release" branch to commit to, which is the website as
it is shown. There you'd commit to change the pages on the website,
e.g. to the page /contrib/
The "docs" repo (as described in the readme of the repo) only contains
the scripts that generate the docs website. In order to improve the
content of the documentation themselves, you commit using the same branches used
for code contributions at
<https://github.com/simplesamlphp/simplesamlphp>.
You can address documentation updates to master
<https://github.com/simplesamlphp/simplesamlphp/tree/master/docs>.
Though it makes sense to backport them to supported releases, so each
version under <https://simplesamlphp.org/docs/VERSION/> will show the
change. In other words, if a documentation change relates to 2.1.3 you
might like to make the pull request against the simplesamlphp-2.1
branch and leave it to the team to also apply it to master and other
branches in the same way that code updates work.
Some docs offered under the `docs` directory on the web site come from modules.
For example the [saml module](https://simplesamlphp.org/docs/2.3/saml/sp.html)
file comes from the file `./modules/saml/docs/sp.md` in the git repository.
### Documentation linting
The CI system has some linting for markdown files in place. This uses
`github-action-markdown-cli` to perform the work which itself uses
`markdownlint-cli`. You can install the latter with npm install and
then setup the rc file from github-action-markdown-cli from
<https://github.com/nosborn/github-action-markdown-cli/blob/master/.markdownlintrc>
to run the linter locally.
For example, with the markdownlintrc from above in a local file you
could use the following if you have not globally installed
markdownlint. The `--fix` option will have markdownlint fix simpler
issues for you so you can concentrate on the document and not the fine
details of the syntax formatting.
```bash
npm install markdownlint-cli
cd ./node_modules/.bin
# copy the markdown lint file to markdownlintrc
./markdownlint -c markdownlintrc /tmp/simplesamlphp-developer-information.md
./markdownlint -c markdownlintrc --fix /tmp/simplesamlphp-developer-information.md
```
You will probably want to make a script or alias to the above command
and apply it before pushing documentation changes to github.
## Making a release
The release process is documented on the wiki
<https://github.com/simplesamlphp/simplesamlphp/wiki/Release-process>.
## Dependbot
The dependbot
<https://docs.github.com/en/code-security/dependabot/dependabot-security-updates/configuring-dependabot-security-updates> runs on the master branch
and creates pull requests with recommended updates.
The release branches are updated automatically as part of the release process.

69
plugins/simplesaml/lib/docs/simplesamlphp-ecp-idp.md Normal file
View File

@@ -0,0 +1,69 @@
# Adding Enhanced Client or Proxy (ECP) Profile support to the IdP
This document describes the necessary steps to enable support for the [SAML V2.0 Enhanced Client or Proxy Profile Version 2.0](http://docs.oasis-open.org/security/saml/Post2.0/saml-ecp/v2.0/cs01/saml-ecp-v2.0-cs01.pdf) on a simpleSAMLphp Identity Provider (IdP).
The SAML V2.0 Enhanced Client or Proxy (ECP) profile is a SSO profile for use with HTTP, and clients with the capability to directly contact a principal's identity provider(s) without requiring discovery and redirection by the service provider, as in the case of a browser. It is particularly useful for desktop or server-side HTTP clients.
## Limitations
* Authentication must be done via [HTTP Basic authentication](https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication#Basic_authentication_scheme).
* Authentication must not require user interaction (e.g. auth filters that require user input).
* Channel Bindings are unsupported.
* "Holder of Key" Subject Confirmation is unsupported.
This feature has been tested to work with Microsoft Office 365, but other service providers may require features of the ECP profile that are currently unsupported!
## Enabling ECP Profile on the IdP
To enable the IdP to send ECP assertions you must add the `saml20.ecp` option to the `saml20-idp-hosted` metadata file:
```php
$metadata['https://example.org/saml-idp'] = [
[....]
'auth' => 'example-userpass',
'saml20.ecp' => true,
];
```
Note: authentication filters that require interaction with the user will not work with ECP.
## Add new metadata to SPs
After enabling the ECP Profile your IdP metadata will change. An additional ECP `SingleSignOnService` endpoint is added.
You therefore need to update the metadata for your IdP at your SPs.
The `saml20-idp-remote` metadata for simpleSAMLphp SPs should contain something like the following code:
```php
'SingleSignOnService' => [
0 => [
'Binding' => 'urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect',
'Location' => 'https://idp.example.org/simplesaml/saml2/idp/SSOService.php',
],
1 => [
'index' => 0,
'Location' => 'https://didp.example.org/simplesaml/saml2/idp/SSOService.php',
'Binding' => 'urn:oasis:names:tc:SAML:2.0:bindings:SOAP',
],
],
```
## SP metadata on the IdP
A SP using the ECP Profile must have an `AssertionConsumerService` endpoint supporting that profile.
This means that you have to use the complex endpoint format in `saml20-sp-remote` metadata.
In general, this should look like the following code:
```php
'AssertionConsumerService' => [
0 => [
'Binding' => 'urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST',
'Location' => 'https://sp.example.org/Shibboleth.sso/SAML2/POST',
'index' => 1,
],
1 => [
'Binding' => 'urn:oasis:names:tc:SAML:2.0:bindings:PAOS',
'Location' => 'https://sp.example.org/ECP',
'index' => 2,
],
],
```

213
plugins/simplesaml/lib/docs/simplesamlphp-errorhandling.md Normal file
View File

@@ -0,0 +1,213 @@
# Exception and error handling in SimpleSAMLphp
[TOC]
This document describes the way errors and exceptions are handled in authentication sources and authentication processing filters.
The basic goal is to be able to throw an exception during authentication, and then have that exception transported back to the SP in a way that the SP understands.
This means that internal SimpleSAMLphp exceptions must be mapped to transport specific error codes for the various transports that are supported by SimpleSAMLphp.
E.g.: When a `\SAML2\Exception\Protocol\NoPassiveException` error is thrown by an authentication processing filter in a SAML 2.0 IdP, we want to map that exception to the `urn:oasis:names:tc:SAML:2.0:status:NoPassive` status code.
That status code should then be returned to the SP.
## Throwing exceptions
How you throw an exception depends on where you want to throw it from.
The simplest case is if you want to throw it during the `authenticate()`-method in an authentication module or during the `process()`-method in a processing filter.
In those methods, you can just throw an exception:
```php
public function process(array &$state): void
{
if ($state['something'] === false) {
throw new \SimpleSAML\Error\Exception('Something is wrong...');
}
}
```
Exceptions thrown at this stage will be caught and delivered to the appropriate error handler.
If you want to throw an exception outside of those methods, i.e. after you have done a redirect, you need to use the `\SimpleSAML\Auth\State::throwException()` function:
```php
<?php
$id = $_REQUEST['StateId'];
$state = \SimpleSAML\Auth\State::loadState($id, 'somestage...');
\SimpleSAML\Auth\State::throwException(
$state,
new \SimpleSAML\Error\Exception('Something is wrong...')
);
```
The `\SimpleSAML\Auth\State::throwException` function will then transfer your exception to the appropriate error handler.
`Note`
Note that we use the `\SimpleSAML\Error\Exception` class in both cases.
This is because the delivery of the exception may require a redirect to a different web page.
In those cases, the exception needs to be serialized.
The normal `Exception` class in PHP isn't always serializable.
If you throw an exception that isn't a subclass of the `\SimpleSAML\Error\Exception` class, your exception will be converted to an instance of `\SimpleSAML\Error\UnserializableException`.
The `\SimpleSAML\Auth\State::throwException` function does not accept any exceptions that does not subclass the `\SimpleSAML\Error\Exception` class.
## Returning specific SAML 2 errors
By default, all thrown exceptions will be converted to a generic SAML 2 error.
In some cases, you may want to convert the exception to a specific SAML 2 status code.
For example, the `\SAML2\Exception\Protocol\NoPassiveException` exception should be converted to a SAML 2 status code with the following properties:
* The top-level status code should be `urn:oasis:names:tc:SAML:2.0:status:Responder`.
* The second-level status code should be `urn:oasis:names:tc:SAML:2.0:status:NoPassive`.
* The status message should contain the cause of the exception.
The `\SimpleSAML\Module\saml\Error` class represents SAML 2 errors.
It represents a SAML 2 status code with three elements: the top-level status code, the second-level status code and the status message.
The second-level status code and the status message is optional, and can be `NULL`.
The `\SimpleSAML\Module\saml\Error` class contains a helper function named `fromException`.
The `fromException()` function is used to return SAML 2 errors to the SP.
The function contains a list which maps various exceptions to specific SAML 2 errors.
If it is unable to convert the exception, it will return a generic SAML 2 error describing the original exception in its status message.
To return a specific SAML 2 error, you should:
* Create a new exception class for your error. This exception class must subclass `\SimpleSAML\Error\Exception`.
* Add that exception to the list in `fromException()`.
* Consider adding the exception to `toException()` in the same file. (See the next section.)
`Note`
While it is possible to throw SAML 2 errors directly from within authentication sources and processing filters, this practice is discouraged.
Throwing SAML 2 errors will tie your code directly to the SAML 2 protocol, and it may be more difficult to use with other protocols.
## Converting SAML 2 errors to normal exceptions
On the SP side, we want to convert SAML 2 errors to SimpleSAMLphp exceptions again.
This is handled by the `toException()` method in `\SimpleSAML\Module\saml\Error`.
The assertion consumer script of the SAML 2 authentication source (`modules/saml2/sp/acs.php`) uses this method.
The result is that generic exceptions are thrown from that authentication source.
For example, `NoPassive` errors will be converted back to instances of `\SAML2\Exception\Protocol\NoPassiveException`.
## Other protocols
The error handling code has not yet been added to other protocols, but the framework should be easy to adapt for other protocols.
To eventually support other protocols was a goal when designing this framework.
## Technical details
This section attempts to describe the internals of the error handling framework.
### `\SimpleSAML\Error\Exception`
The `\SimpleSAML\Error\Exception` class extends the normal PHP `Exception` class.
It makes the exceptions serializable by overriding the `__sleep()` method.
The `__sleep()` method returns all variables in the class which should be serialized when saving the class.
To make sure that the class is serializable, we remove the `$trace` variable from the serialization.
The `$trace` variable contains the full stack trace to the point where the exception was instantiated.
This can be a problem, since the stack trace also contains the parameters to the function calls.
If one of the parameters in unserializable, serialization of the exception will fail.
Since preserving the stack trace can be useful for debugging, we save a variant of the stack trace in the `$backtrace` variable.
This variable can be accessed through the `getBacktrace()` method.
It returns an array with one line of text for each function call in the stack, ending on the point where the exception was created.
#### Note
Since we lose the original `$trace` variable during serialization, PHP will fill it with a new stack trace when the exception is unserialized.
This may be confusing since the new stack trace leads into the `unserialize()` function.
It is therefore recommended to use the getBacktrace() method.
### `\SimpleSAML\Auth\State`
There are two methods in this class that deals with exceptions:
* `throwException($state, $exception)`, which throws an exception.
* `loadExceptionState($id)`, which restores a state containing an exception.
#### `throwException`
This method delivers the exception to the code that initialized the exception handling in the authentication state.
To configure how and where the exception should be delivered, there are two fields in the state-array which can be set:
* `\SimpleSAML\Auth\State::EXCEPTION_HANDLER_FUNC`, in which case the exception will be delivered by a function call to the function specified in that field.
* `\SimpleSAML\Auth\State::EXCEPTION_HANDLER_URL`, in which case the exception will be delivered by a redirect to the URL specified in that field.
If the exception is delivered by a function call, the function will be called with two parameters: The exception and the state array.
If the exception is delivered by a redirect, \SimpleSAML\Auth\State will save the exception in a field in the state array, pass a parameter with the id of the state array to the URL.
The `\SimpleSAML\Auth\State::EXCEPTION_PARAM` constant contains the name of that parameter, while the `\SimpleSAML\Auth\State::EXCEPTION_DATA` constant holds the name of the field where the exception is saved.
#### `loadException`
To retrieve the exception, the application should check for the state parameter in the request, and then retrieve the state array by calling `\SimpleSAML\Auth\State::loadExceptionState()`.
The exception can be located in a field named `\SimpleSAML\Auth\State::EXCEPTION_DATA`.
The following code illustrates this behaviour:
```php
if (array_key_exists(\SimpleSAML\Auth\State::EXCEPTION_PARAM, $_REQUEST)) {
$state = \SimpleSAML\Auth\State::loadExceptionState();
$exception = $state[\SimpleSAML\Auth\State::EXCEPTION_DATA];
/* Process exception. */
}
```
### `\SimpleSAML\Auth\ProcessingChain`
This class requires the caller to add the error handler to the state array before calling the `processState()` function.
Exceptions thrown by the processing filters will be delivered directly to the caller of `processState()` if possible.
However, if one of the filters in the processing chain redirected the user away from the caller, exceptions will be delivered through the error handler saved in the state array.
This is the same behaviour as normal processing filters.
The result will be delivered directly if it is possible, but if not, it will be delivered through a redirect.
The code for handling this becomes something like:
```php
if (array_key_exists(\SimpleSAML\Auth\State::EXCEPTION_PARAM, $_REQUEST)) {
$state = \SimpleSAML\Auth\State::loadExceptionState();
$exception = $state[\SimpleSAML\Auth\State::EXCEPTION_DATA];
/* Handle exception... */
[...]
}
$procChain = [...];
$state = [
'ReturnURL' => \SimpleSAML\Utils\HTTP::getSelfURLNoQuery(),
\SimpleSAML\Auth\State::EXCEPTION_HANDLER_URL => \SimpleSAML\Utils\HTTP::getSelfURLNoQuery(),
[...],
]
try {
$procChain->processState($state);
} catch (\SimpleSAML\Error\Exception $e) {
/* Handle exception. */
[...];
}
#### Note
An exception which isn't a subclass of `\SimpleSAML\Error\Exception` will be converted to the `\SimpleSAML\Error\UnserializedException` class.
This happens regardless of whether the exception is delivered directly or through the error handler.
This is done to be consistent in what the application receives - now it will always receive the same exception, regardless of whether it is delivered directly or through a redirect.
## Custom error show function
Optional custom error show function, called from \SimpleSAML\Error\Error::show, is defined with 'errors.show_function' in config.php.
Example code for this function, which implements the same functionality as \SimpleSAML\Error\Error::show, looks something like:
```php
public static function show(\SimpleSAML\Configuration $config, array $data)
{
$t = new \SimpleSAML\XHTML\Template($config, 'error.twig', 'errors');
$t->data = array_merge($t->data, $data);
$t->send();
exit;
}
```

221
plugins/simplesaml/lib/docs/simplesamlphp-googleapps.md Normal file
View File

@@ -0,0 +1,221 @@
# Setting up a SimpleSAMLphp SAML 2.0 IdP to use with Google Workspace for Education
[TOC]
## Introduction
This article describes how to configure a Google Workspace (formerly G Suite, formerly Google Apps)
instance as a service provider to use with a SimpleSAMLphp identity provider.
This article assumes that you have already read the SimpleSAMLphp installation manual, and installed
a version of SimpleSAMLphp at your server.
In this example we will setup this server as an IdP for Google Workspace:
dev2.andreas.feide.no
## Enabling the Identity Provider functionality
Edit `config.php`, and enable the SAML 2.0 IdP:
```php
'enable.saml20-idp' => true,
```
## Setting up a signing certificate
You must generate a certificate for your IdP.
Here is an example of an openssl command to generate a new key and a self signed certificate to use for signing SAML messages:
```bash
openssl req -newkey rsa:3072 -new -x509 -days 3652 -nodes -out googleworkspaceidp.crt -keyout googleworkspaceidp.pem
```
The certificate above will be valid for 10 years.
Here is an example of typical user input when creating a certificate request:
```bash
Country Name (2 letter code) [AU]:NO
State or Province Name (full name) [Some-State]:Trondheim
Locality Name (eg, city) []:Trondheim
Organization Name (eg, company) [Internet Widgits Pty Ltd]:UNINETT
Organizational Unit Name (eg, section) []:
Common Name (eg, YOUR name) []:dev2.andreas.feide.no
Email Address []:
Please enter the following 'extra' attributes
to be sent with your certificate request
A challenge password []:
An optional company name []:
```
**Note**: SimpleSAMLphp will only work with RSA and not DSA certificates.
## Authentication source
The next step is to configure the way users authenticate on your IdP. Various modules in the `modules/` directory provides methods for authenticating your users. This is an overview of those that are included in the SimpleSAMLphp distribution:
`exampleauth:UserPass`
: Authenticate against a list of usernames and passwords.
`exampleauth:Static`
: Automatically log in as a user with a set of attributes.
[`ldap:LDAP`](/docs/contrib_modules/ldap/ldap.html)
: Authenticates an user to a LDAP server.
For more authentication modules, see [SimpleSAMLphp Identity Provider QuickStart](simplesamlphp-idp).
In this guide, we will use the `exampleauth:UserPass` authentication module. This module does not have any dependencies, and is therefore simple to set up.
After you have successfully tested that everything is working with the simple `exampleauth:UserPass`, you are encouraged to setup SimpleSAMLphp IdP towards your user storage, such as an LDAP directory. (Use the links on the authentication sources above to read more about these setups. `ldap:LDAP` is the most common authentication source.)
## Configuring the authentication source
The `exampleauth:UserPass` authentication module is part of the `exampleauth` module. This module isn't enabled by default, so you will have to enable it. In
`config.php`, search for the `module.enable` key and set `exampleauth` to true:
```php
'module.enable' => [
'exampleauth' => true,
…
],
```
The next step is to create an authentication source with this module. An authentication source is an authentication module with a specific configuration. Each authentication source has a name, which is used to refer to this specific configuration in the IdP configuration. Configuration for authentication sources can be found in `config/authsources.php`.
In this example we will use `example-userpass`, and hence that section is what matters and will be used.
```php
<?php
$config = [
'example-userpass' => [
'exampleauth:UserPass',
'student:studentpass' => [
'uid' => ['student'],
],
'employee:employeepass' => [
'uid' => ['employee'],
],
],
];
```
This configuration creates two users - `student` and `employee`, with the passwords `studentpass` and `employeepass`. The username and password are stored in the array index `student:studentpass` for the `student`-user. The attributes (only `uid` in this example) will be returned by the IdP when the user logs on.
## Configuring metadata for an SAML 2.0 IdP
If you want to setup a SAML 2.0 IdP for Google Workspace, you need to configure two metadata files: `saml20-idp-hosted.php` and `saml20-sp-remote.php`.
### Configuring SAML 2.0 IdP Hosted metadata
This is the configuration of the IdP itself. Here is some example config:
```php
// The SAML entity ID is the index of this config.
$metadata['https://example.org/saml-idp'] = [
// The hostname of the server (VHOST) that this SAML entity will use.
'host' => '__DEFAULT__',
// X.509 key and certificate. Relative to the cert directory.
'privatekey' => 'googleworkspaceidp.pem',
'certificate' => 'googleappsidp.crt',
'auth' => 'example-userpass',
]
```
**Note**: You can only have one entry in the file with host equal to `__DEFAULT__`, therefore you should replace the existing entry with this one, instead of adding this entry as a new entry in the file.
### Configuring SAML 2.0 SP Remote metadata
In the `saml20-sp-remote.php` file we will configure an entry for Google Workspace for Education. There is already an entry for Google Workspace in the template, but we will change the domain name:
```php
/*
* This example shows an example config that works with Google Workspace for education.
* You send the email address that identifies the user from your IdP in the SAML Name ID.
*/
$metadata['https://www.google.com/a/g.feide.no'] = [
'AssertionConsumerService' => 'https://www.google.com/a/g.feide.no/acs',
'NameIDFormat' => 'urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress',
'simplesaml.attributes' => false,
'authproc' => [
1 => [
'class' => 'saml:AttributeNameID',
'identifyingAttribute' => 'mail',
'Format' => 'urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress',
],
],
];
```
You should modify the entityID above and the `AssertionConsumerService` to
include your Google Workspace domain name instead of `g.feide.no`.
(It is also possible to send only the local part of the email address to Google. E.g.
for an e-mail address at GW `student@g.feide.no`, sending an attribute with the
value `student`.)
## Configure Google Workspace
Start by logging in to our Google Workspace for education account panel.
Then select "Advanced tools":
Figure 1. **We go to advanced tools**
![We go to advanced tools](resources/simplesamlphp-googleapps/googleapps-menu.png)
Then select "Set up single sign-on (SSO)":
Figure 2. **We go to setup SSO**
![We go to setup SSO](resources/simplesamlphp-googleapps/googleapps-sso.png)
Upload a certificate, such as the googleworkspaceidp.crt created above:
Figure 3. **Uploading certificate**
![Uploading certificate](resources/simplesamlphp-googleapps/googleapps-cert.png)
Fill out the remaining fields:
The most important field is the Sign-in page URL. You can find the
correct value in your IdP metadata. Browse to your simpleSAMLphp installation,
go to the "Federation" tab, under "SAML 2.0 IdP Metadata" select "show metadata".
You will find in the metadata the XML tag `<md:SingleSignOnService>`
which contains the right URL to input in the field, it will look something
like this:
`https://dev2.andreas.feide.no/simplesaml/saml2/idp/SSOService.php`
The Sign-out page or change password URL can be static pages on your server.
(Google does not support SAML Single Log Out.)
The network mask determines which IP addresses will be asked for SSO login.
IP addresses not matching this mask will be presented with the normal Google Workspace login page.
It is normally best to leave this field empty to enable authentication for all URLs.
Figure 4. **Fill out the remaining fields**
![Fill out the remaining fields](resources/simplesamlphp-googleapps/googleapps-ssoconfig.png)
### Add a user in Google Workspace that is known to the IdP
Before we can test login, a new user must be defined in Google Workspace. This user must have a mail field matching the email from the attribute as described above in the metadata section.
## Test to login to G Suite for education
Go to the URL of your mail account for this domain, the URL is similar to the following:
`http://mail.google.com/a/yourgoogleworkspacedomain.com`
replacing the last part with your own Google Workspace domain name.
## 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](https://simplesamlphp.org/docs/)
* [Join the SimpleSAMLphp user's mailing list](https://simplesamlphp.org/lists)

80
plugins/simplesaml/lib/docs/simplesamlphp-hok-idp.md Normal file
View File

@@ -0,0 +1,80 @@
# Adding Holder-of-Key Web Browser SSO Profile support to the IdP
This document describes the necessary steps to enable support for the [SAML V2.0 Holder-of-Key (HoK) Web Browser SSO Profile](http://docs.oasis-open.org/security/saml/Post2.0/sstc-saml-holder-of-key-browser-sso.pdf)
on a SimpleSAMLphp Identity Provider (IdP).
The SAML V2.0 HoK Web Browser SSO Profile is an alternate version of the standard SAML Web Browser SSO Profile. Its primary benefit is the enhanced security of the SSO process
while preserving maximum compatibility with existing deployments on client and server side.
When using this profile the communication between the user and the IdP is required to be protected by the TLS protocol. Additionally, the user needs a TLS client certificate.
This certificate is usually selfsigned and stored in the certificate store of the browser or the underlying operating system.
## Configuring Apache
The IdP requests a client certificate from the user agent during the TLS handshake. This behaviour is enabled with the following Apache webserver configuration:
```apacheconf
SSLEngine on
SSLCertificateFile /etc/openssl/certs/server.crt
SSLCertificateKeyFile /etc/openssl/private/server.key
SSLVerifyClient optional_no_ca
SSLOptions +ExportCertData
```
If the user agent can successfully prove possession of the private key associated to the public key from the certificate, the received certificate is stored in the
environment variable `SSL_CLIENT_CERT` of the webserver. The IdP embeds the client certificate into the created HoK assertion.
## Enabling HoK SSO Profile on the IdP
To enable the IdP to send HoK assertions you must add the `saml20.hok.assertion` option to the `saml20-idp-hosted` metadata file:
```php
$metadata['https://example.org/saml-idp'] = [
[....]
'auth' => 'example-userpass',
'saml20.hok.assertion' => true,
];
```
## Add new metadata to SPs
After enabling the Holder-of-Key Web Browser SSO Profile your IdP metadata will change. An additional HoK `SingleSignOnService` endpoint is added.
You therefore need to update the metadata for your IdP at your SPs.
The `saml20-idp-remote` metadata for SimpleSAMLphp SPs should contain something like the following code:
```php
'SingleSignOnService' => [
[
'hoksso:ProtocolBinding' => 'urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect',
'Binding' => 'urn:oasis:names:tc:SAML:2.0:profiles:holder-of-key:SSO:browser',
'Location' => 'https://idp.example.org/simplesaml/saml2/idp/SSOService.php',
],
[
'Binding' => 'urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect',
'Location' => 'https://idp.example.org/simplesaml/saml2/idp/SSOService.php',
],
],
```
## SP metadata on the IdP
A SP using the HoK Web Browser SSO Profile must have an `AssertionConsumerService` endpoint supporting that profile.
This means that you have to use the complex endpoint format in `saml20-sp-remote` metadata.
In general, this should look like the following code:
```php
'AssertionConsumerService' => [
[
'Binding' => 'urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST',
'Location' => 'https://sp.example.org/simplesaml/module.php/saml/sp/saml2-acs.php/default-sp',
'index' => 0,
],
[
'Binding' => 'urn:oasis:names:tc:SAML:2.0:profiles:holder-of-key:SSO:browser',
'Location' => 'https://sp.example.org/simplesaml/module.php/saml/sp/saml2-acs.php/default-sp',
'index' => 4,
],
],
```
(The specific values of the various fields will vary depending on the SP.)

40
plugins/simplesaml/lib/docs/simplesamlphp-hok-sp.md Normal file
View File

@@ -0,0 +1,40 @@
Using Holder-of-Key Web Browser SSO Profile on a SimpleSAMLphp SP
=================================================================
This document describes how to enable the [SAML V2.0 Holder-of-Key (HoK) Web Browser SSO Profile](http://docs.oasis-open.org/security/saml/Post2.0/sstc-saml-holder-of-key-browser-sso.pdf)
on a SimpleSAMLphp Service Provider (SP).
The SAML V2.0 HoK Web Browser SSO Profile is an alternate version of the standard SAML Web Browser SSO Profile. Its primary benefit is the enhanced security of the SSO process
while preserving maximum compatibility with existing deployments on client and server side.
When using this profile the communication between the user and the SP is required to be protected by the TLS protocol. Additionally, the user needs a TLS client certificate.
This certificate is usually selfsigned and stored in the certificate store of the browser or the underlying operating system.
Configuring Apache
------------------
The SP requests a client certificate from the user agent during the TLS handshake. This behaviour is enabled with the following Apache webserver configuration:
SSLEngine on
SSLCertificateFile /etc/openssl/certs/server.crt
SSLCertificateKeyFile /etc/openssl/private/server.key
SSLVerifyClient optional_no_ca
SSLOptions +ExportCertData
If the user agent can successfully prove possession of the private key associated to the public key from the certificate, the received certificate is stored in the
environment variable `SSL_CLIENT_CERT` of the webserver.
Enable HoK on SP
----------------
To enable support for the HoK SSO Profile in the SP, the `saml20.hok.assertion` option must be set to TRUE in the SP configuration.
This option can also be enabled in the `saml20-idp-remote` metadata file, but in that case the endpoint will not be added to the SP metadata.
You must also send authentication requests specifying the Holder-of-Key profile to the IdP. This is controlled by the `ProtocolBinding` option in the SP configuration.
'hok-sp' => [
'saml:SP',
'saml20.hok.assertion' => TRUE,
'ProtocolBinding' => 'urn:oasis:names:tc:SAML:2.0:profiles:holder-of-key:SSO:browser',
],
When this is done, you can add the metadata of your SP to the IdP and test the authentication.

85
plugins/simplesaml/lib/docs/simplesamlphp-idp-more.md Normal file
View File

@@ -0,0 +1,85 @@
SimpleSAMLphp Identity Provider Advanced Topics
===============================================
[TOC]
AJAX iFrame Single Log-Out
--------------------------
If you have read about the AJAX iFrame Single Log-Out approach at Andreas' blog and want to enable it, edit your saml20-idp-hosted.php metadata, and add this configuration line for the IdP:
```php
'logouttype' => 'iframe',
```
Attribute Release Consent
-------------------------
The attribute release consent is documented in a [separate document](/docs/contrib_modules/consent/consent.html).
Support for bookmarking the login page
--------------------------------------
Most SAML software crash fatally when users bookmark the login page and return later on when the cached session information is lost. This is natural as the login page happens in the middle of a SAML transaction, and the SAML software needs some references to the original request in order to be able to produce the SAML Response.
SimpleSAMLphp has implemented a graceful fallback to tackle this situation. When SimpleSAMLphp is not able to lookup a session during the login process, it falls back to the *IdP-first flow*, described in the next section, where the reference to the request is not needed.
What happens in the IdP-first flow is that a *SAML unsolicited response* is sent directly to the SP. An *unsolicited response* is a SAML Response with no reference to a SAML Request (no `InReplyTo` field).
When a SimpleSAMLphp IdP falls back to IdP-first flow, the `RelayState` parameter sent by the SP in the SAML request is also lost. The RelayState information contain a reference key for the SP to lookup where to send the user after successful authentication. The SimpleSAMLphp Service Provider supports configuring a static URL to redirect the user after a unsolicited response is received. See more information about the `RelayState` parameter in the next section: *IdP-first flow*.
IdP-first flow
--------------
If you do not want to start the SSO flow at the SP, you may use the IdP-first setup. To do this, redirect the user to the SSOService endpoint on the IdP with a `spentityid` parameter that matches the SP EntityID that the user should be authenticated for.
Here is an example of such a URL:
`https://idp.example.org/simplesaml/saml2/idp/SSOService.php?spentityid=urn:mace:feide.no:someservice`
You can also add a `RelayState` parameter to the IdP-first URL:
`https://idp.example.org/simplesaml/saml2/idp/SSOService.php?spentityid=urn:mace:feide.no:someservice&RelayState=https://sp.example.org/somepage`
The `RelayState` parameter is often used to carry the URL the SP should redirect to after authentication. It is also possible to specify the Assertion
Consumer URL with the `ConsumerURL` parameter.
For compatibility with certain SPs, SimpleSAMLphp will also accept the
`providerId`, `target` and `shire` parameters as aliases for `spentityid`,
`RelayState` and `ConsumerURL`, respectively.
IdP-initiated logout
--------------------
IdP-initiated logout can be initiated by visiting the URL:
`https://idp.example.org/simplesaml/saml2/idp/SingleLogoutService.php?ReturnTo=<URL to return to after logout>`
It will send a logout request to each SP, and afterwards return the user to the URL specified in the `ReturnTo` parameter. Bear in mind that IdPs might disallow redirecting to URLs other than those of their own for security reasons, so in order to get the redirection to work, it might be necessary to ask the IdP to whitelist the URL we are planning to redirect to.
Adding links to the login page
------------------------------
If you want to add some helpful links to the login page, you can add
the following to the `authsources.php` config of the authentication
source you are using:
```php
'example-userpass' => [
...
'core:loginpage_links' => [
[
'href' => 'https://example.com/reset',
'text' => 'Forgot your password?',
],
[
'href' => 'https://example.com/news',
'text' => 'Latest news about us',
],
],
...
],
```
The given text will also be translated via SimpleSAMLphp's translation
system if translations are available in the messages catalog.

251
plugins/simplesaml/lib/docs/simplesamlphp-idp.md Normal file
View File

@@ -0,0 +1,251 @@
# SimpleSAMLphp Identity Provider QuickStart
[TOC]
This guide will describe how to configure SimpleSAMLphp as an identity provider (IdP). You should previously have installed SimpleSAMLphp as described in [the SimpleSAMLphp installation instructions](simplesamlphp-install)
## Enabling the Identity Provider functionality
The first that must be done is to enable the identity provider functionality. This is done by editing `config/config.php`. The option `enable.saml20-idp` controls whether SAML 2.0 IdP support is enabled. Enable it by assigning `true` to them:
```php
'enable.saml20-idp' => true,
```
## Authentication module
The next step is to configure the way users authenticate on your IdP. Various modules in the `modules/` directory provides methods for authenticating your users. This is an overview of those that are included in the SimpleSAMLphp distribution:
[`authcrypt:Hash`](/docs/contrib_modules/authcrypt/authcrypt.html)
: Username & password authentication with hashed passwords.
[`authcrypt:Htpasswd`](/docs/contrib_modules/authcrypt/authcrypt.html)
: Username & password authentication against .htpasswd file.
[`authX509:authX509userCert`](/docs/contrib_modules/authX509/authX509.html)
: Authenticate against a LDAP database with a SSL client certificate.
`exampleauth:UserPass`
: Authenticate against a list of usernames and passwords.
`exampleauth:Static`
: Automatically log in as a user with a set of attributes.
[`ldap:LDAP`](/docs/contrib_modules/ldap/ldap.html)
: Authenticates an user to a LDAP server.
[`ldap:LDAPMulti`](/docs/contrib_modules/ldap/ldap.html)
: Authenticates an user to one of several LDAP server.
The user can choose the LDAP server from a dropdown list.
[`sqlauth:SQL`](/docs/contrib_modules/sqlauth/sql.html)
: Authenticate an user against a database.
[`radius:Radius`](/docs/contrib_modules/radius/radius.html)
: Authenticates an user to a Radius server.
[`multiauth:MultiAuth`](./multiauth:multiauth)
: Allow the user to select from a list of authentication sources.
[`saml:SP`](./saml:sp)
: Authenticate against a SAML IdP. Can be used for bridging.
`authYubiKey:YubiKey`
: Authenticate with [a YubiKey](https://www.yubico.com/products/yubikey/).
[`authtwitter:Twitter`](/docs/contrib_modules/authtwitter/oauthtwitter.html)
: Authenticate with your Twitter account using the Twitter OAuth API.
[`papi:PAPI`](https://github.com/rediris-es/simplesamlphp-module-papi/blob/master/README.md)
: Authenticate by means of the PAPI protocol.
In this guide, we will use the `exampleauth:UserPass` authentication module. This module does not have any dependencies, and is therefore simple to set up.
## Configuring the authentication module
The `exampleauth:UserPass` authentication module is part of the `exampleauth` module. This module isn't enabled by default, so you will have to enable it. In
`config.php`, search for the `module.enable` key and set `exampleauth` to true:
```php
'module.enable' => [
'exampleauth' => true,
…
],
```
The next step is to create an authentication source with this module. An authentication source is an authentication module with a specific configuration. Each authentication source has a name, which is used to refer to this specific configuration in the IdP configuration. Configuration for authentication sources can be found in `config/authsources.php`.
In this setup, this file should contain a single entry:
```php
<?php
$config = [
'example-userpass' => [
'exampleauth:UserPass',
'users' => [
'student:studentpass' => [
'uid' => ['student'],
'eduPersonAffiliation' => ['member', 'student'],
],
'employee:employeepass' => [
'uid' => ['employee'],
'eduPersonAffiliation' => ['member', 'employee'],
],
],
],
];
```
This configuration creates two users - `student` and `employee`, with the passwords `studentpass` and `employeepass`. The username and password are stored in the array index (`student:studentpass` for the `student`-user). The attributes for each user are configured in the array referenced by the index. So for the student user, these are:
```php
[
'uid' => ['student'],
'eduPersonAffiliation' => ['member', 'student'],
],
```
The attributes will be returned by the IdP when the user logs on.
## Creating a self signed certificate
The IdP needs a certificate to sign its SAML assertions with. Here is an example of an `openssl`-command which can be used to generate a new private key key and the corresponding self-signed certificate. The private key and certificate go into the directory defined in the certdir setting (defaults to `cert/`)
This key and certificate can be used to sign SAML messages:
```bash
openssl req -newkey rsa:3072 -new -x509 -days 3652 -nodes -out example.org.crt -keyout example.org.pem
```
The certificate above will be valid for 10 years.
`Note`:
SimpleSAMLphp will only work with RSA certificates. DSA certificates are not supported.
## Configuring the IdP
The SAML 2.0 IdP is configured by the metadata stored in
`metadata/saml20-idp-hosted.php`.
This is a minimal configuration:
```php
<?php
$metadata['https://example.org/saml-idp'] = [
/*
* The hostname for this IdP. This makes it possible to run multiple
* IdPs from the same configuration. '__DEFAULT__' means that this one
* should be used by default.
*/
'host' => '__DEFAULT__',
/*
* The private key and certificate to use when signing responses.
* These can be stored as files in the cert-directory or retrieved
* from a database.
*/
'privatekey' => 'example.org.pem',
'certificate' => 'example.org.crt',
/*
* The authentication source which should be used to authenticate the
* user. This must match one of the entries in config/authsources.php.
*/
'auth' => 'example-userpass',
];
```
For more information about available options in the idp-hosted metadata
files, see the [IdP hosted reference](simplesamlphp-reference-idp-hosted).
## Using the `uri` NameFormat on attributes
The [interoperable SAML 2 profile](https://kantarainitiative.github.io/SAMLprofiles/saml2int.html) specifies that attributes should be delivered using the `urn:oasis:names:tc:SAML:2.0:attrname-format:uri` NameFormat.
We therefore recommended enabling this in new installations.
This can be done by adding the following to the saml20-idp-hosted configuration:
```php
'attributes.NameFormat' => 'urn:oasis:names:tc:SAML:2.0:attrname-format:uri',
'authproc' => [
// Convert LDAP names to oids.
100 => ['class' => 'core:AttributeMap', 'name2oid'],
],
```
## Adding SPs to the IdP
The identity provider you are configuring needs to know about the service providers you are going to connect to it.
This is configured by metadata stored in `metadata/saml20-sp-remote.php`.
This is a minimal example of a `metadata/saml20-sp-remote.php` metadata file for a SimpleSAMLphp SP:
```php
<?php
$metadata['https://sp.example.org/simplesaml/module.php/saml/sp/metadata.php/default-sp'] = [
'AssertionConsumerService' => [
[
'Location' => 'https://sp.example.org/simplesaml/module.php/saml/sp/saml2-acs.php/default-sp',
'Binding' => 'urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST',
],
],
'SingleLogoutService' => [
[
'Location' => 'https://sp.example.org/simplesaml/module.php/saml/sp/saml2-logout.php/default-sp',
'Binding' => 'urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect',
],
],
];
```
Note that the URI in the entityID and the URLs to the AssertionConsumerService and SingleLogoutService endpoints change between different service providers.
If you have the metadata of the remote SP as an XML file, you can use the built-in XML to SimpleSAMLphp metadata converter, which by default is available as `/module.php/admin/federation/metadata-converter` in your SimpleSAMLphp installation.
For more information about available options in the sp-remote metadata files, see the [SP remote reference](simplesamlphp-reference-sp-remote).
## Adding this IdP to other SPs
The method for adding this IdP to a SP varies between different types of SPs. In general, most SPs need some metadata from the IdP. This should be available from `/saml2/idp/metadata.php`.
## Testing the IdP
The simplest way to test the IdP is to configure a SimpleSAMLphp SP
on the same machine. See the instructions for
[configuring SimpleSAMLphp as an SP](simplesamlphp-sp).
`Note`:
When running a SimpleSAMLphp IdP and a SimpleSAMLphp SP on the same computer, the SP and IdP **MUST** be configured with different hostnames. This prevents cookies from the SP to interfere with cookies from the IdP.
## 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](https://simplesamlphp.org/docs/)
- [Join the SimpleSAMLphp user's mailing list](https://simplesamlphp.org/lists)
## IdP-first setup
If you do not want to start the SSO flow at the SP, you may use the IdP-first setup. To do this, redirect the user to the SSOService endpoint on the IdP with one parameter `spentityid` that match the SP EntityId that the user should be logged into.
Here is an example of such a URL:
`https://idp.example.org/simplesaml/saml2/idp/SSOService.php?spentityid=sp.example.org`
If the SP is a SimpleSAMLphp SP, you must also specify a `RelayState` parameter for the SP.
This must be set to a URL the user should be redirected to after authentication.
The `RelayState` parameter can be specified in the [SP configuration](./saml:sp), or it can be sent from the IdP.
To send the RelayState parameter from a SimpleSAMLphp IdP, specify it in the query string to SSOService.php:
`https://idp.example.org/simplesaml/saml2/idp/SSOService.php?spentityid=sp.example.org&RelayState=https://sp.example.org/welcome.php`
To set it in the SP configuration, add it to `authsources.php`:
```php
'default-sp' => [
'saml:SP',
'RelayState' => 'https://sp.example.org/welcome.php',
],
```

94
plugins/simplesaml/lib/docs/simplesamlphp-install-repo.md Normal file
View File

@@ -0,0 +1,94 @@
Installing SimpleSAMLphp from the repository
============================================
These are some notes about running SimpleSAMLphp from the repository.
Prerequisites
-------------
Review the [prerequisites](simplesamlphp-install) from the main installation guide.
Installing from git
-------------------
Go to the directory where you want to install SimpleSAMLphp:
```bash
cd /var
```
The `master` branch is not stable and targets the next major release.
Pick a [tag](https://github.com/simplesamlphp/simplesamlphp/tags) to use.
Then do a git clone:
```bash
git clone --branch <tag_name> https://github.com/simplesamlphp/simplesamlphp.git simplesamlphp
```
Initialize configuration and metadata:
```bash
cd /var/simplesamlphp
cp config/config.php.dist config/config.php
cp config/authsources.php.dist config/authsources.php
cp metadata/saml20-idp-hosted.php.dist metadata/saml20-idp-hosted.php
cp metadata/saml20-idp-remote.php.dist metadata/saml20-idp-remote.php
cp metadata/saml20-sp-remote.php.dist metadata/saml20-sp-remote.php
```
The default config.php has a setting `cachedir` which defaults to
`/var/cache/simplesamlphp`. This directory should exist and be
writable by the web server user. You may like to consider something
like the ACL commands from the [Symfony
website](https://symfony.com/doc/current/setup/file_permissions.html#1-using-acl-on-a-system-that-supports-setfacl-linux-bsd)
to enable access to this cache directory.
Install the external dependencies with Composer (you can refer to
[getcomposer.org](https://getcomposer.org/) to get detailed
instructions on how to install Composer itself):
```bash
php composer.phar install
```
When installing on Windows, use:
```bash
php composer.phar install --ignore-platform-req=ext-posix
```
Upgrading
---------
Go to the root directory of your SimpleSAMLphp installation:
```bash
cd /var/simplesamlphp
```
Ask git to update to update the local repository information:
```bash
git fetch origin
```
If you installed as described above, you will be using a
[tag](https://github.com/simplesamlphp/simplesamlphp/tags) for a
specific release. You can see the current tag you are using and
checkout a newer one with the below commands:
```bash
git branch
* (HEAD detached at v2.2.1)
git checkout v2.2.2
```
Install or upgrade the external dependencies with Composer:
```bash
php composer.phar install
```
When using Windows see the additional options for this composer
command shown at the end of the installation step above.

441
plugins/simplesaml/lib/docs/simplesamlphp-install.md Normal file
View File

@@ -0,0 +1,441 @@
# SimpleSAMLphp Installation and Configuration
[TOC]
This document is part of the SimpleSAMLphp documentation suite.
* [List of all SimpleSAMLphp documentation](https://simplesamlphp.org/docs)
* [SimpleSAMLphp homepage](https://simplesamlphp.org)
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](simplesamlphp-install-repo).
## 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` and `zlib`
* 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`, ...)
* Support for the following PHP packages:
* When saving session information to a Redis server: `predis`
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](https://simplesamlphp.org/download).
Go to the directory where you want to install SimpleSAMLphp and extract the archive file you just downloaded:
```bash
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](simplesamlphp-upgrade-notes) for any relevant
changes.
Extract the new version:
```bash
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):
```bash
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](https://simplesamlphp.org/modules) or [customised the theme](simplesamlphp-theming.md),
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:
```bash
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:
```apacheconf
<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”](simplesamlphp-install#configuration).
Here is an example of how this configuration may look like in `config.php`:
```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](simplesamlphp-maintenance).
## 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:
```nginx
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:
```php
'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.
```php
'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:
```bash
tr -c -d '0123456789abcdefghijklmnopqrstuvwxyz' </dev/urandom | dd bs=32 count=1 2>/dev/null;echo
```
Here is an example of the configuration option:
```php
'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 the `phpsession` data storage, the cookie-related
configuration options are configured in the `session.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:
```php
'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:
```php
'language.default' => 'no',
```
* Set your timezone
```php
'timezone' => 'Europe/Oslo',
```
You can see [a list of Supported Timezones at php.net](http://php.net/manual/en/timezones.php).
## 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:
```php
'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:
![Screenshot of the SimpleSAMLphp installation page.](resources/simplesamlphp-install/screenshot-installationpage.png)
### 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)](simplesamlphp-sp)
* [Remote IdP reference](simplesamlphp-reference-idp-remote)
* [Connecting to the UK Access Federation or InCommon](simplesamlphp-ukaccess)
* [Using SimpleSAMLphp as an Identity Provider (IdP)](simplesamlphp-idp)
* [Hosted IdP reference](simplesamlphp-reference-idp-hosted)
* [Remote SP reference](simplesamlphp-reference-sp-remote)
* [Setting up an IdP for Google Workspace (G Suite / Google Apps)](simplesamlphp-googleapps)
* [Advanced Topics](simplesamlphp-idp-more)
* [Automated Metadata Management](/docs/contrib_modules/metarefresh/simplesamlphp-automated_metadata)
* [Maintenance and configuration](simplesamlphp-maintenance)
## 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.
* [Homepage](https://simplesamlphp.org)
* [Documentation](https://simplesamlphp.org/docs/)
* [Mailing lists](https://simplesamlphp.org/lists)
## 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”](simplesamlphp-install#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.
1. Extract the SimpleSAMLphp archive in your home directory:
```bash
cd ~
tar xzf simplesamlphp-1.x.y.tar.gz
mv simplesamlphp-1.x.y simplesamlphp
```
2. Then you can try to make a symlink into the `public_html` directory.
```bash
cd ~/public_html
ln -s ../simplesamlphp/public simplesaml
```
3. Next, you need to set the `baseurlpath` configuration option with the URL pointing to the `simplesaml` link you
just created in your `public_html` directory. For example, if your home directory is reachable in
`https://host.example/~myaccount/`, set the base URL path accordingly:
```bash
'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:
```bash
cd ~/public_html
mv ../simplesamlphp/public simplesaml
```
Now you have the following directory structure.
* `~/simplesamlphp`
* `~/public_html/simplesaml` where `simplesaml` is the `public` directory from the `simplesamlphp` 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:
```php
require_once(dirname(_FILE__, 2) . '/lib/_autoload.php');
```
to something like:
```php
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.

320
plugins/simplesaml/lib/docs/simplesamlphp-maintenance.md Normal file
View File

@@ -0,0 +1,320 @@
# SimpleSAMLphp Maintenance
[TOC]
## SimpleSAMLphp news and documentation
Please check the following sources of information to stay up to date with regard to SimpleSAMLphp:
* [SimpleSAMLphp documentation](https://simplesamlphp.org/docs)
* [SimpleSAMLphp homepage](https://simplesamlphp.org)
* [SimpleSAMLphp mailing lists](https://simplesamlphp.org/lists)
## Session management
SimpleSAMLphp has an abstraction layer for session management. That means it is possible to choose between different kind of session stores, as well as write new session store plugins.
The `store.type` configuration option in `config.php` allows you to select which method SimpleSAMLphp should use to store the session information. Currently, three session handlers are included in the distribution:
* `phpsession` uses the built in session management in PHP. This is the default, and is simplest to use. It will not work in a load-balanced environment in most configurations.
* `memcache` uses the memcache software to cache sessions in memory. Sessions can be distributed and replicated among several memcache servers, enabling both load-balancing and fail-over.
* `sql` stores the session in an SQL database.
* `redis` stores the session in Redis.
```php
'store.type' => 'phpsession',
```
### Configuring PHP sessions
To use the PHP session handler, set the `store.type` configuration option in `config.php`:
```php
'store.type' => 'phpsession',
```
Keep in mind that **PHP does not allow two sessions to be open at the same time**. This means if you are using PHP sessions both in your
application and in SimpleSAMLphp at the same time, **they need to have different names**. When using the PHP session handler in
SimpleSAMLphp, it is configured with different options than for other session handlers:
```php
'session.phpsession.cookiename' => null,
'session.phpsession.savepath' => null,
'session.phpsession.httponly' => true,
```
Make sure to set `session.phpsession.cookiename` to a name different than the one in use by any other applications. If you are using
SimpleSAMLphp as an Identity Provider, or any other applications using it are not using the default session name, you can use the default
settings by leaving these options unset or setting them to `null`.
If you need to restore your session's application after calling SimpleSAMLphp, you can do it by calling the `cleanup()` method of the
`\SimpleSAML\Session` class, like described [here](simplesamlphp-sp#integrating-authentication-with-your-own-application).
### Configuring memcache
To use the memcache session handler, set the `store.type` parameter in `config.php`:
```php
'store.type' => 'memcache',
```
memcache allows you to store multiple redundant copies of sessions on different memcache servers.
The configuration parameter `memcache_store.servers` is an array of server groups. Every data item will be mirrored in every server group.
Each server group is an array of servers. The data items will be load-balanced between all servers in each server group.
Each server is an array of parameters for the server. The following options are available:
`hostname`:
Host name or ip address where the memcache server runs, or specify other transports like *unix:///path/ssp.sock* to
use UNIX domain sockets. In that case, port will be ignored and forced to *0*.
This is the only required option.
`port`:
Port number of the memcache server. If not set, the `memcache.default_port` ini setting is used. This is 11211 by
default.
The port will be forced to *0* when a UNIX domain socket is specified in *hostname*.
`weight`:
Weight of this server in this server group.
[http://php.net/manual/en/function.Memcache-addServer.php](http://php.net/manual/en/function.Memcache-addServer.php)
has more information about the weight option.
`timeout`:
Timeout for this server. By default, the timeout is 3
seconds.
Here are two examples of configuration of memcache session handling:
### Example 1. Example of redundant configuration with load balancing
Example of redundant configuration with load balancing: This configuration makes it possible to lose both servers in the a-group or both servers in the b-group without losing any sessions. Note that sessions will be lost if one server is lost from both the a-group and the b-group.
```php
'memcache_store.servers' => [
[
['hostname' => 'mc_a1'],
['hostname' => 'mc_a2'],
],
[
['hostname' => 'mc_b1'],
['hostname' => 'mc_b2'],
],
],
```
### Example 2. Example of simple configuration with only one memcache server
Example of simple configuration with only one memcache server, running on the same computer as the web server: Note that all sessions will be lost if the memcache server crashes.
```php
'memcache_store.servers' => [
[
['hostname' => 'localhost'],
],
],
```
The expiration value (`memcache_store.expires`) is the duration for which data should be retained in memcache. Data are dropped from the memcache servers when this time expires. The time will be reset every time the data is written to the memcache servers.
This value should always be larger than the `session.duration` option. Not doing this may result in the session being deleted from the memcache servers while it is still in use.
Set this value to 0 if you don't want data to expire.
`Note`
The oldest data will always be deleted if the memcache server runs
out of storage space.
### Example 3. Example of configuration setting for session expiration
Here is an example of this configuration parameter:
```php
'memcache_store.expires' => 36 * (60*60), // 36 hours.
```
#### Memcache PHP configuration
Configure memcache to not do internal failover. This parameter is
configured in `php.ini`.
```php
memcache.allow_failover = Off
```
#### Environmental configuration
Setup a firewall restricting access to the memcache server.
Because SimpleSAMLphp uses a timestamp to check which session is most recent in a fail-over setup, it is very important to run synchronized clocks on all web servers where you run SimpleSAMLphp.
### Configuring SQL storage
To store session to a SQL database, set the `store.type` option to `sql`.
SimpleSAMLphp uses [PDO](http://www.php.net/manual/en/book.pdo.php) when accessing the database server, so the database source is configured as with a DSN.
The DSN is stored in the `store.sql.dsn` option. See the [PDO driver manual](http://www.php.net/manual/en/pdo.drivers.php) for the DSN syntax used by the different databases.
Username and password for accessing the database can be configured in the `store.sql.username` and `store.sql.password` options.
The required tables are created automatically. If you are storing data from multiple separate SimpleSAMLphp installations in the same database, you can use the `store.sql.prefix` option to prevent conflicts.
### Configuring Redis storage
To store sessions in Redis, set the `store.type` option to `redis`.
By default SimpleSAMLphp will attempt to connect to Redis on the `localhost` at port `6379`. These can be configured via the `store.redis.host` and `store.redis.port` options, respectively. You may also set a key prefix with the `store.redis.prefix` option.
For Redis instances that [require authentication](https://redis.io/commands/auth):
* If authentication is managed with the `requirepass` directive (legacy password protection): use the `store.redis.password` option
* If authentication is managed with [ACL's](https://redis.io/docs/manual/security/acl/) (which are recommended as of Redis 6): use the `store.redis.password` and `store.redis.username` options
#### Redis-Sentinel
If your Redis servers are controlled by [Redis-Sentinel](https://redis.io/docs/manual/sentinel/), then configure your sentinels by setting `store.redis.sentinels` to
```php
[
'tcp://[yoursentinel1]:[port]',
'tcp://[yoursentinel2]:[port]',
'tcp://[yoursentinel3]:[port]',
]
```
If your sentinels are password-protected and use the same password as your Redis servers, then setting `store.redis.password` is enough. However if your sentinels use a different password than that of your Redis servers, then set the password of each sentinel:
```php
[
'tcp://[yoursentinel1]:[port]?password=[password1]',
'tcp://[yoursentinel2]:[port]?password=[password2]',
'tcp://[yoursentinel3]:[port]?password=[password3]',
]
```
Configure your master group by setting `store.redis.mastergroup` (`mymaster` by default).
## Metadata storage
Several metadata storage backends are available by default, including `flatfile`, `directory`, `serialize`, `mdq` and
[`pdo`](https://simplesamlphp.org/docs/stable/simplesamlphp-metadata-pdostoragehandler). Here you have an
example configuration of different metadata sources in use at the same time:
```php
'metadata.sources' => [
['type' => 'flatfile'],
['type' => 'flatfile', 'directory' => 'metadata/metarefresh-kalmar'],
['type' => 'serialize', 'directory' => 'metadata/metarefresh-ukaccess'],
['type' => 'directory'],
['type' => 'directory', 'directory' => 'metadata/somewhere-else'],
],
```
The directory type storage backend will look in subdirectories such as
saml20-idp-hosted.d and saml20-sp-remote.d in the given directory (or
the 'metadatadir' configuration option in 'config.php' by default).
All xml and php files found in those subdirectories will be loaded. It is
currently an error to have subdirectories inside the
saml20-sp-remote.d directories.
You may also implement your own metadata storage handler, in a very similar way to how you would implement
your own session handler. Your class **must** extend the `\SimpleSAML\Metadata\MetaDataStorageSource` class
and override the methods needed to change the backend used. This class **must** also be located in the
`src/MetadataStore/` directory of your custom module.
Bear in mind that **your class name must follow the PSR-4 autoloading standard**. This means it needs to be
properly namespaced. For example, if your module is named `mymodule` and your class is named `MyMetadataHandler`,
you should define it like this:
```php
<?php
namespace SimpleSAML\Module\mymodule\MetadataStore;
class MyMetadataHandler extends \SimpleSAML\Metadata\MetaDataStorageSource
{
...
```
If you would like to see an example of how a custom handler could be implemented in your own module, take
a look at the [cassandrastore](https://github.com/feideconnect/simplesamlphp-module-cassandrastore) module.
## Logging and statistics
SimpleSAMLphp supports standard `syslog` logging. As an
alternative, you may log to flat files.
## Apache configuration
Basic Apache configuration is described in [SimpleSAMLphp Installation](simplesamlphp-install#configuring-apache).
However, your IdP or SP is most likely a valuable website that you want to configure securely. Here are some checks.
* Make sure you use HTTPS with a proper certificate. The best way is to not
serve anything over plain HTTP, except for a possible redirect to https.
* Configure your TLS/SSL to be secure. Mozilla has an easy way to generate
[Recommended Server Configurations](https://wiki.mozilla.org/Security/Server_Side_TLS#Recommended_Server_Configurations).
Verify your SSL settings, e.g. with the [SSLLabs SSLtest](https://www.ssllabs.com/ssltest/).
* In your Apache configuration, add headers that further secure your site.
A good check with hints on what to add is [Mozilla Observatory](https://observatory.mozilla.org/).
## PHP configuration
Secure cookies (if you run HTTPS).
Turn off PHPSESSID in query string.
## Getting ready for production
Here are some checkpoints
1. Remove all entities in metadata files that you do not trust. It is easy to forget about some of the entities that were used for test.
2. If you during testing have been using a certificate that has been exposed (notably: the one found in the SimpleSAMLphp distribution): Obtain and install a new one.
3. Make sure you have installed the latest security upgrades for your OS.
4. Make sure to use HTTPS rather than HTTP.
5. Block access to your servers on anything except port 443. SimpleSAMLphp only uses plain HTTP(S), so there is no need to open ports for SOAP or other communication.
## Error handling, error reporting and metadata reporting
SimpleSAMLphp supports allowing the user when encountering errors to send an e-mail to the administrator. You can turn off this feature in the config.php file.
## Multi-language support
To add support for a new language, add your new language to the `language.available` configuration parameter in `config.php`:
```php
/*
* Languages available and which language is default
*/
'language.available' => ['en', 'no', 'da', 'es', 'xx'],
'language.default' => 'en',
```
Please use the standardized two-character
[language codes as specified in ISO-639-1](http://en.wikipedia.org/wiki/List_of_ISO_639-1_codes).
You also can set the default language. You should ensure that the default language is complete, as it is used as a fallback when a text is not available in the language selected by the user.
All strings that can be localized are found in the files `dictionaries/`. Add a new entry for each string, with your language code, like this:
```php
'user_pass_header' => [
'en' => 'Enter your username and password',
'no' => 'Skriv inn brukernavn og passord',
'xx' => 'Pooa jujjique jamba',
],
```
You can translate as many of the texts as you would like; a full translation is not required unless you want to make this the default language. From the end users point of view, it looks best if all text fragments used in a given screen or form is in one single language.
## Customizing the web frontend with themes
Documentation on theming is moved [to a separate document](simplesamlphp-theming).
### 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](https://simplesamlphp.org/lists)

40
plugins/simplesaml/lib/docs/simplesamlphp-metadata-endpoints.md Normal file
View File

@@ -0,0 +1,40 @@
Metadata endpoints
==================
This document gives a short introduction to the various methods forms metadata endpoints can take in SimpleSAMLphp.
The endpoints we have are:
Endpoint | Indexed | Default binding
-------------------------------|---------|----------------
`ArtifactResolutionService` | Y | SOAP
`AssertionConsumerService` | Y | HTTP-POST
`SingleLogoutService` | N | HTTP-Redirect
`SingleSignOnService` | N | HTTP-Redirect
The various endpoints can be specified in the following format:
'AssertionConsumerService' => [
[
'index' => 1,
'isDefault' => true,
'Location' => 'https://sp.example.org/ACS',
'Binding' => 'urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST',
],
[
'index' => 2,
'Location' => 'https://sp.example.org/ACS',
'Binding' => 'urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Artifact',
],
],
This endpoint format allows for specifying multiple endpoints with different bindings.
It can also be used to specify the ResponseLocation attribute on endpoints, e.g. on `SingleLogoutService`:
'SingleLogoutService' => [
[
'Location' => 'https://sp.example.org/LogoutRequest',
'ResponseLocation' => 'https://sp.example.org/LogoutResponse',
'Binding' => 'urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect',
],
],

135
plugins/simplesaml/lib/docs/simplesamlphp-metadata-extensions-attributes.md Normal file
View File

@@ -0,0 +1,135 @@
SAML V2.0 Metadata Attribute Extensions
=======================================
[TOC]
This is a reference for the SimpleSAMLphp implementation of the [SAML
V2.0 Attribute Extensions](http://docs.oasis-open.org/security/saml/Post2.0/sstc-saml-attribute-ext.pdf)
defined by OASIS. A common use case is adding entity attributes
to the generated metadata.
For an IdP `metadata/saml20-idp-hosted.php` entries are used to define the
metadata extension items; for an SP they can be added to `config/authsources.php`.
An example of this is:
<?php
$metadata['entity-id-1'] = [
/* ... */
'EntityAttributes' => [
'urn:simplesamlphp:v1:simplesamlphp' => ['is', 'really', 'cool'],
'{urn:simplesamlphp:v1}foo' => ['bar'],
],
/* ... */
];
The OASIS specification primarily defines how to include arbitrary
`Attribute` and `Assertion` elements within the metadata for an entity.
*Note*: SimpleSAMLphp does not support `Assertion` elements within the
metadata at this time.
Defining Attributes
-------------------
The `EntityAttributes` key is used to define the attributes in the
metadata. Each item in the `EntityAttributes` array defines a new
`<Attribute>` item in the metadata. The value for each key must be an
array. Each item in this array produces a separate `<AttributeValue>`
element within the `<Attribute>` element.
'EntityAttributes' => [
'urn:simplesamlphp:v1:simplesamlphp' => ['is', 'really', 'cool'],
],
This generates:
<saml:Attribute xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion" Name="urn:simplesamlphp:v1:simplesamlphp" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri">
<saml:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xs="http://www.w3.org/2001/XMLSchema" xsi:type="xs:string">is</saml:AttributeValue>
<saml:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xs="http://www.w3.org/2001/XMLSchema" xsi:type="xs:string">really</saml:AttributeValue>
<saml:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xs="http://www.w3.org/2001/XMLSchema" xsi:type="xs:string">cool</saml:AttributeValue>
</saml:Attribute>
Each `<Attribute>` element requires a `NameFormat` attribute. This is
specified using curly braces at the beginning of the key name:
'EntityAttributes' => [
'{urn:simplesamlphp:v1}foo' => ['bar'],
],
This generates:
<saml:Attribute xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion" Name="foo" NameFormat="urn:simplesamlphp:v1">
<saml:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xs="http://www.w3.org/2001/XMLSchema" xsi:type="xs:string">bar</saml:AttributeValue>
</saml:Attribute>
When the curly braces are omitted, the NameFormat is automatically set
to "urn:oasis:names:tc:SAML:2.0:attrname-format:uri".
Examples
--------
If given the following configuration...
$metadata['https://example.com/saml-idp'] = [
'host' => 'www.example.com',
'certificate' => 'example.com.crt',
'privatekey' => 'example.com.pem',
'auth' => 'example-userpass',
'EntityAttributes' => [
'urn:simplesamlphp:v1:simplesamlphp' => ['is', 'really', 'cool'],
'{urn:simplesamlphp:v1}foo' => ['bar'],
],
];
... will generate the following XML metadata:
<?xml version="1.0"?>
<md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" xmlns:mdattr="urn:oasis:names:tc:SAML:metadata:attribute" xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:mdui="urn:oasis:names:tc:SAML:metadata:ui" xmlns:ds="http://www.w3.org/2000/09/xmldsig#" entityID="https://example.com/saml-idp">
<md:Extensions>
<mdattr:EntityAttributes xmlns:mdattr="urn:oasis:names:tc:SAML:metadata:attribute">
<saml:Attribute xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion" Name="urn:simplesamlphp:v1:simplesamlphp" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri">
<saml:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xs="http://www.w3.org/2001/XMLSchema" xsi:type="xs:string">is</saml:AttributeValue>
<saml:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xs="http://www.w3.org/2001/XMLSchema" xsi:type="xs:string">really</saml:AttributeValue>
<saml:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xs="http://www.w3.org/2001/XMLSchema" xsi:type="xs:string">cool</saml:AttributeValue>
</saml:Attribute>
<saml:Attribute xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion" Name="foo" NameFormat="urn:simplesamlphp:v1">
<saml:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xs="http://www.w3.org/2001/XMLSchema" xsi:type="xs:string">bar</saml:AttributeValue>
</saml:Attribute>
</mdattr:EntityAttributes>
</md:Extensions>
<md:IDPSSODescriptor protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
<md:KeyDescriptor use="signing">
<ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
<ds:X509Data>
...
An example configuration to declare Géant Data Protection Code of Conduct
entity category support for a service provider in `authsources.php`:
'saml:SP' => [
...
'EntityAttributes' => [
'http://macedir.org/entity-category' => [
'http://www.geant.net/uri/dataprotection-code-of-conduct/v1'
]
],
'UIInfo' =>[
'DisplayName' => [
'en' => 'English name',
'es' => 'Nombre en Español',
],
'Description' => [
'en' => 'English description',
'es' => 'Descripción en Español',
],
'InformationURL' => [
'en' => 'http://example.com/info/en',
'es' => 'http://example.com/info/es',
],
'PrivacyStatementURL' => [
'en' => 'http://example.com/privacy/en',
'es' => 'http://example.com/privacy/es',
],
]
],

86
plugins/simplesaml/lib/docs/simplesamlphp-metadata-extensions-rpi.md Normal file
View File

@@ -0,0 +1,86 @@
SAML V2.0 Metadata Extensions for Registration and Publication Information
=============================
[TOC]
This is a reference for the SimpleSAMLphp implementation of the [SAML
V2.0 Metadata Extensions for Registration and Publication Information](http://docs.oasis-open.org/security/saml/Post2.0/saml-metadata-rpi/v1.0/saml-metadata-rpi-v1.0.html)
defined by OASIS.
This extension aims to provide information about the registrars and publishers of the metadata themselves, and it is therefore
available through different endpoints and modules that provide metadata all along SimpleSAMLphp. More specifically, this
extension can be used for:
* metadata published for a [hosted service provider](./saml:sp).
* metadata published for a [hosted identity provider](./simplesamlphp-reference-idp-hosted).
* metadata collected and published by means of the [`aggregator2`](./aggregator2:aggregator2) module.
Currently, only the `<mdrpi:RegistrationInfo>` element is supported.
Depending on the metadata set you want to add this extension to, you will have to configure it on the corresponding
configuration file:
* `metadata/saml20-idp-hosted.php` for hosted identity providers.
* `config/authsources.php` for hosted service providers.
* `config/module_aggregator2.php` for the `aggregator2` module.
RegistrationInfo Items
----------------------
The configuration is the same for all the different files, and consists of a single directive called `RegistrationInfo`, which
**must** be an indexed array with the following options:
`authority`
: A string containing an identifier of the authority who has registered this metadata. This parameter is **mandatory**.
`instant`
: A string containing the instant when the entity or entities where registered by the authority. This parameter is
optional, and must be expressed in the UTC timezone with the *zulu* (`Z`) timezone identifier. If omitted, there will be no
`registrationInstant` in the resulting metadata, except in the `aggregator2` module, which will use the instant when the metadata
was generated.
`policies`
: An indexed array containing URLs pointing to the policy under which the entity or entities where registered. Each
index must be the language code corresponding to the language of the URL. This parameter is optional, and will be omitted in the
resulting metadata if not configured.
Examples
--------
Service Provider:
'default-sp' => [
'saml:SP',
'entityID' => NULL,
...
'RegistrationInfo' => [
'authority' => 'urn:mace:sp.example.org',
'instant' => '2008-01-17T11:28:03.577Z',
'policies' => ['en' => 'http://sp.example.org/policy', 'es' => 'http://sp.example.org/politica'],
],
],
Identity Provider:
$metadata['https://example.org/saml-idp'] = [
'host' => '__DEFAULT__',
...
'RegistrationInfo' => [
'authority' => 'urn:mace:idp.example.org',
'instant' => '2008-01-17T11:28:03.577Z',
],
];
`aggregator2` module:
$config = [
'example.org' => [
'sources' => [
...
],
'RegistrationInfo' => [
'authority' => 'urn:mace:example.federation',
'policies' => ['en' => 'http://example.org/federation_policy', 'es' => 'https://example.org/politica_federacion'],
],
],
];

282
plugins/simplesaml/lib/docs/simplesamlphp-metadata-extensions-ui.md Normal file
View File

@@ -0,0 +1,282 @@
SAML V2.0 Metadata Extensions for Login and Discovery User Interface
=============================
[TOC]
This is a reference for the SimpleSAMLphp implementation of the [SAML
V2.0 Metadata Extensions for Login and Discovery User Interface](http://docs.oasis-open.org/security/saml/Post2.0/sstc-saml-metadata-ui/v1.0/sstc-saml-metadata-ui-v1.0.pdf)
defined by OASIS.
The metadata extensions are available to both IdP and SP usage of
SimpleSAMLphp. For an IdP, the entries are placed in
`metadata/saml20-idp-hosted.php`, for an SP, they are put inside
the relevant entry in `authsources.php`.
An example for an IdP:
<?php
$metadata['entity-id-1'] = [
/* ... */
'UIInfo' => [
'DisplayName' => [
'en' => 'English name',
'es' => 'Nombre en Español',
],
'Description' => [
'en' => 'English description',
'es' => 'Descripción en Español',
],
'InformationURL' => [
'en' => 'http://example.com/info/en',
'es' => 'http://example.com/info/es',
],
'PrivacyStatementURL' => [
'en' => 'http://example.com/privacy/en',
'es' => 'http://example.com/privacy/es',
],
'Keywords' => [
'en' => ['communication', 'federated session'],
'es' => ['comunicación', 'sesión federated'],
],
'Logo' => [
[
'url' => 'http://example.com/logo1.png',
'height' => 200,
'width' => 400,
'lang' => 'en',
],
[
'url' => 'http://example.com/logo2.png',
'height' => 201,
'width' => 401,
],
],
],
'DiscoHints' => [
'IPHint' => ['130.59.0.0/16', '2001:620::0/96'],
'DomainHint' => ['example.com', 'www.example.com'],
'GeolocationHint' => ['geo:47.37328,8.531126', 'geo:19.34343,12.342514'],
],
/* ... */
];
And for an SP it could look like this:
<?php
$config = [
'default-sp' => [
'saml:SP',
'UIInfo' => [
'DisplayName' => [
'en' => 'English name',
'es' => 'Nombre en Español'
],
'Description' => [
'en' => 'English description',
'es' => 'Descripción en Español'
],
],
/* ... */
],
];
The OASIS specification primarily defines how an entity can communicate
metadata related to IdP or service discovery and identification. There
are two different types of
extensions defined. There are the `<mdui:UIInfo>`elements that define
how an IdP or SP should be displayed and there are the `<mdui:DiscoHints>`
elements that define when an IdP should be chosen/displayed.
UIInfo Items
--------------
These elements are used for IdP and SP discovery to determine what to display
about an IdP or SP. These properties are all children of the `UIInfo` key.
*Note*: Most elements are localized strings that specify the language
using the array key as the language-code:
'DisplayName' => [
'en' => 'English name',
'es' => 'Nombre en Español',
],
`DisplayName`
: The localized list of names for this entity
'DisplayName' => [
'en' => 'English name',
'es' => 'Nombre en Español',
],
`Description`
: The localized list of statements used to describe this entity
'Description' => [
'en' => 'English description',
'es' => 'Descripción en Español',
],
`InformationURL`
: A localized list of URLs where more information about the entity is
located.
'InformationURL' => [
'en' => 'http://example.com/info/en',
'es' => 'http://example.com/info/es',
],
`PrivacyStatementURL`
: A localized list of URLs where the entity's privacy statement is
located.
'PrivacyStatementURL' => [
'en' => 'http://example.com/privacy/en',
'es' => 'http://example.com/privacy/es',
],
`Keywords`
: A localized list of keywords used to describe the entity
'Keywords' => [
'en' => ['communication', 'federated session'],
'es' => ['comunicación', 'sesión federated'],
],
: *Note*: The `+` (plus) character is forbidden by specification from
being part of a Keyword.
`Logo`
: The logos used to represent the entity
'Logo' => [
[
'url' => 'http://example.com/logo1.png',
'height' => 200,
'width' => 400,
'lang' => 'en',
],
[
'url' => 'http://example.com/logo2.png',
'height' => 201,
'width' => 401,
],
],
: An optional `lang` key containing a language-code is supported for
localized logos.
DiscoHints Items
--------------
These elements are only relevant when operating in the IdP role; they
assist IdP discovery to determine when to choose or
present an IdP. These properties are all children of the `DiscoHints`
key.
`IPHint`
: This is a list of both IPv4 and IPv6 addresses in CIDR notation
services by or associated with this entity.
'IPHint' => ['130.59.0.0/16', '2001:620::0/96'],
`DomainHint`
: This specifies a list of domain names serviced by or associated with
this entity.
'DomainHint' => ['example.com', 'www.example.com'],
`GeolocationHint`
: This specifies a list of geographic coordinates associated with, or
serviced by, the entity. Coordinates are given in URI form using the
geo URI scheme [RFC5870](http://www.ietf.org/rfc/rfc5870.txt).
'GeolocationHint' => ['geo:47.37328,8.531126', 'geo:19.34343,12.342514'],
Generated XML Metadata Examples
----------------
If given the following configuration...
$metadata['https://example.com/saml-idp'] = [
'host' => 'www.example.com',
'certificate' => 'example.com.crt',
'privatekey' => 'example.com.pem',
'auth' => 'example-userpass',
'UIInfo' => [
'DisplayName' => [
'en' => 'English name',
'es' => 'Nombre en Español',
],
'Description' => [
'en' => 'English description',
'es' => 'Descripción en Español',
],
'InformationURL' => [
'en' => 'http://example.com/info/en',
'es' => 'http://example.com/info/es',
],
'PrivacyStatementURL' => [
'en' => 'http://example.com/privacy/en',
'es' => 'http://example.com/privacy/es',
],
'Keywords' => [
'en' => ['communication', 'federated session'],
'es' => ['comunicación', 'sesión federated'],
],
'Logo' => [
[
'url' => 'http://example.com/logo1.png',
'height' => 200,
'width' => 400,
],
[
'url' => 'http://example.com/logo2.png',
'height' => 201,
'width' => 401,
],
],
],
'DiscoHints' => [
'IPHint' => ['130.59.0.0/16', '2001:620::0/96'],
'DomainHint' => ['example.com', 'www.example.com'],
'GeolocationHint' => ['geo:47.37328,8.531126', 'geo:19.34343,12.342514'],
],
];
... will generate the following XML metadata:
<?xml version="1.0"?>
<md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" xmlns:mdattr="urn:oasis:names:tc:SAML:metadata:attribute" xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:mdui="urn:oasis:names:tc:SAML:metadata:ui" xmlns:ds="http://www.w3.org/2000/09/xmldsig#" entityID="https://example.com/saml-idp">
<md:IDPSSODescriptor protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
<md:Extensions>
<mdui:UIInfo xmlns:mdui="urn:oasis:names:tc:SAML:metadata:ui">
<mdui:DisplayName xml:lang="en">English name</mdui:DisplayName>
<mdui:DisplayName xml:lang="es">Nombre en Espa&#xF1;ol</mdui:DisplayName>
<mdui:Description xml:lang="en">English description</mdui:Description>
<mdui:Description xml:lang="es">Descripci&#xF3;n en Espa&#xF1;ol</mdui:Description>
<mdui:InformationURL xml:lang="en">http://example.com/info/en</mdui:InformationURL>
<mdui:InformationURL xml:lang="es">http://example.com/info/es</mdui:InformationURL>
<mdui:PrivacyStatementURL xml:lang="en">http://example.com/privacy/en</mdui:PrivacyStatementURL>
<mdui:PrivacyStatementURL xml:lang="es">http://example.com/privacy/es</mdui:PrivacyStatementURL>
<mdui:Keywords xml:lang="en">communication federated+session</mdui:Keywords>
<mdui:Keywords xml:lang="es">comunicaci&#xF3;n sesi&#xF3;n+federated</mdui:Keywords>
<mdui:Logo width="400" height="200" xml:lang="en">http://example.com/logo1.png</mdui:Logo>
<mdui:Logo width="401" height="201">http://example.com/logo2.png</mdui:Logo>
</mdui:UIInfo>
<mdui:DiscoHints xmlns:mdui="urn:oasis:names:tc:SAML:metadata:ui">
<mdui:IPHint>130.59.0.0/16</mdui:IPHint>
<mdui:IPHint>2001:620::0/96</mdui:IPHint>
<mdui:DomainHint>example.com</mdui:DomainHint>
<mdui:DomainHint>www.example.com</mdui:DomainHint>
<mdui:GeolocationHint>geo:47.37328,8.531126</mdui:GeolocationHint>
<mdui:GeolocationHint>geo:19.34343,12.342514</mdui:GeolocationHint>
</mdui:DiscoHints>
</md:Extensions>
<md:KeyDescriptor use="signing">
<ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
<ds:X509Data>
...

78
plugins/simplesaml/lib/docs/simplesamlphp-metadata-pdostoragehandler.md Normal file
View File

@@ -0,0 +1,78 @@
PDO Metadata Storage Handler
=============================
<!--
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]
Introduction
------------
If you want to run a clustered SimpleSAMLphp IdP service and you would like to have centralized storage for metadata, you can use the PDO metadata storage handler.
The present document explains how to configure SimpleSAMLphp and your database.
Preparations
------------
You will need to have the appropriate PDO drivers for your database and you will have to configure the database section within the config/config.php file.
Configuring SimpleSAMLphp
-----------------------------
You will first need to configure a PDO metadata source.
```bash
[root@simplesamlphp simplesamlphp]# vi config/config.php
```
Here is an example of flatfile plus PDO:
```php
'metadata.sources' => [
['type' => 'flatfile'],
['type' => 'pdo'],
],
```
Initializing the Database
-------------------------
Once you have configured your metadata sources to include a PDO source, you will need to initialize the database. This process will create tables in the database for each type of metadata set (saml20-idp-hosted, saml20-idp-remote, saml20-sp-remote, etc).
```bash
[root@simplesamlphp simplesamlphp]# php bin/initMDSPdo.php
```
If you connect to your database, you will see 11 new empty tables; one for each metadata set.
Adding Metadata
---------------
With the PDO metadata storage handler, metadata is stored in the table for the appropriate set and is stored in JSON format.
As an example, here is the saml20_idp_hosted table:
entity_id | entity_data
----------------|-------------------------------------------------------------------------------------------------------------------------
`__DEFAULT:1__` | {"host":"\_\_DEFAULT\_\_","privatekey":"idp.key","certificate":"idp.crt","auth":"example-ldap","identifyingAttribute":"uid"}
Another example is the saml20_idp_remote table:
entity_id | entity_data
-------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
`https://openidp.feide.no` | {"name":{"en":"Feide OpenIdP - guest users","no":"Feide Gjestebrukere"},"description":"Here you can login with your account on Feide RnD OpenID. If you do not already have an account on this identity provider, you can create a new one by following the create new account link and follow the instructions.","SingleSignOnService":"https:\/\/openidp.feide.no\/simplesaml\/saml2\/idp\/SSOService.php","SingleLogoutService":"https:\/\/openidp.feide.no\/simplesaml\/saml2\/idp\/SingleLogoutService.php","certFingerprint":"c9ed4dfb07caf13fc21e0fec1572047eb8a7a4cb"}
There is an included script in the `bin` directory that will import all flatfile metadata files and store them in the database, but you can use an external tool to maintain the metadata in the database. This document will only cover adding metadata using the included utility, but the tables above should provide enough information if you would like to create a utility to manage your metadata externally.
To import all flatfile metadata files into the PDO database, run the following script
```bash
[root@simplesamlphp simplesamlphp]# php bin/importPdoMetadata.php
```
In the event that you import a metadata for an entity id that already exists in the database, it will be overwritten.

201
plugins/simplesaml/lib/docs/simplesamlphp-modules.md Normal file
View File

@@ -0,0 +1,201 @@
# SimpleSAMLphp modules
<!--
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]
This document describes how the module system in SimpleSAMLphp
works. It describes what types of modules there are, how they are
configured, and how to write new modules.
## Overview
There are currently three parts of SimpleSAMLphp which can be stored in
modules - authentication sources, authentication processing filters and
themes. There is also support for defining hooks - functions run at
specific times. More than one thing can be stored in a single module.
There is also support for storing supporting files, such as templates
and dictionaries, in modules.
The different functionalities which can be created as modules will be
described in more detail in the following sections; what follows is a
short introduction to what you can do with them:
- Authentication sources implement different methods for
authenticating users, for example simple login forms which
authenticate against a database backend, or login methods which use
client-side certificates.
- Authentication processing filters perform various tasks after the
user is authenticated and has a set of attributes. They can add,
remove and modify attributes, do additional authentication checks,
ask questions of the user, +++.
- Themes allow you to package custom templates for multiple modules
into a single module.
## Module layout
Each SimpleSAMLphp module is stored in a directory under the
`modules`-directory. The module directory contains the following
directories and files:
locales
: This directory contains dictionaries which belong to this
module. To use a dictionary stored in a module, the extended tag
names can be used:
`{<module name>:<dictionary name>:<tag name>}` For
example, `{example:login:hello}` will look up `hello` in
`modules/example/locales/<lang>/login.po`.
: It is also possible to specify
`<module name>:<dictionary name>` as the default
dictionary when instantiating the `\SimpleSAML\XHTML\Template`
class.
hooks
: This directory contains hook functions for this module. Each
file in this directory represents a single function. See the
hook-section in the documentation for more information.
src
: This directory contains classes which belong to this module.
All classes must be named in the following pattern:
`\SimpleSAML\Module\<module name>\<class name>` When looking up the filename of
a class, SimpleSAMLphp will search for `<class name>` in the `src`
directory. Underscores in the class name will be translated into
slashes.
: Thus, if SimpleSAMLphp needs to load a class named
`\SimpleSAML\Module\example\Auth\Source\Example`, it will load the file named
`modules/example/src/Auth/Source/Example.php`.
templates
: These are module-specific templates. To use one of these
templates, specify `<module name>:<template file>.twig`
as the template file in the constructor of
`\SimpleSAML\XHTML\Template`. For example, `example:login-form.twig`
is translated to the file
`modules/example/templates/default/login-form.twig`. Note that
`default` in the previous example is defined by the `theme.use`
configuration option.
themes
: This directory contains themes the module defines. A single
module can define multiple themes, and these themes may override
all templates in all modules. Each subdirectory of `themes` defines
a theme. The theme directory contains a subdirectory for each
module. The templates stored under `simplesamlphp/templates` can be
overridden by a directory named `default`.
: To use a theme provided by a module, the `theme.use`
configuration option should be set to
`<module name>:<theme name>`.
: When using the theme `example:blue`, the template
`templates/default/login.twig` will be overridden by
`modules/example/themes/blue/default/login.twig`, while the template
`modules/core/templates/default/loginuserpass.twig` will be
overridden by
`modules/example/themes/blue/core/loginuserpass.twig`.
public
: All files stored in this directory will be available by
accessing the URL
`https://.../simplesamlphp/module.php/<module name>/<file name>`.
For example, if a script named `login.php` is stored in
`modules/example/public/`, it can be accessed by the URL
`https://.../simplesamlphp/module.php/example/login.php`.
: To retrieve this URL, the
`SimpleSAML\Module::getModuleURL($resource)`-function can be used.
This function takes in a resource on the form `<module>/<file>`.
This function will then return a URL to the given file in the
`public`-directory of `module`.
## Authentication sources
An authentication source is used to authenticate a user and receive a
set of attributes belonging to this user. In a single-signon setup, the
authentication source will only be called once, and the attributes
belonging to the user will be cached until the user logs out.
Authentication sources are defined in `config/authsources.php`. This
file contains an array of `name => configuration` pairs. The name is
used to refer to the authentication source in metadata. When
configuring an IdP to authenticate against an authentication source,
\the `auth` option should be set to this name. The configuration for an
authentication source is an array. The first element in the array
identifies the class which implements the authentication source. The
remaining elements in the array are configuration entries for the
authentication source.
A typical configuration entry for an authentication source looks like
this:
'example-static' => [
/* This maps to modules/exampleauth/src/Auth/Source/Static.php */
'exampleauth:StaticSource',
/* The following is configuration which is passed on to
* the exampleauth:StaticSource authentication source. */
'uid' => 'testuser',
'eduPersonAffiliation' => ['member', 'employee'],
'cn' => ['Test User'],
],
To use this authentication source in a SAML 2.0 IdP, set the
`auth`-option of the IdP to `'example-static'`:
'https://example.org/saml-idp' => [
'host' => '__DEFAULT__',
'privatekey' => 'example.org.pem',
'certificate' => 'example.org.crt',
'auth' => 'example-static',
],
### Creating authentication sources
This is described in a separate document:
- [Creating authentication sources](simplesamlphp-authsource)
## Authentication processing filters
*Authentication processing filters* is explained in a separate document:
- [Authentication processing filters](simplesamlphp-authproc)
## Themes
This feature allows you to collect all your custom templates in one
place. The directory structure is like this:
`modules/<thememodule>/themes/<theme>/<module>/<template>`
`thememodule` is the module where you store your theme, while `theme`
is the name of the theme. A theme is activated by setting the
`theme.use` configuration option to `<thememodule>:<theme>`. `module`
is the module the template belongs to, and `template` is the template
in that module.
For example, `modules/example/themes/test/core/loginuserpass.php`
replaces `modules/core/templates/default/loginuserpass.php`.
`modules/example/themes/test/default/frontpage.php` replaces
`templates/default/frontpage.php`. This theme can be activated by
setting `theme.use` to `example:test`.
## Hook interface
The hook interface allows you to call a hook function in all enabled
modules which define that hook. Hook functions are stored in a
directory called 'hooks' in each module directory. Each hook is
stored in a file named `hook_<hook name>.php`, and each file defines a
function named `<module name>_hook_<hook name>`.
Each hook function accepts a single argument. This argument will be
passed by reference, which allows each hook to update that argument.
For an example of hook usage, see the cron module, which adds a link
to its information page in the Configuration section of the admin
module, through the file `modules/cron/hooks/hook_configpage.php`.

123
plugins/simplesaml/lib/docs/simplesamlphp-nostate.md Normal file
View File

@@ -0,0 +1,123 @@
# Debugging "State Information Lost" errors
**"State Information Lost"** (`\SimpleSAML\Error\NoState: NOSTATE`)
This is one of the most common errors that you can encounter when configuring
SimpleSAMLphp. Unfortunately, it is also a generic error that can have many
possible causes. This document will attempt to describe what this error
actually means, and some of the situations that can cause it.
[TOC]
## What is "state information"?
The "state information" is data that SimpleSAMLphp stores in association with a
request. The request is typically a SAML 2.0 authentication request sent to
the IdP, but it can also be other requests.
This state information is given a random ID, e.g.
"`_2da56e07840b59191d9797442b6b665d67d855cf77`", and is saved in the session of
the user.
## What does it mean that it was lost?
This means that we tried to load state information with a specified ID, but
were unable to find it in the session of the user.
## What can cause it to be lost?
There are several ways that this can happen, but most of them have to do
with session storage. Here we will outline some generic alternatives, and
possible solutions.
### The domain name changed during authentication
The domain name the IdP sends the response to is configured in the metadata of
the IdP. This means that it may not match up with the domain name the user
accessed. For example we may have the following scenario:
1. The user accesses `https://www.example.org/`. A session is created for the user, and the session cookie is set for the current domain (www.example.org).
1. The user needs to be authenticated. We therefore save some information about the current status in the state array, create a SAML 2.0 authentication request, and send it to the IdP.
1. The user logs in on the IdP. The IdP then sends a response to the SP at `example.org`. However, the metadata for the SP that is registered at the IdP uses `https://example.org/` (without `www`) as the domain the response should be sent to. The authentication response is therefore sent to that domain.
1. The SP (now at `https://example.org/`) tries to load the state information associated with the authentication response it received. But, because the domain name has changed, we do not receive the session cookie of the user. We are therefore unable to find the session of the user. When we attempt to load the state information from the session we are therefore unable to find it.
There are several ways to solve this. One of the simplest is often to configure
your webserver to only use one domain, and redirect all accesses to the other
domain to the correct domain.
A different solution is to change the session cookie settings, so that they are
set for the "`example.org`" domain. If you are using PHP sessions, you should
change this in `php.ini`. If not, you should change it with the
'`session.cookie.domain`' option in `config/config.php`. In either case, it should
be set to the top-level domain with a "dot" in front of it. E.g.:
'session.cookie.domain' => '.example.org',
Or in php.ini:
session.cookie_domain = ".example.org"
Note that if you use PHP sessions, you will also have to make sure that your
application uses the same domain when it sets the cookie. How that is done
depends on your application. (See the section about mismatch between
application PHP session settings and SimpleSAMLphp session settings.)
### Hopping between http and https
If a cookie is set during a HTTPS session, it is not available when the same
URL is later accessed over http. If your site is available over both http and
https, check that you're using https consistently throughout the configuration.
The best and most secure is to make your complete site available on https only,
and redirect any http requests to https.
### Mismatch between PHP session settings for the application and SimpleSAMLphp
If both the application you are trying to add SAML 2.0 support to and
SimpleSAMLphp uses PHP session for session storage, and they don't agree on all
the parameters, you can end up with this error. By default, SimpleSAMLphp uses
the settings from `php.ini`, but these can be overridden in `config/config.php`.
If this is the cause of your error, you have two choices: either change
SimpleSAMLphp to use a different session storage method (e.g. memcache or sql),
or change the session settings to match between the application and
SimpleSAMLphp. In many cases it is simplest to adjust the session storage.
If you decide to make the session settings match, you should change the
settings in `php.ini`. This is to make sure that the settings apply to everything
that uses the default settings. The following options in `php.ini` must match the
settings used by the application:
* `session.save_handler`: This is the method that is used to store the session. The default is "`files`".
* `session.save_path`: This is the location the session files are saved. The default depends on your PHP installation.
* `session.name`: This is the name of the session cookie. The default is "`PHPSESSID`".
* `session.cookie_path`: The path that the session cookie is limited to. The default is "`/`", which means that it is available to all pages on your domain.
* `session.cookie_domain`: This is the domain the session cookie is limited to. The default is unset, which makes the cookie available only to the current domain.
What those settings should be set to depends on the application. The simplest
way to determine it may be to look for calls to `session_set_cookie_params` in
the application, and look at what parameters it uses.
### Browsers with SameSite=Lax as default
Some browsers, notably Chrome, will default the cookie SameSite attribute to "Lax" if it
is not set. Specifically in the context of SAML this means that cookies will not be sent
when a POST request is performed between websites, which is typical for the SAML WebSSO
flow. The lack of cookies will cause SimpleSAMLphp's session to be lost when receiving an
assertion via the HTTP-POST binding.
To resolve this, you can set the `session.cookie.samesite` attribute in `config.php`
to `None`. Starting with SimpleSAMLphp 1.19, the config template contains a way to
set this dynamically based on the user's browser support for this attribute.
You also need to enable the `session.cookie.secure` setting.
### A generic problem saving sessions
Sometimes the problem is caused by SimpleSAMLphp being unable to load and/or save
sessions. This can be caused by the session settings being incorrect, or by a
failure of some service required by the session storage. For example, if you
are using memcache for session storage, you need to ensure that the memcache
server is running and that the web server is able to connect to it. The same
applies if you are saving the sessions to a SQL database.
You may want to check your web server error log. If the PHP session handler
fails, it may log an error message there.

455
plugins/simplesaml/lib/docs/simplesamlphp-reference-idp-hosted.md Normal file
View File

@@ -0,0 +1,455 @@
# IdP hosted metadata reference
[TOC]
This is a reference for the metadata file `metadata/saml20-idp-hosted.php`.
The file has the following format:
```php
<?php
/* The index of the array is the entity ID of this IdP. */
$metadata['entity-id-1'] = [
'host' => 'idp.example.org',
/* Configuration options for the first IdP. */
];
$metadata['entity-id-2'] = [
'host' => '__DEFAULT__',
/* Configuration options for the default IdP. */
];
/* ... */
```
The entity ID must be a URI, that is unlikely to change for technical or
political reasons. We recommend it to be a domain name you own.
The URL does not have to resolve to actual content, it's
just an identifier. If your organization's domain is `example.org`:
`https://example.org/saml-idp`
For guidance in picking an entityID, see
[InCommon's best practice](https://spaces.at.internet2.edu/display/federation/saml-metadata-entityid)
on the matter.
The `host` option is the hostname of the IdP, and will be used to
select the correct configuration. One entry in the metadata-list can
have the host `__DEFAULT__`. This entry will be used when no other
entry matches.
## Common options
`auth`
: Which authentication module should be used to authenticate users on
this IdP.
`authproc`
: Used to manipulate attributes, and limit access for each SP. See
the [authentication processing filter manual](simplesamlphp-authproc).
`certificate`
: Location of certificate data which should be used by this IdP, in PEM format.
`contacts`
: Specify contacts in addition to the technical contact configured through config/config.php.
For example, specifying a support contact:
```php
'contacts' => [
[
'contactType' => 'support',
'emailAddress' => 'support@example.org',
'givenName' => 'John',
'surName' => 'Doe',
'telephoneNumber' => '+31(0)12345678',
'company' => 'Example Inc.',
],
],
```
: If you have support for a trust framework that requires extra attributes on the contact person element in your IdP metadata (for example, SIRTFI), you can specify an array of attributes on a contact.
```php
'contacts' => [
[
'contactType' => 'other',
'emailAddress' => 'mailto:abuse@example.org',
'givenName' => 'John',
'surName' => 'Doe',
'telephoneNumber' => '+31(0)12345678',
'company' => 'Example Inc.',
'attributes' => [
'xmlns:remd' => 'http://refeds.org/metadata',
'remd:contactType' => 'http://refeds.org/metadata/contactType/security',
],
],
],
```
`errorURL`
: Overrides the errorURL in the IDP's published metadata.
`host`
: The hostname for this IdP. One IdP can also have the `host`-option
set to `__DEFAULT__`, and that IdP will be used when no other
entries in the metadata matches.
`logouttype`
: The logout handler to use. Either `iframe` or `traditional`. `traditional` is the default.
`OrganizationName`, `OrganizationDisplayName`, `OrganizationURL`
: The name and URL of the organization responsible for this IdP.
You need to either specify *all three* or none of these options.
: The Name does not need to be suitable for display to end users, the DisplayName should be.
The URL is a website the user can access for more information about the organization.
: This option can be translated into multiple languages by specifying the value as an array of language-code to translated name:
```php
'OrganizationName' => [
'en' => 'Voorbeeld Organisatie Foundation b.a.',
'nl' => 'Stichting Voorbeeld Organisatie b.a.',
],
'OrganizationDisplayName' => [
'en' => 'Example organization',
'nl' => 'Voorbeeldorganisatie',
],
'OrganizationURL' => [
'en' => 'https://example.com',
'nl' => 'https://example.com/nl',
],
```
`privatekey`
: Location of private key data for this IdP, in PEM format.
`privatekey_pass`
: Passphrase for the private key. Leave this option out if the
private key is unencrypted.
`scope`
: An array with scopes for this IdP.
The scopes will be added to the generated XML metadata.
A scope can either be a domain name or a regular expression
matching a number of domains.
## SAML 2.0 options
The following SAML 2.0 options are available:
`assertion.encryption`
: Whether assertions sent from this IdP should be encrypted. The default
value is `FALSE`.
: Note that this option can be set for each SP in the SP-remote metadata.
`attributeencodings`
: What encoding should be used for the different attributes. This is
an array which maps attribute names to attribute encodings. There
are three different encodings:
: - `string`: Will include the attribute as a normal string. This is
the default.
: - `base64`: Store the attribute as a base64 encoded string.
: - `raw`: Store the attribute without any modifications. This
makes it possible to include raw XML in the response.
: Note that this option also exists in the SP-remote metadata, and
any value in the SP-remote metadata overrides the one configured
in the IdP metadata.
`attributes.NameFormat`
: What value will be set in the Format field of attribute
statements. This parameter can be configured multiple places, and
the actual value used is fetched from metadata by the following
priority:
: 1. SP Remote Metadata
: 2. IdP Hosted Metadata
: The default value is:
`urn:oasis:names:tc:SAML:2.0:attrname-format:uri`
: Some examples of values specified in the SAML 2.0 Core
Specification:
: - `urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified`
: - `urn:oasis:names:tc:SAML:2.0:attrname-format:uri` (The default
in Shibboleth 2.0, mandatory as per SAML2INT)
: - `urn:oasis:names:tc:SAML:2.0:attrname-format:basic` (The
default in Sun Access Manager)
: You can also define your own value.
: Note that this option also exists in the SP-remote metadata, and
any value in the SP-remote metadata overrides the one configured
in the IdP metadata.
`encryption.blacklisted-algorithms`
: Blacklisted encryption algorithms. This is an array containing the algorithm identifiers.
: Note that this option can be set for each SP in the [SP-remote metadata](./simplesamlphp-reference-sp-remote).
: The RSA encryption algorithm with PKCS#1 v1.5 padding is blacklisted by default for security reasons. Any assertions
encrypted with this algorithm will therefore fail to decrypt. You can override this limitation by defining an empty
array in this option (or blacklisting any other algorithms not including that one). However, it is strongly
discouraged to do so. For your own safety, please include the string 'http://www.w3.org/2001/04/xmlenc#rsa-1_5' if
you make use of this option.
`https.certificate`
: The certificate used by the webserver when handling connections.
This certificate will be added to the generated metadata of the IdP,
which is required by some SPs when using the HTTP-Artifact binding.
`nameid.encryption`
: Whether NameIDs sent from this IdP should be encrypted. The default
value is `FALSE`.
: Note that this option can be set for each SP in the [SP-remote metadata](./simplesamlphp-reference-sp-remote).
`NameIDFormat`
: The format(s) of the NameID supported by this IdP, as either an array or a string. If an array is given, the first
value is used as the default if the incoming request does not specify a preference. Defaults to the `transient`
format if unspecified.
: This parameter can be configured in multiple places, and the actual value used is fetched from metadata with
the following priority:
: 1. SP Remote Metadata
: 2. IdP Hosted Metadata
: The three most commonly used values are:
: 1. `urn:oasis:names:tc:SAML:2.0:nameid-format:transient`
: 2. `urn:oasis:names:tc:SAML:2.0:nameid-format:persistent`
: 3. `urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress`
: The `transient` format will generate a new unique ID every time
the user logs in.
: To properly support the `persistent` and `emailAddress` formats,
you should configure [NameID generation filters](./saml:nameid)
on your IdP.
: Note that the value(s) set here will be added to the metadata generated for this IdP,
in the `NameIDFormat` element.
`RegistrationInfo`
: Allows to specify information about the registrar of this SP. Please refer to the
[MDRPI extension](./simplesamlphp-metadata-extensions-rpi) document for further information.
`saml20.ecp`
: Set to `true` to enable the IdP to receive AuthnRequests and send responses according the Enhanced Client or Proxy (ECP) Profile. Note: authentication filters that require interaction with the user will not work with ECP.
Defaults to `false`.
`saml20.hok.assertion`
: Set to `TRUE` to enable the IdP to send responses according the [Holder-of-Key Web Browser SSO Profile](./simplesamlphp-hok-idp).
Defaults to `FALSE`.
`saml20.sendartifact`
: Set to `TRUE` to enable the IdP to send responses with the HTTP-Artifact binding.
Defaults to `FALSE`.
: Note that this requires a configured memcache server.
`saml20.sign.assertion`
: Whether `<saml:Assertion>` elements should be signed.
Defaults to `TRUE`.
: Note that this option also exists in the SP-remote metadata, and
any value in the SP-remote metadata overrides the one configured
in the IdP metadata.
`saml20.sign.response`
: Whether `<samlp:Response>` messages should be signed.
Defaults to `TRUE`.
: Note that this option also exists in the SP-remote metadata, and
any value in the SP-remote metadata overrides the one configured
in the IdP metadata.
`signature.algorithm`
: The algorithm to use when signing any message generated by this identity provider. Defaults to RSA-SHA256.
: Possible values:
* `http://www.w3.org/2000/09/xmldsig#rsa-sha1`
*Note*: the use of SHA1 is **deprecated** and will be disallowed in the future.
* `http://www.w3.org/2001/04/xmldsig-more#rsa-sha256`
The default.
* `http://www.w3.org/2001/04/xmldsig-more#rsa-sha384`
* `http://www.w3.org/2001/04/xmldsig-more#rsa-sha512`
`sign.logout`
: Whether to sign logout messages sent from this IdP.
: Note that this option also exists in the SP-remote metadata, and
any value in the SP-remote metadata overrides the one configured
in the IdP metadata.
`SingleSignOnService`
: Override the default URL for the SingleSignOnService for this
IdP. This is an absolute URL. The default value is
`<SimpleSAMLphp-root>/module.php/saml/idp/singleSignOnService`
: Note that this only changes the values in the generated
metadata and in the messages sent to others. You must also
configure your webserver to deliver this URL to the correct PHP
page.
`SingleSignOnServiceBinding`
: List of SingleSignOnService bindings that the IdP will claim support for.
: Possible values:
* `urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect`
* `urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST`
: Defaults to HTTP-Redirect binding. Please note that the order
specified will be kept in the metadata, making the first binding
the default one.
`SingleLogoutService`
: Override the default URL for the SingleLogoutService for this
IdP. This is an absolute URL. The default value is
`<SimpleSAMLphp-root>/module.php/saml/idp/singleLogout`
: Note that this only changes the values in the generated
metadata and in the messages sent to others. You must also
configure your webserver to deliver this URL to the correct PHP
page.
`SingleLogoutServiceBinding`
: List of SingleLogoutService bindings the IdP will claim support for.
: Possible values:
* `urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect`
* `urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST`
: Defaults to HTTP-Redirect binding. Please note that the order
specified will be kept in the metadata, making the first binding
the default one.
`validate.authnrequest`
: Whether we require signatures on authentication requests sent to this IdP.
Set it to:
: true: authnrequest must be signed (and signature will be validated)
: null: authnrequest may be signed, if it is, signature will be validated
: false: authnrequest signature is never checked
: Note that this option also exists in the SP-remote metadata, and
any value in the SP-remote metadata overrides the one configured
in the IdP metadata.
`validate.logout`
: Whether we require signatures on logout messages sent to this IdP.
: Note that this option also exists in the SP-remote metadata, and
any value in the SP-remote metadata overrides the one configured
in the IdP metadata.
### Fields for signing and validating messages
SimpleSAMLphp only signs authentication responses by default.
Signing of logout requests and logout responses can be enabled by
setting the `redirect.sign` option. Validation of received messages
can be enabled by the `redirect.validate` option.
These options set the default for this IdP, but options for each SP
can be set in `saml20-sp-remote`. Note that you need to add a
certificate for each SP to be able to validate signatures on
messages from that SP.
`redirect.sign`
: Whether logout requests and logout responses sent from this IdP
should be signed. The default is `FALSE`.
`redirect.validate`
: Whether authentication requests, logout requests and logout
responses received sent from this IdP should be validated. The
default is `FALSE`
**Example: Configuration for signed messages**:
```php
'redirect.sign' => true,
```
## Metadata extensions
SimpleSAMLphp supports generating metadata with the MDUI, MDRPI and EntityAttributes metadata extensions.
See the documentation for those extensions for more details:
* [MDUI extension](./simplesamlphp-metadata-extensions-ui)
* [MDRPI extension](./simplesamlphp-metadata-extensions-rpi)
* [EntityAttributes](./simplesamlphp-metadata-extensions-attributes)
For other metadata extensions, you can use the `saml:Extensions` option:
`saml:Extensions`
: An array of `\SAML2\XML\Chunk`s to include in the IdP metadata extensions, at the same level as `EntityAttributes`.
`Examples`:
These are some examples of IdP metadata
### Minimal SAML 2.0 IdP
```php
<?php
$metadata['https://example.org/saml-idp'] = [
/*
* We use '__DEFAULT__' as the hostname so we won't have to
* enter a hostname.
*/
'host' => '__DEFAULT__',
/* The private key and certificate used by this IdP. */
'certificate' => 'example.org.crt',
'privatekey' => 'example.org.pem',
/*
* The authentication source for this IdP. Must be one
* from config/authsources.php.
*/
'auth' => 'example-userpass',
];
```
### A custom metadata extension (eduGAIN republish request)
```php
<?php
$dom = \SAML2\DOMDocumentFactory::create();
$republishRequest = $dom->createElementNS('http://eduid.cz/schema/metadata/1.0', 'eduidmd:RepublishRequest');
$republishTarget = $dom->createElementNS('http://eduid.cz/schema/metadata/1.0', 'eduidmd:RepublishTarget', 'http://edugain.org/');
$republishRequest->appendChild($republishTarget);
$ext = [new \SAML2\XML\Chunk($republishRequest)];
$metadata['https://example.org/saml-idp'] = [
'host' => '__DEFAULT__',
'certificate' => 'example.org.crt',
'privatekey' => 'example.org.pem',
'auth' => 'example-userpass',
/*
* The custom metadata extensions.
*/
'saml:Extensions' => $ext,
];
```
this generates the following metadata:
```xml
<EntityDescriptor entityID="...">
<Extensions xmlns="urn:oasis:names:tc:SAML:2.0:metadata">
<eduidmd:RepublishRequest xmlns:eduidmd="http://eduid.cz/schema/metadata/1.0">
<eduidmd:RepublishTarget>http://edugain.org/</eduidmd:RepublishTarget>
</eduidmd:RepublishRequest>
</Extensions>
<!-- rest of metadata -->
</EntityDescriptor>
```

245
plugins/simplesaml/lib/docs/simplesamlphp-reference-idp-remote.md Normal file
View File

@@ -0,0 +1,245 @@
# IdP remote metadata reference
[TOC]
This is a reference for metadata options available for `metadata/saml20-idp-remote.php`. The file has the following format:
```php
<?php
/* The index of the array is the entity ID of this IdP. */
$metadata['entity-id-1'] = [
/* Configuration options for the first IdP. */
];
$metadata['entity-id-2'] = [
/* Configuration options for the second IdP. */
];
/* ... */
```
## Options
`AuthnContextClassRef`
: The AuthnContextClassRef that will be sent in the login request.
: Note that this option also exists in the SP configuration. This
entry in the IdP-remote metadata overrides the option in the
[SP configuration](./saml:sp).
`AuthnContextComparison`
: The Comparison attribute of the AuthnContext that will be sent in the login request. This parameter won't be used unless AuthnContextClassRef is set and contains one or more values. Possible values:
* SAML2\Constants::COMPARISON_EXACT (default)
* SAML2\Constants::COMPARISON_BETTER
* SAML2\Constants::COMPARISON_MINIMUM
* SAML2\Constants::COMPARISON_MAXIMUM
: Note that this option also exists in the SP configuration. This
entry in the IdP-remote metadata overrides the option in the
[SP configuration](./saml:sp).
`authproc`
: Used to manipulate attributes, and limit access for each IdP. See the [authentication processing filter manual](simplesamlphp-authproc).
`base64attributes`
: Whether attributes received from this IdP should be base64 decoded. The default is `FALSE`.
`certData`
: The base64 encoded certificate for this IdP. This is an alternative to storing the certificate in a file on disk and specifying the filename in the `certificate`-option.
`certificate`
: Location of certificate data for this IdP.
`description`
: A description of this IdP. Will be used by various modules when they need to show a description of the IdP to the user.
: This option can be translated into multiple languages in the same way as the `name`-option.
`disable_scoping`
: Whether sending of samlp:Scoping elements in authentication requests should be suppressed. The default value is `FALSE`.
When set to `TRUE`, no scoping elements will be sent. This does not comply with the SAML2 specification, but allows
interoperability with ADFS which [does not support Scoping elements](https://docs.microsoft.com/en-za/azure/active-directory/develop/active-directory-single-sign-on-protocol-reference#scoping).
: Note that this option also exists in the SP configuration. This
entry in the IdP-remote metadata overrides the option in the
[SP configuration](./saml:sp).
`encryption.blacklisted-algorithms`
: Blacklisted encryption algorithms. This is an array containing the algorithm identifiers.
: Note that this option also exists in the SP configuration. This
entry in the IdP-remote metadata overrides the option in the
[SP configuration](./saml:sp).
: The RSA encryption algorithm with PKCS#1 v1.5 padding is blacklisted by default for security reasons. Any assertions
encrypted with this algorithm will therefore fail to decrypt. You can override this limitation by defining an empty
array in this option (or blacklisting any other algorithms not including that one). However, it is strongly
discouraged to do so. For your own safety, please include the string 'http://www.w3.org/2001/04/xmlenc#rsa-1_5' if
you make use of this option.
`hide.from.discovery`
: Whether to hide hide this IdP from the local discovery or not. Set to true to hide it. Defaults to false.
`icon`
: A logo which will be shown next to this IdP in the discovery service.
`IDPList`
: The IdP is allowed to respond to an `AuthNRequest` originally sent to entityIDs in this list.
`name`
: The name of this IdP. Will be used by various modules when they need to show a name of the SP to the user.
: If this option is unset, the organization name will be used instead (if it is available).
: This option can be translated into multiple languages by specifying the value as an array of language-code to translated name:
```php
'name' => [
'en' => 'A service',
'no' => 'En tjeneste',
],
```
`nameid.encryption`
: Whether NameIDs sent to this IdP should be encrypted. The default
value is `FALSE`.
: Note that this option also exists in the SP configuration. This
entry in the IdP-remote metadata overrides the option in the
[SP configuration](./saml:sp).
`NameIDPolicy`
: The format of the NameID we request from this IdP: an array in the form of
`[ 'Format' => the format, 'AllowCreate' => true or false ]`.
Set to an empty array `[]` to omit sending any specific NameIDPolicy element
in the AuthnRequest. When the entire option or either array key is unset,
the defaults are transient and true respectively.
`OrganizationName`
: The name of the organization responsible for this SPP.
This name does not need to be suitable for display to end users.
: This option can be translated into multiple languages by specifying the value as an array of language-code to translated name:
```php
'OrganizationName' => [
'en' => 'Example organization',
'no' => 'Eksempel organisation',
],
```
: *Note*: If you specify this option, you must also specify the `OrganizationURL` option.
`OrganizationDisplayName`
: The name of the organization responsible for this IdP.
This name must be suitable for display to end users.
If this option isn't specified, `OrganizationName` will be used instead.
: This option can be translated into multiple languages by specifying the value as an array of language-code to translated name.
: *Note*: If you specify this option, you must also specify the `OrganizationName` option.
`OrganizationURL`
: A URL the end user can access for more information about the organization.
: This option can be translated into multiple languages by specifying the value as an array of language-code to translated URL.
: *Note*: If you specify this option, you must also specify the `OrganizationName` option.
`scope`
: An array with scopes valid for this IdP.
The IdP will send scopes in scoped attributes, that is, attributes containing a value with an `@` sign and a domain name
after it.
: When the `saml:FilterScopes` authentication processing filter is used, this list of scopes will determine the valid
scopes for attributes.
`signature.algorithm`
: The algorithm to use when signing any message sent to this specific identity provider. Defaults to RSA-SHA256.
: Note that this option also exists in the SP configuration.
This value in the IdP remote metadata overrides the value in the SP configuration.
: Possible values:
* `http://www.w3.org/2000/09/xmldsig#rsa-sha1`
*Note*: the use of SHA1 is **deprecated** and will be disallowed in the future.
* `http://www.w3.org/2001/04/xmldsig-more#rsa-sha256`
The default.
* `http://www.w3.org/2001/04/xmldsig-more#rsa-sha384`
* `http://www.w3.org/2001/04/xmldsig-more#rsa-sha512`
`sign.authnrequest`
: Whether to sign authentication requests sent to this IdP.
: Note that this option also exists in the SP configuration.
This value in the IdP remote metadata overrides the value in the SP configuration.
`sign.logout`
: Whether to sign logout messages sent to this IdP.
: Note that this option also exists in the SP configuration.
This value in the IdP remote metadata overrides the value in the SP configuration.
`SingleLogoutService`
: Endpoint URL for logout requests and responses. You should obtain this from the IdP. Users who log out from your service is redirected to this URL with the LogoutRequest using HTTP-REDIRECT.
: The value of this option is specified in the format shown in [endpoint format](./simplesamlphp-metadata-endpoints).
`SingleLogoutServiceResponse`
: Endpoint URL for logout responses. Overrides the `SingleLogoutService`-option for responses.
`SingleSignOnService`
: Endpoint URL for sign on. You should obtain this from the IdP. For SAML 2.0, SimpleSAMLphp will use the HTTP-Redirect binding when contacting this endpoint.
: The value of this option is specified in the format shown in [endpoint format](./simplesamlphp-metadata-endpoints).
`SPNameQualifier`
: This corresponds to the SPNameQualifier in the SAML 2.0 specification. It allows to give subjects a SP specific namespace. This option is rarely used, so if you don't need it, leave it out. When left out, SimpleSAMLphp assumes the entityID of your SP as the SPNameQualifier.
`validate.logout`
: Whether we require signatures on logout messages sent from this IdP.
: Note that this option also exists in the SP configuration.
This value in the IdP remote metadata overrides the value in the SP configuration.
### Decrypting assertions
It is possible to decrypt the assertions received from an IdP. Currently the only algorithm supported is `AES128_CBC` or `RIJNDAEL_128`.
There are two modes of encryption supported by SimpleSAMLphp. One is symmetric encryption, in which case both the SP and the IdP needs to share a key. The other mode is the use of public key encryption. In that mode, the public key of the SP is extracted from the certificate of the SP.
`assertion.encryption`
: Whether assertions received from this IdP must be encrypted. The default value is `FALSE`.
If this option is set to `TRUE`, assertions from the IdP must be encrypted.
Unencrypted assertions will be rejected.
: Note that this option overrides the option with the same name in the SP configuration.
`sharedkey`
: Symmetric key which should be used for decryption. This should be a 128-bit, 192-bit or 256-bit key based on the algorithm used. If this option is not specified, public key encryption will be used instead.
`sharedkey_algorithm`
: Algorithm which should be used for decryption. Possible values are:
* `http://www.w3.org/2001/04/xmlenc#aes128-cbc`
* `http://www.w3.org/2001/04/xmlenc#aes192-cbc`
* `http://www.w3.org/2001/04/xmlenc#aes256-cbc`
* `http://www.w3.org/2009/xmlenc11#aes128-gcm`
* `http://www.w3.org/2009/xmlenc11#aes192-gcm`
* `http://www.w3.org/2009/xmlenc11#aes256-gcm`
### Fields for signing and validating messages
SimpleSAMLphp only signs authentication responses by default. Signing of authentication request, logout requests and logout responses can be enabled by setting the `redirect.sign` option. Validation of received messages can be enabled by the `redirect.validate` option.
`redirect.sign`
: Whether authentication request, logout requests and logout responses sent to this IdP should be signed. The default is `FALSE`.
`redirect.validate`
: Whether logout requests and logout responses received from this IdP should be validated. The default is `FALSE`.
**Example: Configuration for validating messages**:
```php
'redirect.validate' => true,
'certificate' => 'example.org.crt',
```

352
plugins/simplesaml/lib/docs/simplesamlphp-reference-sp-remote.md Normal file
View File

@@ -0,0 +1,352 @@
# SP remote metadata reference
[TOC]
This is a reference for metadata options available for `metadata/saml20-sp-remote.php`. The file has the following format:
```php
<?php
/* The index of the array is the entity ID of this SP. */
$metadata['entity-id-1'] = [
/* Configuration options for the first SP. */
];
$metadata['entity-id-2'] = [
/* Configuration options for the second SP. */
];
/* ... */
```
## Common options
The following options can be set:
`attributes`
: This should indicate which attributes an SP should receive. It is
used by for example the `consent:Consent` module to tell the user
which attributes the SP will receive, and the `core:AttributeLimit`
module to limit which attributes are sent to the SP.
`authproc`
: Used to manipulate attributes, and limit access for each SP. See
the [authentication processing filter manual](simplesamlphp-authproc).
`description`
: A description of this SP. Will be used by various modules when they
need to show a description of the SP to the user.
: This option can be translated into multiple languages in the same
way as the `name`-option.
`name`
: The name of this SP. Will be used by various modules when they need
to show a name of the SP to the user.
: If this option is unset, the organization name will be used instead (if it is available).
: This option can be translated into multiple languages by specifying
the value as an array of language-code to translated name:
```php
'name' => [
'en' => 'A service',
'no' => 'En tjeneste',
],
```
`OrganizationName`
: The name of the organization responsible for this SPP.
This name does not need to be suitable for display to end users.
: This option can be translated into multiple languages by specifying the value as an array of language-code to translated name:
```php
'OrganizationName' => [
'en' => 'Example organization',
'no' => 'Eksempel organisation',
],
```
: *Note*: If you specify this option, you must also specify the `OrganizationURL` option.
`OrganizationDisplayName`
: The name of the organization responsible for this IdP.
This name must be suitable for display to end users.
If this option isn't specified, `OrganizationName` will be used instead.
: This option can be translated into multiple languages by specifying the value as an array of language-code to translated name.
: *Note*: If you specify this option, you must also specify the `OrganizationName` option.
`OrganizationURL`
: A URL the end user can access for more information about the organization.
: This option can be translated into multiple languages by specifying the value as an array of language-code to translated URL.
: *Note*: If you specify this option, you must also specify the `OrganizationName` option.
`AssertionConsumerService`
: The URL of the AssertionConsumerService endpoint for this SP.
This option is required - without it you will not be able to send
responses back to the SP.
: The value of this option is specified the format detailed in [endpoint format](./simplesamlphp-metadata-endpoints).
`attributeencodings`
: What encoding should be used for the different attributes. This is
an array which maps attribute names to attribute encodings. There
are three different encodings:
: - `string`: Will include the attribute as a normal string. This is
the default.
: - `base64`: Store the attribute as a base64 encoded string.
: - `raw`: Store the attribute without any modifications. This
makes it possible to include raw XML in the response.
`attributes.NameFormat`
: What value will be set in the Format field of attribute
statements. This parameter can be configured multiple places, and
the actual value used is fetched from metadata by the following
priority:
:
1. SP Remote Metadata
2. IdP Hosted Metadata
: The default value is:
`urn:oasis:names:tc:SAML:2.0:attrname-format:uri`
: Some examples of values specified in the SAML 2.0 Core
Specification:
: - `urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified`
: - `urn:oasis:names:tc:SAML:2.0:attrname-format:uri` (The default in Shibboleth 2.0, mandatory as per SAML2INT)
: - `urn:oasis:names:tc:SAML:2.0:attrname-format:basic` (The default in Sun Access Manager)
: You can also define your own value.
: Note that this option also exists in the IdP-hosted metadata. This
entry in the SP-remote metadata overrides the option in the
IdP-hosted metadata.
`audience`
: An array of additional entities to be added to the AudienceRestriction. By default the only audience is the SP's entityID.
`certData`
: The base64 encoded certificate for this SP. This is an alternative to storing the certificate in a file on disk and specifying the filename in the `certificate`-option.
`certificate`
: Location of certificate data for this SP. The certificate is used to
verify the signature of messages received from the SP (if
`redirect.validate`is set to `TRUE`), and to encrypting assertions
(if `assertion.encryption` is set to TRUE and `sharedkey` is
unset.)
`encryption.blacklisted-algorithms`
: Blacklisted encryption algorithms. This is an array containing the algorithm identifiers.
: Note that this option also exists in the IdP-hosted metadata. This
entry in the SP-remote metadata overrides the option in the
[IdP-hosted metadata](./simplesamlphp-reference-idp-hosted).
: The RSA encryption algorithm with PKCS#1 v1.5 padding is blacklisted by default for security reasons. Any assertions
encrypted with this algorithm will therefore fail to decrypt. You can override this limitation by defining an empty
array in this option (or blacklisting any other algorithms not including that one). However, it is strongly
discouraged to do so. For your own safety, please include the string 'http://www.w3.org/2001/04/xmlenc#rsa-1_5' if
you make use of this option.
`ForceAuthn`
: Set this `TRUE` to force the user to reauthenticate when the IdP
receives authentication requests from this SP. The default is
`FALSE`.
`NameIDFormat`
: The `NameIDFormat` this SP should receive. This may be specified as either a string or an array.
: The three most commonly used values are:
:
1. `urn:oasis:names:tc:SAML:2.0:nameid-format:transient`
2. `urn:oasis:names:tc:SAML:2.0:nameid-format:persistent`
3. `urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress`
: The `transient` format will generate a new unique ID every time
the SP logs in.
: To properly support the `persistent` and `emailAddress` formats,
you should configure [NameID generation filters](./saml:nameid)
on your IdP.
`nameid.encryption`
: Whether NameIDs sent to this SP should be encrypted. The default
value is `FALSE`.
: Note that this option also exists in the IdP-hosted metadata. This
entry in the SP-remote metadata overrides the option in the
[IdP-hosted metadata](./simplesamlphp-reference-idp-hosted).
`saml20.sign.response`
: Whether `<samlp:Response>` messages should be signed.
Defaults to `TRUE`.
: Note that this option also exists in the IdP-hosted metadata.
The value in the SP-remote metadata overrides the value in the IdP-hosted metadata.
`saml20.sign.assertion`
: Whether `<saml:Assertion>` elements should be signed.
Defaults to `TRUE`.
: Note that this option also exists in the IdP-hosted metadata.
The value in the SP-remote metadata overrides the value in the IdP-hosted metadata.
`signature.algorithm`
: The algorithm to use when signing any message sent to this specific service provider. Defaults to RSA-SHA256.
: Note that this option also exists in the IdP-hosted metadata.
The value in the SP-remote metadata overrides the value in the IdP-hosted metadata.
: Possible values:
* `http://www.w3.org/2000/09/xmldsig#rsa-sha1`
*Note*: the use of SHA1 is **deprecated** and will be disallowed in the future.
* `http://www.w3.org/2001/04/xmldsig-more#rsa-sha256`
The default.
* `http://www.w3.org/2001/04/xmldsig-more#rsa-sha384`
* `http://www.w3.org/2001/04/xmldsig-more#rsa-sha512`
`signature.privatekey`
: Location of private key data for this IdP, in PEM format.
: Note that this option also exists in the IdP-hosted metadata. This entry in the SP-remote metadata overrides the option `privatekey` in the IdP-hosted metadata.
`signature.privatekey_pass`
: Passphrase for the private key. Leave this option out if the private key is unencrypted.
: Note that this option only is used if `signature.privatekey` is present.
`signature.certificate`
: Location of certificate data included by IdP for KeyInfo within the signature for the SP, in PEM format.
: If `signature.privatekey` is present and `signature.certificate` is left blank, X509Certificate will not be included with the signature.
`sign.logout`
: Whether to sign logout messages sent to this SP.
: Note that this option also exists in the IdP-hosted metadata.
The value in the SP-remote metadata overrides the value in the IdP-hosted metadata.
`simplesaml.attributes`
: Whether the SP should receive any attributes from the IdP. The
default value is `TRUE`.
`SingleLogoutService`
: The URL of the SingleLogoutService endpoint for this SP.
This option is required if you want to implement single logout for
this SP. If the option isn't specified, this SP will not be logged
out automatically when a single logout operation is initialized.
: The value of this option is specified in the format detailed in [endpoint format](./simplesamlphp-metadata-endpoints).
`SingleLogoutServiceResponse`
: The URL logout responses to this SP should be sent. If this option
is unspecified, the `SingleLogoutService` endpoint will be used as
the recipient of logout responses.
`SPNameQualifier`
: SP NameQualifier for this SP. If not set, the IdP will set the
SPNameQualifier to be the SP entity ID.
`validate.authnrequest`
: Whether we require signatures on authentication requests sent from this SP.
Set it to:
: - true: authnrequest must be signed (and signature will be validated)
: - null: authnrequest may be signed, if it is, signature will be validated
: - false: authnrequest signature is never checked
: Note that this option also exists in the IdP-hosted metadata.
The value in the SP-remote metadata overrides the value in the IdP-hosted metadata.
`validate.logout`
: Whether we require signatures on logout messages sent from this SP.
: Note that this option also exists in the IdP-hosted metadata.
The value in the SP-remote metadata overrides the value in the IdP-hosted metadata.
`skipEndpointValidationWhenSigned`
: Whether to skip validating that the AssertionConsumerServiceURL sent in authentication
requests exist in SP metadata. Only allowed for signed requests.
This option must be a simple boolean (true/false - although a value of false essentially has
no effect) or a callable. When used as a callable, the static class method must accept the
SP metadata config as a parameter and return a boolean.
## Encrypting assertions
It is possible to encrypt the assertions sent to a SP. Currently the
only algorithm supported is `AES128_CBC` or `RIJNDAEL_128`.
There are two modes of encryption supported by SimpleSAMLphp. One is
symmetric encryption, in which case both the SP and the IdP needs to
share a key. The other mode is the use of public key encryption. In
that mode, the public key of the SP is extracted from the certificate
of the SP.
`assertion.encryption`
: Whether assertions sent to this SP should be encrypted. The default
value is `FALSE`.
: Note that this option also exists in the IdP-hosted metadata. This
entry in the SP-remote metadata overrides the option in the
IdP-hosted metadata.
`sharedkey`
: Symmetric key which should be used for encryption. This should be a
128-bit, 192-bit or 256-bit key based on the algorithm used.
If this option is not specified, public key encryption will be used instead.
`sharedkey_algorithm`
: Algorithm which should be used for encryption. Possible values are:
* `http://www.w3.org/2001/04/xmlenc#aes128-cbc`
* `http://www.w3.org/2001/04/xmlenc#aes192-cbc`
* `http://www.w3.org/2001/04/xmlenc#aes256-cbc`
* `http://www.w3.org/2009/xmlenc11#aes128-gcm`
* `http://www.w3.org/2009/xmlenc11#aes192-gcm`
* `http://www.w3.org/2009/xmlenc11#aes256-gcm`
## Fields for signing and validating messages
SimpleSAMLphp only signs authentication responses by default.
Signing of logout requests and logout responses can be enabled by
setting the `redirect.sign` option. Validation of received messages
can be enabled by the `redirect.validate` option.
These options overrides the options set in `saml20-idp-hosted`.
`redirect.sign`
: Whether logout requests and logout responses sent to this SP should
be signed. The default is `FALSE`.
`redirect.validate`
: Whether authentication requests, logout requests and logout
responses received from this SP should be validated. The default is
`FALSE`
### Example: Configuration for validating messages
```php
'redirect.validate' => true,
'certificate' => 'example.org.crt',
```
## Fields for scoping
Only relevant if you are a proxy/bridge and want to limit the IdPs on your proxy
that this SP can use.
`IDPList`
: The list of scoped IdPs, i.e. the list of entityids for IdPs that are
relevant for this SP. It will override any list set in the IdP's
metadata.
### Example: Configuration for scoping
```php
'IDPList' => ['https://idp1.wayf.dk', 'https://idp2.wayf.dk'],
```

91
plugins/simplesaml/lib/docs/simplesamlphp-scoping.md Normal file
View File

@@ -0,0 +1,91 @@
# Scoping
[TOC]
Scoping allows a service provider to specify a list of identity providers in an
authnRequest to a proxying identity provider. This is an indication to the
proxying identity provider that the service will only deal with the identity
providers specified.
A common use is for a service provider in a hub-and-spoke architecture to
manage its own discovery service and being able to tell the hub/proxy-IdP which
(backend-end) identity provider to use. The standard discovery service in
SimpleSAMLphp will show the intersection of all the known IdPs and the IdPs
specified in the scoping element. If this intersection only contains one IdP,
then the request is automatically forwarded to that IdP.
Scoping is a SAML 2.0 specific option.
## Options
SimpleSAMLphp supports scoping by allowing the following options:
`ProxyCount`
: Specifies the number of proxying indirections permissible
between the identity provider receiving the request and the identity provider
who ultimately authenticates the user. A count of zero permits no proxying. If
ProxyCount is unspecified the number of proxy indirections is not limited.
`IDPList`
: The list of trusted IdPs, i.e. the list of entityIDs for identity providers
that are relevant for a service provider in an authnRequest.
**Note**: SimpleSAMLphp does not support specifying the GetComplete option.
### Usage
The ProxyCount and IDPList option can be specified in the following places:
- as a state parameter to the authentication source
- in the saml:SP authentication source configuration
- in the saml20-idp-remote metadata
- in the saml20-sp-remote metadata
Example configuration:
# Add the IDPList
'IDPList' => [
'IdPEntityID1',
'IdPEntityID2',
'IdPEntityID3',
],
# Set ProxyCount
'ProxyCount' => 2,
## Retrieving information
### RequesterID element
To allow an identity provider to identify the original requester and the
proxying identity providers, SimpleSAMLphp adds the RequesterID element to
the request and if necessary the scoping element even if explicit scoping is
not used.
The RequesterId elements are available from the state array as an array, for
instance via the authenticate method on an authentication source.
$requesterIDs = $state['saml:RequesterID'];
### AuthenticatingAuthority element
To allow a service provider to identify the authentication authorities that
were involved in the authentication of the user, SimpleSAMLphp adds the
AuthenticatingAuthority elements.
The list of authenticating authorities (the AuthenticatingAuthority element)
can be retrieved as an array from the authentication data.
# Get the authentication source.
$as = new \SimpleSAML\Auth\Simple();
# Get the AuthenticatingAuthority
$aa = $as->getAuthData('saml:AuthenticatingAuthority');
## 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](https://simplesamlphp.org/docs/)
- [Join the SimpleSAMLphp user's mailing list](https://simplesamlphp.org/lists)

318
plugins/simplesaml/lib/docs/simplesamlphp-sp-api.md Normal file
View File

@@ -0,0 +1,318 @@
# SimpleSAMLphp SP API reference
[TOC]
This document describes the \SimpleSAML\Auth\Simple API.
This is the preferred API for integrating SimpleSAMLphp with other applications.
**Note on PHP sessions and SimpleSAMLphp API calls**:
Some SimpleSAMLphp calls replace the current active PHP session. If you previously started a session and wish to write to it, then you must cleanup the SimpleSAMLphp session before you can write to your session. If you do not need to modify your own session, then you can leave the cleanup call out; however, forgetting to call cleanup is a common source of hard to find bugs.
```php
session_start();
// ...
$auth = new \SimpleSAML\Auth\Simple('default-sp');
$auth->isAuthenticated(); // Replaces our session with the SimpleSAMLphp one
// $_SESSION['key'] = 'value'; // This would save to the SimpleSAMLphp session which isn't what we want
\SimpleSAML\Session::getSessionFromRequest()->cleanup(); // Reverts to our PHP session
// Save to our session
$_SESSION['key'] = 'value';
```
## Constructor
```php
new \SimpleSAML\Auth\Simple(string $authSource)
```
The constructor initializes a \SimpleSAML\Auth\Simple object.
`Parameters`:
It has a single parameter, which is the ID of the authentication
source that should be used. This authentication source must exist in
`config/authsources.php` and be of type saml:SP. Note that
authentication methods such as `ldap:Ldap` and `sqlauth` are defined
in `config/authsources.php` but those are only to be used by an IdP.
A normal setup would have your application talking to an SP, that SP
talking with an IdP, and that IdP using an authentication method to
authenticate the user.
`Example`:
```php
$auth = new \SimpleSAML\Auth\Simple('default-sp');
```
### isAuthenticated
```php
bool isAuthenticated()
```
Check whether the user is authenticated with this authentication source.
`TRUE` is returned if the user is authenticated, `FALSE` if not.
`Example`:
```php
if (!$auth->isAuthenticated()) {
\SimpleSAML\Session::getSessionFromRequest()->cleanup();
/* Show login link. */
print('<a href="/login">Login</a>');
}
```
### requireAuth
```php
void requireAuth(array $params = [])
```
Make sure that the user is authenticated.
This function will only return if the user is authenticated.
If the user isn't authenticated, this function will start the authentication process.
`Parameters`:
`$params` is an associative array with named parameters for this function.
See the documentation for the `login`-function for a description of the parameters.
`Example 1`:
```php
$auth->requireAuth();
\SimpleSAML\Session::getSessionFromRequest()->cleanup();
print("Hello, authenticated user!");
```
`Example 2`:
```php
/*
* Return the user to the frontpage after authentication, don't post
* the current POST data.
*/
$auth->requireAuth([
'ReturnTo' => 'https://sp.example.org/',
'KeepPost' => FALSE,
]);
\SimpleSAML\Session::getSessionFromRequest()->cleanup();
print("Hello, authenticated user!");
```
### login
```php
void login(array $params = [])
```
Start a login operation.
This function will always start a new authentication process.
`Parameters`:
The following global parameters are supported:
`ErrorURL` (`string`)
: A URL to a page which will receive errors that may occur during authentication.
`KeepPost` (`bool`)
: If set to `TRUE`, the current POST data will be submitted again after authentication.
The default is `TRUE`.
`ReturnTo` (`string`)
: The URL the user should be returned to after authentication.
The default is to return the user to the current page.
`ReturnCallback` (`array`)
: The function we should call when the user finishes authentication.
The [`saml:SP`](./saml:sp) authentication source also defines some parameters.
`Example`:
```php
# Send a passive authentication request.
$auth->login([
'isPassive' => true,
'ErrorURL' => 'https://.../error_handler.php',
]);
\SimpleSAML\Session::getSessionFromRequest()->cleanup();
```
### logout
```php
void logout(mixed $params = null)
```
Log the user out.
After logging out, the user will either be redirected to another page, or a function will be called.
This function never returns.
`Parameters`:
`$params`
: Parameters for the logout operation.
: This can either be a simple string, in which case it is interpreted as the URL the user should be redirected to after logout, or an associative array with logout parameters.
: If this parameter isn't specified, we will redirect the user to the current URL after logout.
: If the parameter is an an array, it can have the following options:
- `ReturnTo`: The URL the user should be returned to after logout.
- `ReturnCallback`: The function that should be called after logout.
- `ReturnStateParam`: The parameter we should return the state in when redirecting.
- `ReturnStateStage`: The stage the state array should be saved with.
The `ReturnState` parameters allow access to the result of the logout operation after it completes.
`Example 1`:
Logout, and redirect to the specified URL.
```php
$auth->logout('https://sp.example.org/logged_out.php');
\SimpleSAML\Session::getSessionFromRequest()->cleanup();
```
`Example 2`:
Same as the previous, but check the result of the logout operation afterwards.
```php
$auth->logout([
'ReturnTo' => 'https://sp.example.org/logged_out.php',
'ReturnStateParam' => 'LogoutState',
'ReturnStateStage' => 'MyLogoutState',
]);
\SimpleSAML\Session::getSessionFromRequest()->cleanup();
```
And in logged_out.php:
```php
$state = \SimpleSAML\Auth\State::loadState((string)$_REQUEST['LogoutState'], 'MyLogoutState');
$ls = $state['saml:sp:LogoutStatus']; /* Only works for SAML SP */
if ($ls['Code'] === 'urn:oasis:names:tc:SAML:2.0:status:Success' && !isset($ls['SubCode'])) {
/* Successful logout. */
echo("You have been logged out.");
} else {
/* Logout failed. Tell the user to close the browser. */
echo("We were unable to log you out of all your sessions. To be completely sure that you are logged out, you need to close your web browser.");
}
```
### getAttributes
```php
array getAttributes()
```
Retrieve the attributes of the current user.
If the user isn't authenticated, an empty array will be returned.
The attributes will be returned as an associative array with the name of the attribute as the key and the value as an array of one or more strings:
```php
[
'uid' => ['testuser'],
'eduPersonAffiliation' => ['student', 'member'],
]
```
`Example`:
```php
$attrs = $auth->getAttributes();
if (!isset($attrs['displayName'][0])) {
throw new Exception('displayName attribute missing.');
}
$name = $attrs['displayName'][0];
print('Hello, ' . htmlspecialchars($name));
```
### getAuthData
```php
mixed getAuthData(string $name)
```
Retrieve the specified authentication data for the current session.
NULL is returned if the user isn't authenticated.
The available authentication data depends on the module used for authentication.
See the [`saml:SP`](./saml:sp) reference for information about available SAML authentication data.
`Example`:
```php
$idp = $auth->getAuthData('saml:sp:IdP');
$nameID = $auth->getAuthData('saml:sp:NameID')->getValue();
printf('You are %s, logged in from %s', htmlspecialchars($nameID), htmlspecialchars($idp));
```
### getLoginURL
```php
string getLoginURL(string $returnTo = null)
```
Retrieve a URL that can be used to start authentication.
`Parameters`:
`$returnTo`
: The URL the user should be returned to after authentication.
The default is the current page.
`Example`:
```php
$url = $auth->getLoginURL();
print('<a href="' . htmlspecialchars($url) . '">Login</a>');
```
**Note**:
The URL returned by this function is static, and will not change.
You can easily create your own links without using this function.
The URL should be:
`.../simplesaml/module.php/core/login/<authentication source>?ReturnTo=<return URL>`
### getLogoutURL
```php
string getLogoutURL(string $returnTo = NULL)
```
Retrieve a URL that can be used to trigger logout.
`Parameters`:
`$returnTo`
: The URL the user should be returned to after logout.
The default is the current page.
`Example`:
```php
$url = $auth->getLogoutURL();
print('<a href="' . htmlspecialchars($url) . '">Logout</a>');
```
**Note**:
The URL returned by this function is static, and will not change.
You can easily create your own links without using this function.
The URL should be:
`.../simplesaml/module.php/core/logout/<authentication source>?ReturnTo=<return URL>`

290
plugins/simplesaml/lib/docs/simplesamlphp-sp.md Normal file
View File

@@ -0,0 +1,290 @@
# SimpleSAMLphp Service Provider QuickStart
[TOC]
This guide will describe how to configure SimpleSAMLphp as a service
provider (SP). You should previously have installed SimpleSAMLphp as
described in the [SimpleSAMLphp installation instructions](simplesamlphp-install).
## Configuring the SP
The SP is configured by an entry in `config/authsources.php`.
This is a minimal `authsources.php` for a SP:
```php
<?php
$config = [
/* This is the name of this authentication source, and will be used to access it later. */
'default-sp' => [
'saml:SP',
'entityID' => 'https://myapp.example.org/',
],
];
```
The entity ID must be a URI, that is unlikely to change for technical or
political reasons. We recommend it to be a domain name that you own.
Like above, if your organization's main domain is `example.org` and this SP is
for the application `myapp`. The URL does not have to resolve to actual
content, it's just an identifier. Hence you don't need to and should not change
it if the actual domain of your application changes.
For guidance in picking an entityID, see
[InCommon's best practice](https://spaces.at.internet2.edu/display/federation/saml-metadata-entityid)
on the matter.
For more information about additional options available for the SP,
see the [`saml:SP` reference](./saml:sp).
If you want multiple Service Providers in the same site and installation,
you can add more entries in the `authsources.php` configuration. If so
remember to set the EntityID explicitly. Here is an example:
```php
'sp1' => [
'saml:SP',
'entityID' => 'https://myapp.example.org/',
],
'sp2' => [
'saml:SP',
'entityID' => 'https://myotherapp.example.org/',
],
```
### Enabling a certificate for your Service Provider
Some Identity Providers / Federations may require that your Service Providers
holds a certificate. If you enable a certificate for your Service Provider,
it may be able to sign requests and response sent to the Identity Provider,
as well as receiving encrypted responses.
Create a self-signed certificate in the `cert/` directory.
```bash
cd cert
openssl req -newkey rsa:3072 -new -x509 -days 3652 -nodes -out saml.crt -keyout saml.pem
```
Then edit your `authsources.php` entry, and add references to your certificate:
```php
'default-sp' => [
'saml:SP',
'entityID' => 'https://myapp.example.org/',
'privatekey' => 'saml.pem',
'certificate' => 'saml.crt',
],
```
## Adding IdPs to the SP
The service provider you are configuring needs to know about the identity
providers you are going to connect to it. This is configured by metadata
stored in `metadata/saml20-idp-remote.php`.
This is a minimal example of a `metadata/saml20-idp-remote.php`
metadata file:
```php
<?php
$metadata['https://example.org/saml-idp'] = [
'SingleSignOnService' => [
[
'Location' => 'https://example.org/simplesaml/saml2/idp/SSOService.php',
'Binding' => 'urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect',
],
],
'SingleLogoutService' => [
[
'Location' => 'https://example.org/simplesaml/saml2/idp/SingleLogoutService.php',
'ResponseLocation' => 'https://sp.example.org/LogoutResponse',
'Binding' => 'urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect',
],
],
'certificate' => 'example.pem',
];
```
`example.pem` under your `cert/` directory contains the certificate the
identity provider uses for signing assertions.
For more information about available options in the idp-remote metadata
files, see the [IdP remote reference](simplesamlphp-reference-idp-remote).
If you have the metadata of the remote IdP as an XML file, you can use the
built-in XML to SimpleSAMLphp metadata converter, which by default is
available at `/module.php/admin/federation/metadata-converter` in
your SimpleSAMLphp installation.
Note that the idp-remote file lists all IdPs you trust.
You should remove all IdPs that you don't use.
## Setting the default IdP
An option in the authentication source allows you to configure which IdP should
be used. This is the `idp` option.
```php
<?php
$config = [
'default-sp' => [
'saml:SP',
/*
* The entity ID of the IdP this should SP should contact.
* Can be NULL/unset, in which case the user will be shown a list of available IdPs.
*/
'idp' => 'https://example.org/saml-idp',
],
];
```
## Exchange metadata with the IdP
In order to complete the connection between your SP and an IdP, you must
exchange the metadata of your SP with the IdP. The metadata of your SP can be
found in the *Federation* tab of the web interface. Copy the SAML 2.0 XML
Metadata document automatically generated by SimpleSAMLphp and send it to the
administrator of the IdP. You can also send them the dedicated URL of your
metadata, so that they can fetch it periodically and obtain automatically any
changes that you may perform to your SP.
You will also need to add the metadata of the IdP. Ask them to provide you with
their metadata, and parse it using the *XML to SimpleSAMLphp metadata converter*
tool available also in the *Federation* tab of the web interface. Copy the
resulting parsed metadata and paste it with a text editor into the
`metadata/saml20-idp-remote.php` file in your SimpleSAMLphp directory.
If you intend to add your SP to a federation, the procedure for managing trust
in federations will differ, but the common part is that you would need to
provide the *SAML 2.0 metadata of your SP*, and register that with the
federation administration. You will probably be required too to consume
the federation metadata periodically. Read more about
[automated metadata management](/docs/contrib_modules/metarefresh/simplesamlphp-automated_metadata)
to learn more about that.
## Test the SP
After the metadata is configured on the IdP, you should be able to test the
configuration. The admin module of SimpleSAMLphp has a tab to test
authentication sources. There you should a list of authentication sources,
including the one you have created for the SP.
After you click the link for that authentication source, you will be
redirected to the IdP. After entering your credentials, you should be
redirected back to the test page.
The test page should contain a list of your attributes:
![Screenshot of the status page after a user has successfully authenticated](resources/simplesamlphp-sp/screenshot-example.png)
For a better looking, more advanced Discovery Service with tabs and live
search, you may want to use the `discopower` module.
## Integrating authentication with your own application
The API is documented in [the SP API reference](simplesamlphp-sp-api).
For those web resources you want to protect, you must add a few
lines of PHP code:
- Register the SimpleSAMLphp classes with the PHP autoloader.
- Require authentication of the user for those places it is required.
- Access the users attributes.
Example code:
We start off with loading a file which registers the SimpleSAMLphp classes
with the autoloader.
```php
require_once('../../src/_autoload.php');
```
We select our authentication source:
```php
$as = new \SimpleSAML\Auth\Simple('default-sp');
```
We then require authentication:
```php
$as->requireAuth();
```
And print the attributes:
```php
$attributes = $as->getAttributes();
print_r($attributes);
```
Each attribute name can be used as an index into $attributes to obtain the
value. Every attribute value is an array - a single-valued attribute is an
array of a single element.
We can also request authentication with a specific IdP:
```php
$as->login([
'saml:idp' => 'https://example.org/saml-idp',
]);
```
Other options are also available.
Take a look in the documentation for the [SP module](./saml:sp) for a list
of all parameters.
If we are using PHP sessions in SimpleSAMLphp and in the application we are
protecting, SimpleSAMLphp will close any existing session when invoked for the
first time, and its own session will prevail afterwards. If you want to restore
your own session after calling SimpleSAMLphp, you can do so by cleaning up the
session like this:
```php
$session = \SimpleSAML\Session::getSessionFromRequest();
$session->cleanup();
```
If you don't cleanup SimpleSAMLphp's session and try to use $_SESSION
afterwards, you won't be using your own session and all your data is
likely to get lost or inaccessible.
Note that if your application uses a [custom session handler](https://www.php.net/manual/en/function.session-set-save-handler.php),
SimpleSAMLphp will use it as well. This can lead to problems because
SimpleSAMLphp's stand-alone web UI uses the default PHP session handlers.
Therefore, you may need to unset the custom handler before making any calls to SimpleSAMLphp:
```php
// use custom save handler
session_set_save_handler($handler);
session_start();
// close session and restore default handler
session_write_close();
session_set_save_handler(new SessionHandler(), true);
// use SimpleSAML\Session
$session = \SimpleSAML\Session::getSessionFromRequest();
$session->cleanup();
session_write_close();
// back to custom save handler
session_set_save_handler($handler);
session_start();
```
## 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](https://simplesamlphp.org/docs/)
- [Join the SimpleSAMLphp user's mailing list](https://simplesamlphp.org/lists)

164
plugins/simplesaml/lib/docs/simplesamlphp-theming.md Normal file
View File

@@ -0,0 +1,164 @@
# Theming the user interface in SimpleSAMLphp
[TOC]
In SimpleSAMLphp every part that needs to interact with the user by using a web page, uses templates to present the HTML. SimpleSAMLphp comes with a default set of templates that presents an anonymous look.
You may create your own theme, where you add one or more template files that will override the default ones. This document explains how to achieve that.
## How themes work
If you want to customize the UI, the right way to do that is to create a new **theme**. A theme is a set of templates that can be configured to override the default templates. Themes are a special type of SimpleSAMLphp module.
### Configuring which theme to use
In `config.php` there is a configuration option that controls theming. You need to set that option and also add the module that contains the theme to the list of enabled modules. Here is an example:
```php
'module.enable' => [
...
'mymodule' => true,
],
'theme.use' => 'mymodule:fancytheme',
```
The `theme.use` parameter points to which theme that will be used. If some functionality in SimpleSAMLphp needs to present UI in example with the `logout.twig` template, it will first look for `logout.twig` in the `theme.use` theme, and if not found it will all fallback to look for the base templates.
### Override only specific templates
The SimpleSAMLphp templates are derived from a base template and include other templates as building blocks. You only need to override the templates or building blocks needed for your change.
SimpleSAMLphp allows themes to override the included templates files only, if needed. That means you can create a new theme `fancytheme` that includes only a header and footer template. These templates may refer to your own CSS files, which means that a simple way of making a new look on SimpleSAMLphp is to create a new theme, and copy the existing header, but point to your own CSS instead of the default CSS. This means that for many theme requirements, you only need to specify a new header and footer template, and leave all other templates to SimpleSAMLphp's base versions.
## Creating your first theme
The first thing you need to do is having a SimpleSAMLphp module to place your theme in. If you do not have a module already, create a new one:
```bash
cd modules
mkdir mymodule
```
Then within this module, you can create a new theme named `fancytheme`.
```bash
cd modules/mymodule
mkdir -p themes/fancytheme/default/
```
Now, in `config.php`, add the module to the list of enabled modules, and configure SimpleSAMLphp to actually use your new theme:
```php
'module.enable' => [
...
'mymodule' => true,
],
'theme.use' => 'mymodule:fancytheme',
```
Next, we copy the header file from the base theme:
```bash
cp templates/_header.twig modules/mymodule/themes/fancytheme/default/
```
In the `modules/mymodule/themes/fancytheme/default/_header.twig` file, type in something and go to the SimpleSAMLphp front page to see that your new theme is in use.
## Adding resource files
You can put resource files within the `public/assets` folder of your module, to make your module completely independent with included css, icons etc.
```bash
modules
└───mymodule
└───src
└───themes
└───public
└───assets
└───logo.svg
└───style.css
```
Reference these resources in your custom templates under `themes/fancytheme` by using a generator for the URL.
Example for a custom CSS stylesheet file:
```twig
{% block preload %}
<link rel="stylesheet" href="{{ asset('style.css', 'mymodule') }}">
{% endblock %}
```
## A custom theme controller
If you have very specific requirements for your theme, you can define a custom theme controller
in `config.php`:
```php
'theme.controller' => '\SimpleSAML\Module\mymodule\FancyThemeController',
```
This requires you to implement `\SimpleSAML\XHTML\TemplateControllerInterface.php` in your module's `src`-directory.
The class can then modify the Twig Environment and the variables passed to the theme's templates. In short, this allows you to set additional global variables and to write your own Twig filters and functions.
An example to put in `src/FancyThemeController.php`:
```php
<?php
namespace SimpleSAML\Module\mymodule;
use Twig\Environment;
use SimpleSAML\XHTML\TemplateControllerInterface;
class FancyThemeController implements TemplateControllerInterface
{
/**
* Modify the twig environment after its initialization (e.g. add filters or extensions).
*
* @param \Twig\Environment $twig The current twig environment.
* @return void
*/
public function setUpTwig(Environment &$twig): void
{
}
/**
* Add, delete or modify the data passed to the template.
*
* This method will be called right before displaying the template.
*
* @param array $data The current data used by the template.
* @return void
*/
public function display(array &$data): void
{
$data['extra_info'] = 'Extra information to use in your template';
}
}
```
See the [Twig documentation](https://twig.symfony.com/doc/2.x/templates.html) for more information on using variables and expressions in Twig templates, and the SimpleSAMLphp wiki for [our conventions](https://github.com/simplesamlphp/simplesamlphp/wiki/Twig-conventions).
## Migrating to Twig templates
For existing themes that have been created before SimpleSAMLphp 2.0, you may need to upgrade them to the Twig
templating engine to be compatible with SimpleSAMLphp 2.0.
Twig works by extending a base template, which can itself include other partial templates. Some of the content of the old `includes/header.php` template is now located in a separate `_header.twig` file. This can be customized by copying it from the base template:
```bash
cp templates/_header.twig modules/mymodule/themes/fancytheme/default/
```
If you need to make more extensive customizations to the base template, you should copy it from the base theme:
```bash
cp templates/base.twig modules/mymodule/themes/fancytheme/default/
```
Any references to `$this->data['baseurlpath']` in old-style templates can be replaced with `{{baseurlpath}}` in Twig templates. Likewise, references to `\SimpleSAML\Module::getModuleURL()` can be replaced with `{{baseurlpath}}module.php/mymodule/...` or the `asset()` function like shown above.
If you want to use the `asset()` function, you need to move the asserts from `public/` to `public/assets/`.
Within templates each module is defined as a separate namespace matching the module name. This allows one template to reference templates from other modules using Twig's `@namespace_name/template_path` notation. For instance, a template in `mymodule` can include the widget template from the `yourmodule` module using the notation `@yourmodule/widget.twig`. A special namespace, `__parent__`, exists to allow theme developers to more easily extend a module's stock template.
The wiki also includes some information on [migrating translations](https://github.com/simplesamlphp/simplesamlphp/wiki/Migrating-translation-in-Twig) and [migrating templates](https://github.com/simplesamlphp/simplesamlphp/wiki/Twig:-Migrating-templates).

3
plugins/simplesaml/lib/docs/simplesamlphp-translation.md Normal file
View File

@@ -0,0 +1,3 @@
# SimpleSAMLphp Translation
TODO: please complete this doc on how to translate SimpleSAMLphp

3
plugins/simplesaml/lib/docs/simplesamlphp-upgrade-notes-1.10.md Normal file
View File

@@ -0,0 +1,3 @@
# Upgrade notes for SimpleSAMLphp 1.10
* The default encryption key padding scheme has been changed to `http://www.w3.org/2001/04/xmlenc#rsa-oaep-mgf1p`. This may cause problems if the recipient of messages do not support this padding scheme.

4
plugins/simplesaml/lib/docs/simplesamlphp-upgrade-notes-1.11.md Normal file
View File

@@ -0,0 +1,4 @@
# Upgrade notes for SimpleSAMLphp 1.11
* Support for the Holder-of-Key profile in the SAML 2.0 SP has been disabled by default.
To enable it, set `saml20.hok.assertion` to `TRUE` in `config/authsources.php`.

3
plugins/simplesaml/lib/docs/simplesamlphp-upgrade-notes-1.12.md Normal file
View File

@@ -0,0 +1,3 @@
# Upgrade notes for SimpleSAMLphp 1.12
* PHP version 5.3 is now required.

6
plugins/simplesaml/lib/docs/simplesamlphp-upgrade-notes-1.13.md Normal file
View File

@@ -0,0 +1,6 @@
# Upgrade notes for SimpleSAMLphp 1.13
* The RSA_1.5 (RSA with PKCS#1 v1.5 padding) algorithm is now longer allowed by default. This means messages received
that use this algorithm will fail to decrypt.
* Several functions, classes and interfaces are now deprecated. Please check your code if you are using the API.
* A workaround related to performance issues when processing large metadata sets was included in **1.13.2**. **This workaround is experimental and could have unexpected side effects**.

195
plugins/simplesaml/lib/docs/simplesamlphp-upgrade-notes-1.14.md Normal file
View File

@@ -0,0 +1,195 @@
# Upgrade notes for SimpleSAMLphp 1.14
The `mcrypt` extension is no longer required by SimpleSAMLphp, so if no signatures or encryption are being used, it
can be skipped. It is still a requirement for `xmlseclibs` though, so for those verifying or creating signed
documents, or using encryption, it is still needed.
The `mbstring` extension is now required starting on SimpleSAMLphp 1.14.12.
PHP session cookies are now set to HTTP-only by default. This relates to the `session.phpsession.httponly`
configuration option.
The default value for the 'trusted.url.domains' option in the config file has been changed from null to an empty array,
making SimpleSAMLphp secure to open redirection attacks by default. Setting it explicitly to null will re-allow
insecure redirections.
The jQuery version in use has been bumped to the latest 1.8.X version.
Service Providers using the eduPersonTargetedID attribute, will get a DOMNodeList object instead of the NameID value. In
order to process the NameID, a SAML2_XML_saml_NameID object can be used:
```php
$attributes = $as->getAttributes();
$eptid = $attributes['eduPersonTargetedID'][0]->item(0);
$nameID = new SAML2_XML_saml_NameID($eptid);
```
The following deprecated files, directories and endpoints have been removed:
* `bin/pack.php`
* `docs/pack.txt`
* `docs/simplesamlphp-features.txt`
* `docs/simplesamlphp-reference-sp-hosted.txt`
* `docs/simplesamlphp-subversion.txt`
* `lib/SimpleSAML/Auth/BWC.php` (`SimpleSAML_Auth_BWC`)
* `lib/SimpleSAML/MemcacheStore.php` (`SimpleSAML_MemcacheStore`)
* `lib/SimpleSAML/Metadata/MetaDataStorageHandlerDynamicXML.php` (`SimpleSAML_Metadata_MetaDataStorageHandlerDynamicXML`)
* `modules/aselect/www/linkback.php`
* `modules/core/lib/ModuleDefinition.php` (`sspmod_core_ModuleDefinition`)
* `modules/core/lib/ModuleInstaller.php` (`sspmod_core_ModuleInstaller`)
* `modules/core/www/bwc_resumeauth.php`
* `modules/core/www/idp/resumeauth.php`
* `modules/oauth/lib/OauthSignatureMethodRSASHA1.php` (`sspmod_oauth_OauthSignatureMethodRSASHA1`)
* `modules/oauth/www/accessToken.php`
* `modules/oauth/www/authorize.php`
* `modules/oauth/www/requestToken.php`
* `modules/smartnameattribute/`
* `www/resources/jquery.js`
* `www/resources/jquery-ui.js`
* `www/resources/uitheme/`
* `www/shib13/sp/`
* `www/saml2/idp/idpInitSingleLogoutServiceiFrame.php`
* `www/saml2/idp/SingleLogoutServiceiFrame.php`
* `www/saml2/idp/SingleLogoutServiceiFrameResponse.php`
* `www/saml2/sp/`
* `www/wsfed/`
* `www/example-simple/`
* `www/auth/`
The following deprecated methods and constants have been removed:
* `SimpleSAML_AuthMemCookie::getLoginMethod()`
* `SimpleSAML_Session::DATA_TIMEOUT_LOGOUT`
* `SimpleSAML_Session::expireDataLogout()`
* `SimpleSAML_Session::get_sp_list()`
* `SimpleSAML_Session::getAttribute()`
* `SimpleSAML_Session::getAttributes()`
* `SimpleSAML_Session::getAuthnInstant()`
* `SimpleSAML_Session::getAuthnRequest()`
* `SimpleSAML_Session::getAuthority()`
* `SimpleSAML_Session::getIdP()`
* `SimpleSAML_Session::getInstance()`
* `SimpleSAML_Session::getLogoutState()`
* `SimpleSAML_Session::getNameID()`
* `SimpleSAML_Session::getSessionIndex()`
* `SimpleSAML_Session::getSize()`
* `SimpleSAML_Session::isAuthenticated()`
* `SimpleSAML_Session::remainingTime()`
* `SimpleSAML_Session::setAttribute()`
* `SimpleSAML_Session::setAttributes()`
* `SimpleSAML_Session::setAuthnRequest()`
* `SimpleSAML_Session::setIdP()`
* `SimpleSAML_Session::setLogoutState()`
* `SimpleSAML_Session::setNameID()`
* `SimpleSAML_Session::setSessionDuration()`
* `SimpleSAML_Session::setSessionIndex()`
* `SimpleSAML_Utilities::generateRandomBytesMTrand()`
The following methods have changed their signature. Refer to the code for the updated signatures:
* `SimpleSAML_Auth_Default::initLogin()`
* `SimpleSAML_Metadata_MetaDataStorageHandler::getGenerated()`
* `SimpleSAML_Metadata_MetaDataStorageHandler::getMetaData()`
* `SimpleSAML_Metadata_MetaDataStorageHandler::getMetaDataCurrent()`
* `SimpleSAML_Metadata_MetaDataStorageHandler::getMetaDataCurrentEntityID()`
* `SimpleSAML_Session::doLogout()`
* `SimpleSAML_Session::getAuthState()`
* `SimpleSAML_Session::registerLogoutHandler()`
* `SimpleSAML_Utilities::generateRandomBytes()`
* `SimpleSAML_XML_Shib13_AuthnRequest::createRedirect()`
The following methods and classes have been deprecated. Refer to the code for alternatives:
* `SimpleSAML_Auth_Default`, together with all the `SimpleSAML_Auth_Default.*` keys in the state array.
* `SimpleSAML_Auth_Default::extractPersistentAuthState()`
* `SimpleSAML_Auth_Default::handleUnsolicitedAuth()`
* `SimpleSAML_Auth_Default::initLogin()`
* `SimpleSAML_Auth_Default::initLogout()`
* `SimpleSAML_Auth_Default::initLogoutReturn()`
* `SimpleSAML_Auth_Default::loginCompleted()`
* `SimpleSAML_Auth_Default::logoutCallback()`
* `SimpleSAML_Auth_Default::logoutCompleted()`
* `SimpleSAML_Utilities`
* `SimpleSAML_Utilities::addURLParameter()`
* `SimpleSAML_Utilities::aesDecrypt()`
* `SimpleSAML_Utilities::aesEncrypt()`
* `SimpleSAML_Utilities::arrayize()`
* `SimpleSAML_Utilities::checkCookie()`
* `SimpleSAML_Utilities::checkDateConditions()`
* `SimpleSAML_Utilities::checkURLAllowed()`
* `SimpleSAML_Utilities::createHttpPostRedirectLink()`
* `SimpleSAML_Utilities::createPostRedirectLink()`
* `SimpleSAML_Utilities::debugMessage()`
* `SimpleSAML_Utilities::doRedirect()`
* `SimpleSAML_Utilities::fatalError()`
* `SimpleSAML_Utilities::fetch()`
* `SimpleSAML_Utilities::formatDOMElement()`
* `SimpleSAML_Utilities::formatXMLString()`
* `SimpleSAML_Utilities::generateID()`
* `SimpleSAML_Utilities::generateRandomBytes()`
* `SimpleSAML_Utilities::generateTimestamp()`
* `SimpleSAML_Utilities::getAcceptLanguage()`
* `SimpleSAML_Utilities::getAdminLogoutURL()`
* `SimpleSAML_Utilities::getBaseURL()`
* `SimpleSAML_Utilities::getDefaultEndpoint()`
* `SimpleSAML_Utilities::getDOMChildren()`
* `SimpleSAML_Utilities::getDOMText()`
* `SimpleSAML_Utilities::getFirstPathElement()`
* `SimpleSAML_Utilities::getLastError()`
* `SimpleSAML_Utilities::getSecretSalt()`
* `SimpleSAML_Utilities::getSelfHost()`
* `SimpleSAML_Utilities::getSelfHostWithPath()`
* `SimpleSAML_Utilities::getTempDir()`
* `SimpleSAML_Utilities::initTimezone()`
* `SimpleSAML_Utilities::ipCIDRcheck()`
* `SimpleSAML_Utilities::isAdmin()`
* `SimpleSAML_Utilities::isDOMElementOfType()`
* `SimpleSAML_Utilities::isHTTPS()`
* `SimpleSAML_Utilities::isWindowsOS()`
* `SimpleSAML_Utilities::loadPrivateKey()`
* `SimpleSAML_Utilities::loadPublicKey()`
* `SimpleSAML_Utilities::maskErrors()`
* `SimpleSAML_Utilities::normalizeURL()`
* `SimpleSAML_Utilities::parseAttributes()`
* `SimpleSAML_Utilities::parseDuration()`
* `SimpleSAML_Utilities::parseQueryString()`
* `SimpleSAML_Utilities::parseStateID()`
* `SimpleSAML_Utilities::popErrorMask()`
* `SimpleSAML_Utilities::postRedirect()`
* `SimpleSAML_Utilities::redirect()`
* `SimpleSAML_Utilities::redirectTrustedURL()`
* `SimpleSAML_Utilities::redirectUntrustedURL()`
* `SimpleSAML_Utilities::requireAdmin()`
* `SimpleSAML_Utilities::resolveCert()`
* `SimpleSAML_Utilities::resolvePath()`
* `SimpleSAML_Utilities::resolveURL()`
* `SimpleSAML_Utilities::selfURL()`
* `SimpleSAML_Utilities::selfURLHost()`
* `SimpleSAML_Utilities::selfURLNoQuery()`
* `SimpleSAML_Utilities::setCookie()`
* `SimpleSAML_Utilities::stringToHex()`
* `SimpleSAML_Utilities::transposeArray()`
* `SimpleSAML_Utilities::validateCA()`
* `SimpleSAML_Utilities::validateXML()`
* `SimpleSAML_Utilities::validateXMLDocument()`
* `SimpleSAML_Utilities::writeFile()`
The following modules will no longer be shipped with the next version of SimpleSAMLphp:
* `aggregator`
* `aggregator2`
* `aselect`
* `autotest`
* `casserver`
* `consentSimpleAdmin`
* `discojuice`
* `InfoCard`
* `logpeek`
* `metaedit`
* `modinfo`
* `papi`
* `oauth`
* `openid`
* `openidProvider`
* `saml2debug`
* `themefeidernd`

31
plugins/simplesaml/lib/docs/simplesamlphp-upgrade-notes-1.15.md Normal file
View File

@@ -0,0 +1,31 @@
# Upgrade notes for SimpleSAMLphp 1.15
The minimum required PHP version is now 5.4. The dependency on mcrypt has been
dropped.
A new templating system based on Twig has been introduced. The old templating
system is still available but should be considered deprecated. Custom themes
may need to be updated to include Twig-style templates as well. See the
[theming documentation](simplesamlphp-theming).
A new internationalization system based on Gettext has been introduced. While
old templates can use either the old or the new system (refer to the
"language.i18n.backend" configuration option for more information on how to
choose the internationalization backend), new Twig templates can only use the
new Gettext internationalization system.
The integrated _Auth Memcookie_ support is now deprecated and will no longer
be available starting in SimpleSAMLphp 2.0. Please use the new
[memcookie module](https://github.com/simplesamlphp/simplesamlphp-module-memcookie)
instead.
The option to specify a SAML certificate by its fingerprint, `certFingerprint`
has been deprecated and will be removed in a future release. Please use the
full certificate in `certData` instead.
The `core:AttributeRealm` authproc filter has been deprecated.
Please use `core:ScopeFromAttribute`, which is a generalised version of this.
simpleSAMLphp will now send the eduPersonTargetedID attribute in the correct
NameID XML form, instead of the incorrect simple string. It will also refuse
to parse an assertion with an eduPersonTargetedID in 'string' format.

25
plugins/simplesaml/lib/docs/simplesamlphp-upgrade-notes-1.16.md Normal file
View File

@@ -0,0 +1,25 @@
# Upgrade notes for SimpleSAMLphp 1.16
The default signature algorithm is now SHA-256 (SHA-1 has been considered
obsolete since 2014). For entities that need it, you can switch back to
SHA-1 by setting the `signature.algorithm` option in the remote entity
metadata.
In the Consent module, the `noconsentattributes` has been renamed to
`attributes.exclude`. The old name continues to work but is considered
deprecated.
The class `SimpleSAML_Error_BadUserInnput` has been renamed to
`SimpleSAML_Error_BadUserInput`.
The `authmyspace` module has been removed since the service is no longer
available.
The `casserver` module has been removed because it was an outdated version,
the up to date module is maintained in the
[simplesamlphp-module-casserver](https://github.com/simplesamlphp/simplesamlphp-module-casserver)
repository. It can be installed with composer:
```bash
composer require simplesamlphp/simplesamlphp-module-casserver
```

37
plugins/simplesaml/lib/docs/simplesamlphp-upgrade-notes-1.17.md Normal file
View File

@@ -0,0 +1,37 @@
# Upgrade notes for SimpleSAMLphp 1.17
The minimum PHP version required is now PHP 5.5.
All (remaining) classes have been changed to namespaces. There are mappings
from the legacy names so calling code should remain working. Custom code
(e.g. modules) that test for class names, e.g. when catching specific
exceptions, may need to be changed.
The possibility has been reintroduced to omit the NameIdPolicy from SP
AuthnRequests by setting NameIDPolicy to `false`. The preferred way is
to configure it as an array `[ 'Format' => format, 'AllowCreate' => true/false ]`,
which is now also the format used in the `saml:NameIDPolicy` variable
in `$state`.
The code, config and documentation have switched to using the modern PHP
array syntax. This should not have an impact as both will remain working
equally, but the code examples and config templates look slightly different.
The following are equivalent:
```php
// Old style array syntax
$config = array(
'authproc' => array(
60 => 'class:etc'
),
'other example' => 1
);
// Current style array syntax
$config = [
'authproc' => [
60 => 'class:etc'
],
'other example' => 1
];
```

29
plugins/simplesaml/lib/docs/simplesamlphp-upgrade-notes-1.18.md Normal file
View File

@@ -0,0 +1,29 @@
# Upgrade notes for SimpleSAMLphp 1.18
The minimum PHP version required is now PHP 5.6.
## Deprecations
* The use of the PHP `memcache` extension was deprecated in favour of `memcached`.
In order to keep using memcache functionality you have to move to the PHP `memcached` extension,
which is available from PECL; see [memcached][1]. The former is considered abandoned
and it's safe use can no longer be guaranteed.
There are a few options here:
* Depending on your distribution, the package may just be available for you to install
* You could use the package from the [REMI repository][2] if you're on RHEL.
* Download the source from [memcached][1] and [compile][3] the source as a PHP-extension manually.
* Support for SAML1.1 / Shibboleth 1.3 will be discontinued in a future release.
* The class `SimpleSAML\Auth\TimeLimitedToken` is now deprecated and will be removed in a future release
If your custom module relies on this class, be sure to make a copy into your repository and
make sure to also copy the unit tests that come along.
* Setting `privacypolicy` in metadata files will be removed in a future release. It was only used
by the consent module, which supports `UIInfo`'s `PrivacyStatementURL`.
See [Metadata extensions][4] on how to configure this.
[1]: https://pecl.php.net/package/memcached
[2]: https://rpms.remirepo.net
[3]: https://www.php.net/manual/en/install.pecl.phpize.php
[4]: https://simplesamlphp.org/docs/stable/simplesamlphp-metadata-extensions-ui

3
plugins/simplesaml/lib/docs/simplesamlphp-upgrade-notes-1.19.md Normal file
View File

@@ -0,0 +1,3 @@
# Upgrade notes for SimpleSAMLphp 1.19
The minimum PHP version required is now PHP 7.0.

21
plugins/simplesaml/lib/docs/simplesamlphp-upgrade-notes-1.5.md Normal file
View File

@@ -0,0 +1,21 @@
# Upgrade notes for SimpleSAMLphp 1.5
* `SimpleSAML_Session::isValid()`
If your code calls `$session->isValid()` without an argument, you will now have to update it to pass an argument (probably `saml2`).
The reason for this change is that calling `$session->isValid()` without an argument can easily create a security hole.
* We have introduced a new module for SAML authentication.
This authentication module supports both SAML 1.1 and SAML 2.0 IdPs.
We have also added a new authentication framework which should replace the previous redirects to the initSSO-scripts.
Relating to this change, we have also deprecated the `initSSO`-scripts for SAML 1.1 and SAML 2.0 authentication.
The old methods will still be supported for a while, but new code should probably use the new code.
See the [migration guide](simplesamlphp-sp-migration) for more information about this.
* The `request.signing` option has been removed.
That option was replaced with the `redirect.sign` and `redirect.validate` options, and has been deprecated for one year.
* The `aggregator` module's configuration file has changed name.
It was changed from `aggregator.php` to `module_aggregator.php`.

21
plugins/simplesaml/lib/docs/simplesamlphp-upgrade-notes-1.6.md Normal file
View File

@@ -0,0 +1,21 @@
# Upgrade notes for SimpleSAMLphp 1.6
* This release requires PHP version >= 5.2.0, as that was the first version to include `json_decode()`.
It is possible that it may work with version of PHP >= 5.1.2 if the [JSON PECL extension](http://pecl.php.net/package/json) is enabled, but this is untested.
* The secure-flag is no longer automatically set on the session cookie.
This was changed to avoid hard to diagnose session problems.
There is a new option `session.cookie.secure` in `config.php`, which can be used to enable secure cookies.
* Dictionaries have moved to JSON format.
The PHP format is still supported, but all dictionaries included with SimpleSAMLphp are in JSON format.
* The iframe-specific logout endpoints on the IdP have been merged into the normal logout endpoints.
This means that the metadata no longer needs to be changed when switching between logout handlers.
The old iframe logout endpoints are now deprecated, and the generated metadata will only include the normal logout endpoint.
* As a result of the changed metadata classes, all metadata elements now have a `md:`-prefix.
This does not change the content of the metadata, just its expression.
* The deprecated functions `init(...)` and `setAuthenticated(...)` in the `SimpleSAML_Session` class have been removed.
Code which relies on those functions should move to using `SimpleSAML_Session::getInstance()` and `$session->doLogin(...)`.

11
plugins/simplesaml/lib/docs/simplesamlphp-upgrade-notes-1.7.md Normal file
View File

@@ -0,0 +1,11 @@
# Upgrade notes for SimpleSAMLphp 1.7
* The attribute names generated by the twitter and facebook authentication sources have changed.
* Several new options have been added to config.php, and some have been renamed.
The old options should still work, but it is suggested that you look at the config.php file in config-templates, and compare it to your own.
* There have been several changes to the internal API.
Most of the changes will not be noticed by the application using SimpleSAMLphp.
See the changelog for more details about the changes.
* Relative redirects are no longer supported.
If your application passes relative URL's to the `SimpleSAML_Utilities::redirect()`-function, it will no longer work.
This also applies if you pass relative URL's to other functions that do redirects.

7
plugins/simplesaml/lib/docs/simplesamlphp-upgrade-notes-1.8.md Normal file
View File

@@ -0,0 +1,7 @@
# Upgrade notes for SimpleSAMLphp 1.8
* The IdP now sends the NotOnOrAfter attribute in LogoutRequest messages.
* We now have full support for selecting the correct AssertionConsumerService endpoint based on parameters in the authentication request.
As a side effect of this, an IdP may start sending responses to a new AssertionConsumerService endpoint after upgrade.
(This should only happen in the case where it sent the response to the wrong endpoint before.)
* The SP no longer incorrectly returns PartialLogout as a status code in a LogoutResponse after the local session has expired.

10
plugins/simplesaml/lib/docs/simplesamlphp-upgrade-notes-1.9.md Normal file
View File

@@ -0,0 +1,10 @@
# Upgrade notes for SimpleSAMLphp 1.9
* The OpenID client "linkback" URL has changed from `.../module.php/openid/consumer.php` to `.../module.php/openid/linkback.php`.
* Support for CA path validation has been removed from SAML 2.0.
* The X-Frame-Options has been added to the default templates, to prevent the pages from being loaded in iframes.
* Access permissions of generated files are now restricted to the current user.
* The code to set cookies now requires PHP version >= 5.2. (PHP version 5.2.0 or newer has been the only supported version for a while, but it has in some cases been possible to run SimpleSAMLphp with older versions.)
* It used to be possible to set an array of endpoints for the SingleSignOnService in `saml20-idp-hosted.php`. That is no longer supported.
* The `aselect` module has been replaced with a new module. The new module gives us better error handling and support for request signing, but we lose support for A-Select Cross.
* There has been various fixes in the session expiration handling. As a result of this, sessions may get a shorter lifetime (if the IdP places a limit on the lifetime, this limit will now be honored).

194
plugins/simplesaml/lib/docs/simplesamlphp-upgrade-notes-2.0.md Normal file
View File

@@ -0,0 +1,194 @@
# Upgrade notes for SimpleSAMLphp 2.0
SimpleSAMLphp 2.0 is a major new release which has cleaned up support for a
lot of things that have been marked deprecated in previous SimpleSAMLphp
releases. The following changes are relevant for installers and/or developers.
## Software requirements
- The minimum PHP version required is now PHP 7.4.
- Dropped support for Symfony 4 and Twig 2.
## Not all modules included by default
The set of modules included in the base installation has been reduced.
If you used some of the modules that were shipped with SimpleSAMLphp, you now have to manually install them using Composer.
For example, to use the LDAP module:
```bash
composer require simplesamlphp/simplesamlphp-module-ldap --update-no-dev
```
## Functional changes
- EntityIDs are no longer auto-generated. Make sure to set something sensible in the array-keys in
`metadata/saml20-idp-hosted.php` and for any saml:SP in `config/authsources.php` (or to the existing entityIDs when
upgrading an existing installation).
If you are using a database to store metadata, make sure to replace any `__DYNAMIC:<n>__` entityID's with
a real value manually. Dynamic records are no longer loaded from the database. See the "Upgrading and EntityIDs"
section at the end of the document for more information.
- Modules must be enabled through the `module.enable` option in `config.php`. Modules can no longer be enabled by having
a file named `enable` or `default-enable` in the module's root directory.
- The base URL of the SimpleSAMLphp installation no longer provides an admin menu. Instead this is now at the location
`<simpleSAMLphp base URL>/admin`. The `admin` module needs to be enabled for this to work.
- SAML AuthnRequests that are signed will have their signature validated unless specifically disabled
by setting `validate.authnrequest` to `false`. If unset (or set to `true`) signatures will be
validated if present and requests not passing validation will be refused.
- The default value for attrname-format was changed to 'urn:oasis:names:tc:SAML:2.0:attrname-format:uri'.
- In the core:TargetedID authproc-filter, the `attributename` setting has been renamed to `identifyingAttribute`.
Similarly, in the saml:AttributeNameID, saml:PersistentNameID and saml:SQLPersistentNameId authproc-filters, the
`attribute` setting has been renamed to `identifyingAttribute` for consistency with other NameID filters.
- The default encryption algorithm is set from `AES128_CBC` to `AES128_GCM`.
It is possible to switch back via the `sharedkey_algorithm`.
Note however that CBC is vulnerable to the Padding oracle attack.
- All support for the Shibboleth 1.3 / SAML 1.1 protocol has been removed.
- Sessions are no longer backwards compatible with previous versions. Make sure to clear your session cache during
the upgrade process. How to do this depends on your session backend.
## Configuration changes
Our assets have been moved from the `www` to the `public` directory. You will have to update your webserver to reflect this change.
Quite some options have been changed or removed. We recommend to start with a fresh
template from `config/config.php.dist` and migrate the settings you require to the new
config file manually.
The date formatting when specifying a custom logging string has been changed from PHP's
deprecated `strftime()` format to PHP's `date()` format.
The format of the `NameIDPolicy` option has been changed: to omit sending the
element entirely, you can no longer specify `false` but need to set it to
an empty array (`[]`).
Configuration options that have been removed:
- `simplesaml.nameidattribute`. Use the appropriate authproc-filters instead.
- `languages[priorities]`. No replacement.
- `attributes.extradictionaries`. Add an attributes.po to your configured theme instead.
- `admin.protectindexpage`. Replaced by the admin module which always requires login.
- `base64attributes`. Obsolete functionality, individual attributes can still be en/decoded
with the existing attributeencodings feature.
- `database.slaves`. This is now called `database.secondaries`.
- `metadata.handler`. Since a long time the preferred option is `metadata.sources`.
## Changes relevant for (module) developers
The following changes are relevant for those having custom developed modules, authentication
processing filters, themes, or that interface with the SimpleSAMLphp development API.
- We expect your source files to exist in the `src/` directory within your module. This used to be the
`lib/` directory, so you have to rename the directory and for composer-modules you have to update
your `composer.json` file (specifically the `psr-0` and `psr-4` entries if you have them).
- We expect your module assets to exist in the `public/` directory within your module (was: `www/`).
- Old JSON-formatted dictionaries have been replaced by gettext / .po-files; see [migration guide][1]
- Old PHP templates have been replaced by Twig-templates; see [migration guide][2]
- The source was completely typehinted; if you have custom authsources or authproc filters,
make sure you change them to reflect the method signatures of the base classes.
- Some hooks are no longer called:
- `frontpage`: replace with `configpage`
- `htmlinject`: use a Twig template override instead.
- `metadata_hosted`: no replacement
- The following classes have been migrated to non-static:
- `\SimpleSAML\Utils\Arrays`
- `\SimpleSAML\Utils\Attributes`
- `\SimpleSAML\Utils\Auth`
- `\SimpleSAML\Utils\Config`
- `\SimpleSAML\Utils\Crypto`
- `\SimpleSAML\Utils\EMail`
- `\SimpleSAML\Utils\HTTP`
- `\SimpleSAML\Utils\Net`
- `\SimpleSAML\Utils\Random`
- `\SimpleSAML\Utils\System`
- `\SimpleSAML\Utils\Time`
- `\SimpleSAML\Utils\XML`
If you use any of these classes in your modules or themes, you will now have to instantiate them so that:
```php
// Old style
$x = \SimpleSAML\Utils\Arrays::arrayize($someVar)
```
becomes:
```php
// New style
$arrayUtils = new \SimpleSAML\Utils\Arrays();
$x = $arrayUtils->arrayize($someVar);
```
- Database table schemes have been flattened. Upgrade paths are:
- Generic KVStore: 1.16+ > 2.0
- Logout store: 1.18+ > 2.0
- Data stores have been refactored:
- `lib/SimpleSAML/Store.php` has been renamed to `lib/SimpleSAML/Store/StoreFactory.php` and is now solely a Factory-class
- All store implementations now implement `\SimpleSAML\Store\StoreInterface`:
- `lib/SimpleSAML/Store/SQL.php` has been renamed to `lib/SimpleSAML/Store/SQLStore.php`
- `lib/SimpleSAML/Store/Memcache.php` has been renamed to `lib/SimpleSAML/Store/MemcacheStore.php`
- `lib/SimpleSAML/Store/Redis.php` has been renamed to `lib/SimpleSAML/Store/RedisStore.php`
- The following methods have had their signature changed:
- `Configuration::getValue`
- `Configuration::getBoolean`
- `Configuration::getString`
- `Configuration::getInteger`
- `Configuration::getIntegerRange`
- `Configuration::getValueValidate`
- `Configuration::getArray`
- `Configuration::getArrayize`
- `Configuration::getArrayizeString`
- `Configuration::getConfigItem`
- `Configuration::getLocalizedString`
All of these methods no longer accept a default as their last parameter. Use their getOptional* counterparts instead.
[1]: https://github.com/simplesamlphp/simplesamlphp/wiki/Migrating-translations-(pre-migration)
[2]: https://github.com/simplesamlphp/simplesamlphp/wiki/Twig:-Migrating-templates
## Upgrading and EntityIDs
If you still have your 1.x installation available, the entityID you
are using for your SP and IdP should be available in
module.php/core/frontpage_federation.php location on your
SimpleSAMLphp server.
For a service provider, if it was set as auto-generated in 1.19, it
will likely have the form of (<https://yourhostname/simplesaml/module.php/saml/sp/metadata.php/default-sp>).
The EntityID is set in two locations, as the property 'entityID' for
an SP and as the index in the $metadata array for an IdP. Examples of
both are shown below.
For the SP you can set the EntityID as shown in the below fragment of
authsources.php. In all of the below configuration fragments the
EntityID is set to (<https://example.com/the-service/>).
```php
...
'default-sp' => [
'saml:SP',
// The entity ID of this SP.
'entityID' => 'https://example.com/the-service/',
...
```
One suggestion for forming an EntityID is to use the below scheme.
```php
$entityid_sp = 'https://'
. $_SERVER['HTTP_HOST']
. '/simplesaml/module.php/saml/sp/metadata.php/default-sp';
```
For an IdP you might like to look at saml20-idp-hosted.php where the
EntityID is used as the key in the metadata array.
```php
...
$metadata['https://example.com/the-service/'] = [
...
```
If you use SimpleSAMLphp as an SP, the IdP you are using will have
your correct entityID configured.

23
plugins/simplesaml/lib/docs/simplesamlphp-upgrade-notes-2.1.md Normal file
View File

@@ -0,0 +1,23 @@
# Upgrade notes for SimpleSAMLphp 2.1
SimpleSAMLphp 2.1 is a minor new release which bumps some
of the minimum requirements to be able to run SimpleSAMLphp.
The following changes are relevant for installers and/or developers.
## Software requirements
- The minimum PHP version required is now PHP 8.0.
- Dropped support for Symfony 5.4.
## Two builds
As of SimpleSAMLphp 2.1 two builds are created for every release.
The 'slim' build is a lightweight build without any modules other than the core modules installed (alike the 2.0 build).
A new 'full' build is added that will come with the most used modules pre-installed.
## Default security-headers
The default security headers have been adjusted to a more strict set. This may cause issues if you use any modules
or custom themes that use inline CSS or JavaScript. You can adjust these settings in `config.php` using the
`headers.security` setting, but we recommend updating the custom module/theme and move and inline CSS or JavaScript
to a file. All modules within the `simplesamlphp/*` namespace are fixed and should not cause any issues.

29
plugins/simplesaml/lib/docs/simplesamlphp-upgrade-notes-2.2.md Normal file
View File

@@ -0,0 +1,29 @@
# Upgrade notes for SimpleSAMLphp 2.2
SimpleSAMLphp 2.2 is a minor new release which introduces a few new features.
The following changes are relevant for installers and/or developers.
## Software requirements
- The minimum PHP version required is now PHP 8.1.
- Symfony was upgraded to 6.4 (LTS).
## Deprecations
The following methods were marked `deprecated` and will be removed in a next major release.
- SimpleSAML\Error\ErrorCodes::defaultGetAllErrorCodeTitles - Use getDefaultTitles instead
- SimpleSAML\Error\Errorcodes::getCustomErrorCodeTitles - Use getCustomTitles instead
- SimpleSAML\Error\Errorcodes::getAllErrorCodeTitles - Use getAllTitles instead
- SimpleSAML\Error\Errorcodes::defaultGetAllErrorCodeDescriptions - Use getDefaultDescriptions instead
- SimpleSAML\Error\Errorcodes::getCustomErrorCodeDescriptions - Use getCustomErrorCodeDescriptions instead
- SimpleSAML\Error\Errorcodes::getAllErrorCodeDescriptions - Use getAllDescriptions instead
- SimpleSAML\Error\Errorcodes::getAllErrorCodeMessages - Use getAllMessages instead
- SimpleSAML\Error\Errorcodes::getErrorCodeTitle - Use getTitle instead
- SimpleSAML\Error\Errorcodes::getErrorCodeDescription - Use getDescription instead
- SimpleSAML\Error\Errorcodes::getErrorCodeMessage - Use getMessage instead
The `tempdir` configuration setting was marked `deprecated`. Use `cachedir` instead.
The core:StatisticsWithAttribute authproc-filter was removed from SimpleSAMLphp.
It is now available in the statistics-module from v2.1 and up.

38
plugins/simplesaml/lib/docs/simplesamlphp-upgrade-notes-2.3.md Normal file
View File

@@ -0,0 +1,38 @@
# Upgrade notes for SimpleSAMLphp 2.3
SimpleSAMLphp 2.3 is a minor new release which introduces a few new features.
The following changes are relevant for installers and/or developers.
- Session ID's are now hashed when stored in a database. This means all old sessions are effectively
invalidated by this upgrade. We recommend clearing your session store as part of the upgrade-routine.
## Deprecations
The following classes were marked `deprecated` and will be removed in a next major release.
- SimpleSAML\Utils\Net
The following methods were marked `deprecated` and will be removed in a next major release.
- SimpleSAML\Utils\Crypto::aesDecrypt - use the xml-security library instead - See commit `52ef3a78d1faf22e040efd5d0fd1f234da2458eb` for an example.
- SimpleSAML\Utils\Crypto::aesEncrypt - use the xml-security library instead - See commit `52ef3a78d1faf22e040efd5d0fd1f234da2458eb` for an example.
- SimpleSAML\Utils\Crypto::pwHash - Use \Symfony\Component\PasswordHasher\NativePasswordHasher::hash instead
- SimpleSAML\Utils\Crypto::pwValid - Use \Symfony\Component\PasswordHasher\NativePasswordHasher::verify instead
- SimpleSAML\Utils\Crypto::secureCompare - Use hash_equals() instead
- SimpleSAML\Utils\Net::ipCIDRcheck - Use \Symfony\Component\HttpFoundation\IpUtils::checkIp instead
The following properties were marked `deprecated` and will be removed in a next major release.
- SimpleSAML\Locale\Language::$language_names - Use \Symfony\Component\Intl\Languages::getNames() instead
The use of plain-text admin-passwords has been deprecated. Generate a secure hash using the `bin/pwgen.php` script instead.
## BC break
- The language codes `pt-br` and `zh-tw` have been renamed to `pt_BR` and `zh_TW`.
Please update your configuration to match the new names.
- Endpoints in metadata (e.g. "SingleSignOnLocation" and "AssertionCosumerService") can no longer be simple strings and are now only accepted in array-style. The old string-style was deprecated for 9 yrs
already and was broken anyway. See [endpoints] for the current format.
[endpoints]: https://simplesamlphp.org/docs/stable/simplesamlphp-metadata-endpoints.html

26
plugins/simplesaml/lib/docs/simplesamlphp-upgrade-notes.md Normal file
View File

@@ -0,0 +1,26 @@
# SimpeSAMLphp Upgrade Notes
See the following pages for important information for users upgrading
from older versions of SimpleSAMLphp:
* [Upgrade notes for version 2.3](simplesamlphp-upgrade-notes-2.3)
* [Upgrade notes for version 2.2](simplesamlphp-upgrade-notes-2.2)
* [Upgrade notes for version 2.1](simplesamlphp-upgrade-notes-2.1)
* [Upgrade notes for version 2.0](simplesamlphp-upgrade-notes-2.0)
* [Upgrade notes for version 1.19](simplesamlphp-upgrade-notes-1.19)
* [Upgrade notes for version 1.18](simplesamlphp-upgrade-notes-1.18)
* [Upgrade notes for version 1.17](simplesamlphp-upgrade-notes-1.17)
* [Upgrade notes for version 1.16](simplesamlphp-upgrade-notes-1.16)
* [Upgrade notes for version 1.15](simplesamlphp-upgrade-notes-1.15)
* [Upgrade notes for version 1.14](simplesamlphp-upgrade-notes-1.14)
* [Upgrade notes for version 1.13](simplesamlphp-upgrade-notes-1.13)
* [Upgrade notes for version 1.12](simplesamlphp-upgrade-notes-1.12)
* [Upgrade notes for version 1.11](simplesamlphp-upgrade-notes-1.11)
* [Upgrade notes for version 1.10](simplesamlphp-upgrade-notes-1.10)
* [Upgrade notes for version 1.9](simplesamlphp-upgrade-notes-1.9)
* [Upgrade notes for version 1.8](simplesamlphp-upgrade-notes-1.8)
* [Upgrade notes for version 1.7](simplesamlphp-upgrade-notes-1.7)
* [Upgrade notes for version 1.6](simplesamlphp-upgrade-notes-1.6)
A detailed list of changes in each release can be found in the
[Changelog](simplesamlphp-changelog).