Merge pull request #195 from onelogin/key_rollover_mngmt

Improve Key Rollover management

Author: pitbulk

README.md

@@ -157,6 +157,9 @@ Or also we can provide those data in the setting file at the 'x509cert' and the
 
 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 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.
+
 If you want to create self-signed certs, you can do it at the https://www.samltool.com/self_signed_certs.php service, or using the command:
 
 ```bash
@@ -279,6 +282,15 @@ This is the settings.json file:
         // the certs folder. But we can also provide them with the following parameters
         "x509cert": "",
         "privateKey": ""
+
+        /*
+         * Key rollover
+         * If you plan to update the SP x509cert and privateKey
+         * you can define here the new x509cert and it will be 
+         * published on the SP metadata so Identity Providers can
+         * read them and get ready for rollover.
+         */
+        // 'x509certNew': '',
     },
 
     // Identity Provider Data that we want connected with our SP.
@@ -320,8 +332,24 @@ This is the settings.json file:
          *  Notice that if you want to validate any SAML Message sent by the HTTP-Redirect binding, you
          *  will need to provide the whole x509cert.
          */
-        // 'certFingerprint' => '',
-        // 'certFingerprintAlgorithm' => 'sha1',
+        // 'certFingerprint': '',
+        // 'certFingerprintAlgorithm': 'sha1',
+
+        /* 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 that parameter.
+         * (when used, 'x509cert' and 'certFingerprint' values are
+         * ignored).
+         */
+        // 'x509certMulti': {
+        //      'signing': [
+        //          '<cert1-string>'
+        //      ],
+        //      'encryption': [
+        //          '<cert2-string>'
+        //      ]
+        // }
     }
 }
 ```
@@ -475,6 +503,23 @@ json_data_file.close()
 auth = OneLogin_Saml2_Auth(req, settings_data)
 ```
 
+#### Metadata Based Configuration
+
+The method above requires a little extra work to manually specify attributes about the IdP. (And your SP application)
+
+There's an easier method -- use a metadata exchange.  Metadata is just an XML file that defines the capabilities of both the IdP and the SP application.  It also contains the X.509 public key certificates which add to the trusted relationship.  The IdP administrator can also configure custom settings for an SP based on the metadata.
+
+Using ````parse_remote```` IdP metadata can be obtained and added to the settings withouth further ado.
+
+``
+idp_data = OneLogin_Saml2_IdPMetadataParser.parse_remote('https://example.com/auth/saml2/idp/metadata')
+``
+
+If the Metadata contains several entities, the relevant EntityDescriptor can be specified when retrieving the settings from the IdpMetadataParser by its Entity Id value:
+
+idp_data = OneLogin_Saml2_IdPMetadataParser.parse_remote(https://example.com/metadatas, entity_id='idp_entity_id')
+
+
 #### How load the library ####
 
 In order to use the toolkit library you need to import the file that contains the class that you will need
@@ -815,6 +860,25 @@ else:
   print ', '.join(errors)
 ```
 
+### 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 
+published on the SP metadata so Identity Providers can read them and get ready for rollover.
+
+
+### IdP with multiple certificates ###
+
+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.
+
+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
+
 
 ### Main classes and methods ###
 
@@ -924,14 +988,17 @@ Configuration of the OneLogin Python Toolkit
 * ***check_sp_certs*** Checks if the x509 certs of the SP exists and are valid.
 * ***get_sp_key*** Returns the x509 private key of the SP.
 * ***get_sp_cert*** Returns the x509 public cert of the SP.
+* ***get_sp_cert_new*** Returns the future x509 public cert of the SP.
 * ***get_idp_cert*** Returns the x509 public cert of the IdP.
 * ***get_sp_data*** Gets the SP data.
 * ***get_idp_data*** Gets the IdP data.
 * ***get_security_data***  Gets security data.
 * ***get_contacts*** Gets contacts data.
 * ***get_organization*** Gets organization data.
 * ***format_idp_cert*** Formats the IdP cert.
+* ***format_idp_cert_multi*** Formats all registered IdP certs.
 * ***format_sp_cert*** Formats the SP cert.
+* ***format_sp_cert_new*** Formats the SP cert new.
 * ***format_sp_key*** Formats the private key.
 * ***set_strict*** Activates or deactivates the strict mode.
 * ***is_strict*** Returns if the 'strict' mode is active.
@@ -992,6 +1059,9 @@ A class that contains methods to obtain and parse metadata from IdP
 
 For more info, look at the source code; each method is documented and details about what does and how to use it are provided. Make sure to also check the doc folder where HTML documentation about the classes and methods is provided.
 
+
+
+
 Demos included in the toolkit
 -----------------------------
 

demo-bottle/saml/certs/README

@@ -2,8 +2,9 @@ Take care of this folder that could contain private key. Be sure that this folde
 
 Onelogin Python Toolkit expects that certs for the SP could be stored in this folder as:
 
- * sp.key   Private Key
- * sp.crt  Public cert
+ * sp.key     Private Key
+ * sp.crt     Public cert
+ * sp_new.crt Future Public cert
 
 Also you can use other cert to sign the metadata of the SP using the:
 

demo-django/saml/certs/README

@@ -2,8 +2,9 @@ Take care of this folder that could contain private key. Be sure that this folde
 
 Onelogin Python Toolkit expects that certs for the SP could be stored in this folder as:
 
- * sp.key   Private Key
- * sp.crt  Public cert
+ * sp.key     Private Key
+ * sp.crt     Public cert
+ * sp_new.crt Future Public cert
 
 Also you can use other cert to sign the metadata of the SP using the:
 

demo-flask/saml/certs/README

@@ -2,8 +2,9 @@ Take care of this folder that could contain private key. Be sure that this folde
 
 Onelogin Python Toolkit expects that certs for the SP could be stored in this folder as:
 
- * sp.key   Private Key
- * sp.crt  Public cert
+ * sp.key     Private Key
+ * sp.crt     Public cert
+ * sp_new.crt Future Public cert
 
 Also you can use other cert to sign the metadata of the SP using the:
 

demo_pyramid/demo_pyramid/saml/certs/README

@@ -2,8 +2,9 @@ Take care of this folder that could contain private key. Be sure that this folde
 
 Onelogin Python Toolkit expects that certs for the SP could be stored in this folder as:
 
- * sp.key   Private Key
- * sp.crt  Public cert
+ * sp.key     Private Key
+ * sp.crt     Public cert
+ * sp_new.crt Future Public cert
 
 Also you can use other cert to sign the metadata of the SP using the: