Merge branch 'sp-cert-multi' of github.com:johnnyshields/ruby-saml in…

…to sp-cert-multi

README.md

@@ -739,11 +739,11 @@ validation fails. You may disable such exceptions using the `settings.security[:
 
 Ruby SAML provides the `settings.sp_cert_multi` parameter to enable the following
 advanced usage scenarios:
-- To specify separate SP certificates for signing and encryption.
-- To rotate SP certificates and private keys without disruption of service.
+- Rotating SP certificates and private keys without disruption of service.
+- Specifying separate SP certificates for signing and encryption.
 
 The `sp_cert_multi` parameter replaces `certificate` and `private_key`
-(you may not specify both at the same time.) `sp_cert_multi` has the following shape:
+(you may not specify both pparameters at the same time.) `sp_cert_multi` has the following shape:
 
 ```ruby
 settings.sp_cert_multi = {
@@ -753,16 +753,22 @@ settings.sp_cert_multi = {
   ],
   encryption: [
     { certificate: cert1, private_key: private_key1 },
-    { certificate: cert3, private_key: private_key3 }
+    { certificate: cert3, private_key: private_key1 }
   ],
 }
 ```
 
+Certificate rotation is acheived by inserting new certificates at the bottom of each list,
+and then removing the old certificates from the top of the list once your IdPs have migrated.
+A common practice is for apps to publish the current SP metadata at a URL endpoint and have
+the IdP regularly poll for updates.
+
 Note the following:
-- You may re-use the same certificate and/or private key for both signing and encryption.
-- When signing, Ruby SAML will use the first SP certificate in the `sp_cert_multi[:signing]`
-  array. This will be the first active/non-expired certificate in the array if
-  `settings.security[:check_sp_cert_expiration]` is true.
+- You may re-use the same certificate and/or private key in multiple places, including for both signing and encryption.
+- The IdP should attempt to verify signatures with *all* `:signing` certificates,
+  and permit if *any one* succeeds. When signing, Ruby SAML will use the first SP certificate
+  in the `sp_cert_multi[:signing]` array. This will be the first active/non-expired certificate
+  in the array if `settings.security[:check_sp_cert_expiration]` is true.
 - The IdP may encrypt with any of the SP certificates in the `sp_cert_multi[:encryption]`
   array. When decrypting, Ruby SAML attempt to decrypt with each SP private key in
   `sp_cert_multi[:encryption]` until the decryption is successful. This will skip private