diff --git a/docs/simplesamlphp-reference-sp-remote.md b/docs/simplesamlphp-reference-sp-remote.md
index efcffc2e3c02582ecaa536be8a8fa1377a39c453..77213e64911a2a2a49a4822920a1e0e5e176f1f1 100644
--- a/docs/simplesamlphp-reference-sp-remote.md
+++ b/docs/simplesamlphp-reference-sp-remote.md
@@ -6,15 +6,18 @@ SP remote metadata reference
This is a reference for metadata options available for `metadata/saml20-sp-remote.php`.
Both files have the following format:
- <?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. */
- ];
- /* ... */
+
+```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
@@ -114,9 +117,9 @@ The following options can be set:
the actual value used is fetched from metadata by the following
priority:
-: 1. SP Remote Metadata
-
- 2. IdP Hosted Metadata
+:
+ 1. SP Remote Metadata
+ 2. IdP Hosted Metadata
: The default value is:
`urn:oasis:names:tc:SAML:2.0:attrname-format:uri`
@@ -124,13 +127,9 @@ The following options can be set:
: 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)
+: - `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.
@@ -174,7 +173,8 @@ The following options can be set:
: The three most commonly used values are:
-: 1. `urn:oasis:names:tc:SAML:2.0:nameid-format:transient`
+:
+ 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`
@@ -213,12 +213,12 @@ The following options can be set:
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`
+: * `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`
+: * `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`
+: * `http://www.w3.org/2001/04/xmldsig-more#rsa-sha384`
+: * `http://www.w3.org/2001/04/xmldsig-more#rsa-sha512`
`signature.privatekey`
: Name of private key file for this IdP, in PEM format. The filename is relative to the cert/-directory.
@@ -276,9 +276,9 @@ The following options can be set:
: 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
+: - 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.
@@ -323,12 +323,12 @@ of the SP.
`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
+: * `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
diff --git a/docs/simplesamlphp-sp.md b/docs/simplesamlphp-sp.md
index 7191577c28f3acabbedd05d0081263fd0a73c8a5..d169793dd83f8b019b3cde565f6a25c128ac0da8 100644
--- a/docs/simplesamlphp-sp.md
+++ b/docs/simplesamlphp-sp.md
@@ -14,27 +14,31 @@ The SP is configured by an entry in `config/authsources.php`.
This is a minimal `authsources.php` for a SP:
- <?php
- $config = [
+```php
+<?php
+$config = [
- /* This is the name of this authentication source, and will be used to access it later. */
- 'default-sp' => [
- 'saml:SP',
- ],
- ];
+ /* This is the name of this authentication source, and will be used to access it later. */
+ 'default-sp' => [
+ 'saml:SP',
+ ],
+];
+```
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:
- 'sp1' => [
- 'saml:SP',
- 'entityID' => 'https://sp1.example.org/',
- ],
- 'sp2' => [
- 'saml:SP',
- 'entityID' => 'https://sp2.example.org/',
- ],
+```php
+ 'sp1' => [
+ 'saml:SP',
+ 'entityID' => 'https://sp1.example.org/',
+ ],
+ 'sp2' => [
+ 'saml:SP',
+ 'entityID' => 'https://sp2.example.org/',
+ ],
+```
### Enabling a certificate for your Service Provider
@@ -48,12 +52,13 @@ Create a self-signed certificate in the `cert/` directory.
Then edit your `authsources.php` entry, and add references to your certificate:
- 'default-sp' => [
- 'saml:SP',
- 'privatekey' => 'saml.pem',
- 'certificate' => 'saml.crt',
- ],
-
+```php
+ 'default-sp' => [
+ 'saml:SP',
+ 'privatekey' => 'saml.pem',
+ 'certificate' => 'saml.crt',
+ ],
+```
Adding IdPs to the SP
---------------------
@@ -61,12 +66,14 @@ 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
- $metadata['https://example.com'] = [
- 'SingleSignOnService' => 'https://example.com/simplesaml/saml2/idp/SSOService.php',
- 'SingleLogoutService' => 'https://example.com/simplesaml/saml2/idp/SingleLogoutService.php',
- 'certificate' => 'example.pem',
- ];
+```php
+<?php
+$metadata['https://example.com'] = [
+ 'SingleSignOnService' => 'https://example.com/simplesaml/saml2/idp/SSOService.php',
+ 'SingleLogoutService' => 'https://example.com/simplesaml/saml2/idp/SingleLogoutService.php',
+ 'certificate' => 'example.pem',
+];
+```
`example.pem` under your `cert/` directory contains the certificate the identity provider uses for signing assertions.
@@ -83,20 +90,21 @@ 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
- $config = [
-
- 'default-sp' => [
- 'saml:SP',
+```php
+<?php
+$config = [
- /*
- * 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://idp.example.com',
- ],
- ];
+ '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://idp.example.com',
+ ],
+];
+```
Exchange metadata with the IdP
------------------------------
@@ -148,28 +156,38 @@ Example code:
We start off with loading a file which registers the SimpleSAMLphp classes with the autoloader.
- require_once('../../lib/_autoload.php');
+```php
+require_once('../../lib/_autoload.php');
+```
We select our authentication source:
- $as = new \SimpleSAML\Auth\Simple('default-sp');
+```php
+$as = new \SimpleSAML\Auth\Simple('default-sp');
+```
We then require authentication:
- $as->requireAuth();
+```php
+$as->requireAuth();
+```
And print the attributes:
- $attributes = $as->getAttributes();
- print_r($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:
- $as->login([
- 'saml:idp' => 'https://idp.example.org/',
- ]);
+```php
+$as->login([
+ 'saml:idp' => 'https://idp.example.org/',
+]);
+```
Other options are also available.
Take a look in the documentation for the [SP module](./saml:sp) for a list of all parameters.
@@ -178,31 +196,34 @@ If we are using PHP sessions in SimpleSAMLphp and in the application we are prot
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:
- $session = \SimpleSAML\Session::getSessionFromRequest();
- $session->cleanup();
+```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:
- // 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();
+```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