Merge pull request #310 from stof/improve_readme

Improve the readme

Author: pitbulk

README.md

@@ -110,7 +110,7 @@ After installation has completed you will find at the `vendor/` folder a new fol
 **Important** In this option, the x509 certs must be stored at `vendor/onelogin/php-saml/certs`
 and settings file stored at `vendor/onelogin/php-saml`.
 
-Your settings are at risk of being deleted when updating packages using `composer update` or similiar commands. So it is **highly** recommended that instead of using settings files, you pass the settings as an array directly to the constructor (explained later in this document). If you do not use this approach your settings are at risk of being deleted when updating packages using `composer update` or similiar commands.
+Your settings are at risk of being deleted when updating packages using `composer update` or similar commands. So it is **highly** recommended that instead of using settings files, you pass the settings as an array directly to the constructor (explained later in this document). If you do not use this approach your settings are at risk of being deleted when updating packages using `composer update` or similar commands.
 
 Compatibility
 -------------
@@ -120,11 +120,11 @@ This 3.X.X supports PHP 7.X. but can be used with PHP >=5.4 as well  (5.6.24+ re
 Namespaces
 ----------
 
-If you are using the library with a framework like Symfony2 that contains
+If you are using the library with a framework like Symfony that contains
 namespaces, remember that calls to the class must be done by adding a backslash (`\`) to the
 start, for example to use the static method getSelfURLNoQuery use:
 
-    OneLogin\Saml2\Utils::getSelfURLNoQuery()
+    \OneLogin\Saml2\Utils::getSelfURLNoQuery()
 
 
 Security warning
@@ -135,7 +135,7 @@ In production, the `strict` parameter **MUST** be set as `"true"` and the
 something other than SHA1 (see https://shattered.io/ ). Otherwise your
 environment is not secure and will be exposed to attacks.
 
-In production also we highly recommended to register on the settings the IdP certificate instead of using the fingerprint method. The fingerprint, is a hash, so at the end is open to a collision attack that can end on a siganture validation bypass. Other SAML toolkits deprecated that mechanism, we maintain it for compatibility and also to be used on test environment.
+In production also we highly recommended to register on the settings the IdP certificate instead of using the fingerprint method. The fingerprint, is a hash, so at the end is open to a collision attack that can end on a signature validation bypass. Other SAML toolkits deprecated that mechanism, we maintain it for compatibility and also to be used on test environment.
 
 Getting started
 ---------------
@@ -149,26 +149,26 @@ Let's start describing the folders:
 
 #### `certs/` ####
 
-SAML requires a x.509 cert to sign and encrypt elements like `NameID`, `Message`,
+SAML requires a x509 cert to sign and encrypt elements like `NameID`, `Message`,
 `Assertion`, `Metadata`.
 
 If our environment requires sign or encrypt support, this folder may contain
 the x509 cert and the private key that the SP will use:
 
  * `sp.crt` - The public cert of the SP
- * `sp.key` - The privake key of the SP
+ * `sp.key` - The private key of the SP
 
 Or also we can provide those data in the setting file at the `$settings['sp']['x509cert']`
 and the `$settings['sp']['privateKey']`.
 
 Sometimes we could need a signature on the metadata published by the SP, in
-this case we could use the x.509 cert previously mentioned or use a new x.509
+this case we could use the x509 cert previously mentioned or use a new x.509
 cert: `metadata.crt` and `metadata.key`.
 
 Use `sp_new.crt` if you are in a key rollover process and you want to
-publish that x509certificate on Service Provider metadata.
+publish that x509 certificate on Service Provider metadata.
 
-#### `lib/` ####
+#### `src/` ####
 
 This folder contains the heart of the toolkit, the libraries:
 
@@ -218,8 +218,6 @@ and support multiple languages.
 * `demo1/` - Contains an example of a simple PHP app with SAML support.
   Read the `Readme.txt` inside for more info.
 * `demo2/` - Contains another example.
-* `demo-old/` - Contains an example that uses the code of the older version of the
-  the toolkit to demonstrate the backwards compatibility.
 
 
 ### How it works ###
@@ -509,7 +507,7 @@ $advancedSettings = array (
 
 The compression settings allow you to instruct whether or not the IdP can accept
 data that has been compressed using [gzip](gzip) ('requests' and 'responses').
-But if we provide a $deflate boolean parameter to the getRequest or getResponse method it will have priority over the compression settings.
+But if we provide a `$deflate` boolean parameter to the `getRequest` or `getResponse` method it will have priority over the compression settings.
 
 In the security section, you can set the way that the SP will handle the messages
 and assertions. Contact the admin of the IdP and ask him what the IdP expects,
@@ -520,7 +518,7 @@ Once we know what kind of data could be configured, let's talk about the way
 settings are handled within the toolkit.
 
 The settings files described (`settings.php` and `advanced_settings.php`) are loaded
-by the toolkit if not other array with settings info is provided in the constructors of the toolkit. Let's see some examples.
+by the toolkit if no other array with settings info is provided in the constructor of the toolkit. Let's see some examples.
 
 ```php
 // Initializes toolkit with settings.php & advanced_settings files.
@@ -534,7 +532,7 @@ $auth = new OneLogin\Saml2\Auth($settingsInfo);
 $settings = new OneLogin\Saml2\Settings($settingsInfo);
 ```
 
-You can declare the `$settingsInfo` in the file that constains the constructor
+You can declare the `$settingsInfo` in the file that contains the constructor
 execution or locate them in any file and load the file in order to get the
 array available as we see in the following example:
 
@@ -592,9 +590,9 @@ The `AuthNRequest` will be sent signed or unsigned based on the security info
 of the `advanced_settings.php` (`'authnRequestsSigned'`).
 
 
-The IdP will then return the SAML Response to the user's client. The client is then forwarded to the Attribute Consumer Service of the SP with this information. If we do not set a 'url' param in the login method and we are using the default ACS provided by the toolkit (`endpoints/acs.php`), then the ACS endpoint will redirect the user to the file that launched the SSO request.
+The IdP will then return the SAML Response to the user's client. The client is then forwarded to the Attribute Consumer Service of the SP with this information. If we do not set a `'url'` param in the login method and we are using the default ACS provided by the toolkit (`endpoints/acs.php`), then the ACS endpoint will redirect the user to the file that launched the SSO request.
 
-We can set an `'returnTo'` url to change the workflow and redirect the user to the other PHP file.
+We can set a `'returnTo'` url to change the workflow and redirect the user to the other PHP file.
 
 ```php
 $newTargetUrl = 'http://example.com/consume2.php';
@@ -661,7 +659,8 @@ Before the XML metadata is exposed, a check takes place to ensure
 that the info to be provided is valid.
 
 Instead of use the Auth object, you can directly use
-```
+
+```php
 $settings = new OneLogin\Saml2\Settings($settingsInfo, true);
 ```
 to get the settings object and with the true parameter we will avoid the IdP Settings validation.
@@ -1086,11 +1085,11 @@ php-saml toolkit uses a bunch of methods in OneLogin\Saml2\Utils that try to gue
 
 getSelfURLNoQuery and getSelfRoutedURLNoQuery are used to calculate the currentURL in order to valdate SAML elements like Destination or Recipient.
 
-When the PHP application is behind a proxy or a load balancer we can execute setProxyVars(true) and getSelfPort and isHTTPS will take care of the $_SERVER["HTTP_X_FORWARDED_PORT"] and $_SERVER['HTTP_X_FORWARDED_PROTO'] vars (otherwise they are ignored).
+When the PHP application is behind a proxy or a load balancer we can execute `setProxyVars(true)` and `setSelfPort` and `isHTTPS` will take care of the `$_SERVER["HTTP_X_FORWARDED_PORT"]` and `$_SERVER['HTTP_X_FORWARDED_PROTO']` vars (otherwise they are ignored).
 
-Also a developer can use setSelfProtocol, setSelfHost, setSelfPort and getBaseURLPath to define a specific value to be returned by isHTTPS, getSelfHost, getSelfPort and getBaseURLPath. And define a setBasePath to be used on the getSelfURL and getSelfRoutedURLNoQuery to replace the data extracted from $_SERVER["REQUEST_URI"].
+Also a developer can use `setSelfProtocol`, `setSelfHost`, `setSelfPort` and `getBaseURLPath` to define a specific value to be returned by `isHTTPS`, `getSelfHost`, `getSelfPort` and `getBaseURLPath`. And define a `setBasePath` to be used on the `getSelfURL` and `getSelfRoutedURLNoQuery` to replace the data extracted from `$_SERVER["REQUEST_URI"]`.
 
-At the settings the developer will be able to set a 'baseurl' parameter that automatically will use setBaseURL to set values for setSelfProtocol, setSelfHost, setSelfPort and setBaseURLPath.
+At the settings the developer will be able to set a `'baseurl'` parameter that automatically will use `setBaseURL` to set values for `setSelfProtocol`, `setSelfHost`, `setSelfPort` and `setBaseURLPath`.
 
 
 ### Working behind load balancer ###
@@ -1104,7 +1103,7 @@ Or by using the method described on the previous section.
 
 ### SP Key rollover ###
 
-If you plan to update the SP x509cert and privateKey you can define the new x509cert as $settings['sp']['x509certNew'] and it will be
+If you plan to update the SP x509cert and privateKey you can define the new x509cert as `$settings['sp']['x509certNew']` and it will be
 published on the SP metadata so Identity Providers can read them and get ready for rollover.
 
 
@@ -1113,20 +1112,20 @@ published on the SP metadata so Identity Providers can read them and get ready f
 In some scenarios the IdP uses different certificates for
 signing/encryption, or is under key rollover phase and more than one certificate is published on IdP metadata.
 
-In order to handle that the toolkit offers the $settings['idp']['x509certMulti'] parameter.
+In order to handle that the toolkit offers the `$settings['idp']['x509certMulti']` parameter.
 
-When that parameter is used, 'x509cert' and 'certFingerprint' values will be ignored by the toolkit.
+When that parameter is used, `'x509cert'` and `'certFingerprint'` values will be ignored by the toolkit.
 
-The 'x509certMulti' is an array with 2 keys:
-- 'signing'. An array of certs that will be used to validate IdP signature
-- 'encryption' An array with one unique cert that will be used to encrypt data to be sent to the IdP
+The `x509certMulti` is an array with 2 keys:
+- `signing`. An array of certs that will be used to validate IdP signature
+- `encryption` An array with one unique cert that will be used to encrypt data to be sent to the IdP
 
 
 ### Replay attacks ###
 
 In order to avoid replay attacks, you can store the ID of the SAML messages already processed, to avoid processing them twice. Since the Messages expires and will be invalidated due that fact, you don't need to store those IDs longer than the time frame that you currently accepting.
 
-Get the ID of the last processed message/assertion with the getLastMessageId/getLastAssertionId method of the Auth object.
+Get the ID of the last processed message/assertion with the `getLastMessageId`/`getLastAssertionId` methods of the Auth object.
 
 
 ### Main classes and methods ###

demo1/Readme.txt

@@ -19,7 +19,7 @@ file is loaded in order to get the $settingsInfo var to be used to initialize
 the Setting class.
 
 Notice that in this demo, the setting.php file that could be defined at the base
-folder of the toolkit is ignored and the libs are loaded using the 
+folder of the toolkit is ignored and the libs are loaded using the
 _toolkit_loader.php located at the base folder of the toolkit.
 
 
@@ -37,40 +37,40 @@ How it works
     to the same view or login and be redirected to the attrs.php view.
 
  2. When you click:
- 
+
     2.1 in the first link, we access to (index.php?sso) an AuthNRequest
     is sent to the IdP, we authenticate at the IdP and then a Response is sent
     to the SP, specifically the Assertion Consumer Service view: index.php?acs,
     notice that a RelayState parameter is set to the url that initiated the
     process, the index.php view.
 
-    2.2 in the second link we access to (attrs.php) have the same process 
+    2.2 in the second link we access to (attrs.php) have the same process
     described at 2.1 with the diference that as RelayState is set the attrs.php
 
 3. The SAML Response is processed in the ACS (index.php?acs), if the Response
    is not valid, the process stop here and a message is showed. Otherwise we
    are redirected to the RelayState view. a) index.php or b) attrs.php
 
-4. We are logged in the app and the user attributes are showed. 
+4. We are logged in the app and the user attributes are showed.
    At this point, we can test the single log out functionality.
 
-5. The single log out funcionality could be tested by 2 ways.
+5. The single log out functionality could be tested by 2 ways.
 
     5.1 SLO Initiated by SP. Click on the "logout" link at the SP, after that a
-    Logout Request is sent to the IdP, the session at the IdP is closed and 
+    Logout Request is sent to the IdP, the session at the IdP is closed and
     replies to the SP a Logout Response (sent to the Single Logout Service
     endpoint). The SLS endpoint (index.php?sls)of the SP process the Logout
     Response and if is valid, close the user session of the local app. Notice
     that the SLO Workflow starts and ends at the SP.
-   
+
     5.2 SLO Initiated by IdP. In this case, the action takes place on the IdP
-    side, the logout process is initiated at the idP, sends a Logout 
+    side, the logout process is initiated at the idP, sends a Logout
     Request to the SP (SLS endpoint, index.php?sls). The SLS endpoint of the SP
     process the Logout Request and if is valid, close the session of the user
     at the local app and send a Logout Response to the IdP (to the SLS endpoint
     of the IdP). The IdP recieve the Logout Response, process it and close the
     session at of the IdP. Notice that the SLO Workflow starts and ends at the IdP.
-    
+
 Notice that all the SAML Requests and Responses are handler at a unique file,
 the index.php file and how GET paramters are used to know the action that
 must be done.