Domino SAML & NFL – Changing the ADFS Certificate

Recently we got contacted by a growing number of customers regarding the change of the SSL Certificate on the ADFS Server used for Domino SAML and Notes NFL. Although the process is not overly complicated, there are some “gotchas” you need to keep in mind in order for this process to go smoothly, which I will try to describe before going through the actual process of changing the certificate.

Plan ahead

Keep in mind that, as soon as you change the certificate on the ADFS Server, SAML/NFL on the Domino/Notes side will not work properly. As there is no Configuration Document in the IdP Catalog which corresponds with this certificate, thus Domino will just drop the Requests signed with the new ADFS Certificate. In this case, you will get the following errors:

SECCheckAndParseSAMLResponse> Signature verification check failed : Could not verify cryptographic signature

SECCheckAndParseSAMLResponse> Exiting : Document has been modified or corrupted since signed! (signature)

Needles to say, this will lead to the SSO Process not working and many angry users…

To remedy this, plan the certificate change so that the impact on the client machine is minimal.

For NFL to work, you need to roll-out the new ADFS Certificate (in case if you are using public CA, you need to roll out the Intermediate and the CA certificate). You would do this via Notes Client Policy, Security Settings. This is not a big deal, but keep in mind that after setting the Policy, the Users need to successfully log in, for the Notes Client to pick up the change and get the new Policy together with the new ADFS Certificate. I have seen some environments were the Notes Client needed multiple restarts to pick up the change.

Now, think about this, the certificate is expiring, and you have to change it in the middle of Christmas holidays, meaning most of the Users are on vacation, so you go ahead, do everything perfectly. But as soon as your users get back from the vacation, they try to login and they get the beautiful error message stating that NFL is not possible at this time and their Notes ID Password is requested. Resulting in Helpdesk calls… Only after they enter the ID Password and successfully login, the Client will get the new certificate and in the future the login will be possible.

In order to get around this, I would recommend rolling out the new certificate as soon as possible, before actually changing it on ADFS.

Check the Certificate Requirements

The worst scenario is using the wrong certificate, so make sure that the Certificate you are using meets the Requirements. If you are using a Self-Signed Certificate, then it must have the “keyCertSign” (also know as “Certificate Signer”) and “cRLSign” (also known as “CRL Signer”) in the “Certificate key usage” field. To check this just open the certificate and inspect that field. If the certificate does not contain these fields, than you will get the following error when you try to create a Cross Certificate from it in the Domino Directory:

“A cross certificate will not be made due to key usage restrictions in the input certificate.”

It also needs to be a “SHA2” or higher. For the full list of Certificate Requirements and more, please read the following article:

https://www-01.ibm.com/support/docview.wss?uid=ibm10718435

If you are using a certificate from the public Authority, then the purchased personal certificate will not contain these values, but this is not a problem, because you can just import the CA and all Intermediate Certificates in the Domino Directory and cross-certify them. After that you can roll-out the the Cross-Certificates via Notes Policy Document.

One customer is planning to use their own internal Windows Certificate Services or Windows PKI, I opened a Support Case regarding this, and got a confirmation that in this case you can also use the CA Certificate of that Authority. We still have not tried that and I didn´t have time to test it out in my Test Environment, but as soon as I have done so, I will post the results.

If the CA and Intermediate Certificates do not change, then you can skip the step of importing and cross-certifying these, as the mentioned certificates do not change.

Steps needed to change the ADFS Certificate

• Check that the new Certificate meets the requirements.
• Import the Certificate (self-signed), or CA and Intermediate Certificates if you are using a Certificate from a public Authority.
• Cross-Certify the Certificate(s).
• Push the newly created Cross Internet Certificates via Notes Policy (Security Settings).
• Change the ADFS Certificate
  • As mentioned, as soon as you do this, the SAML Assertions will fail until you create a new IdP Configuration Document and restart the participating Domino Servers.
• Export the new “FederationMetadata.xml” file from the ADFS Server.
  • You can get the file by using the following URL:
    
  • https://<adfs_server_FQDN>/FederationMetadata/2007-06/FederationMetadata.xml
  • Use the FireFox for downloading the file, sometimes the IE will not get the XML format right (as I had to learn the hard way) and you will get an error when you try to import it in the IdP Catalog.
• Deactivate old Configuration Documents in the IdP Catalog Database.
• Create new IdP Configuration Documents using the new “FederationMetadata.xml” file.
  • After you import the XML File, it will be deleted from the filesystem, so if you need it for another Configuration Document, make a copy of it.
• Replicate the IdP Catalog Database if needed.
• Restart all Domino Servers participating in SAML Authentication.
• Delete the deactivated IdP Configuration Documents after you have made sure that the new Configuration works.