Add new doc topic: "Configuring SAML Web Browser SSO in Liberty when FIPS 140-3 is Enabled"

[Zech-Hein]

Please describe the problem you are having with the documentation. Is information missing, inaccurate, or unclear? Tell us about the context where you encountered the problem so we can understand how to address it.

This is part of the new documentation for #7962

Target: 25.0.0.12

Doc to be updated: https://www.ibm.com/docs/en/was-liberty/base?topic=liberty-configuring-saml-web-browser-sso-in
(nest the new topic: "Configuring SAML Web Browser SSO in Liberty when FIPS 140-3 is Enabled" under "Configuring SAML Web Browser SSO in Liberty")

Configuring SAML Web Browser SSO in Liberty when FIPS 140-3 is Enabled

25.0.0.12+ Liberty SAML Web Browser SSO encryption supports ECDH-ES key exchange which is IBM Semeru FIPS 140-3 certified. However, if your SAML provider does not support ECDH-ES and uses RSA-OAEP key agreement instead, see the section titled SAML using RSA-OAEP example below.

Note: The FIPS module in use by the IBM Semeru runtime is planning to certify RSA-OAEP operations in a future release.

Enabling SAML assertion encryption when FIPS 140-3 is enabled

By default, the generated Liberty spmetadata will not contain the encryption key when FIPS 140-3 is enabled. The encryption key is the public key in the Keystore that is being used that contains the keys. Follow the steps below to update SAML metadata to add the encryption key.

After FIPS 140-3 is configured for Liberty, you need to download the metadata for the SP from a browser with the SP metadata URL and update the encryption configuration as shown below.

<KeyDescriptor use="signing">
    <ds:KeyInfo>
        <ds:X509Data>
            <ds:X509Certificate>
                MIIDRzCCAi…Bt0qxFS
            </ds:X509Certificate>
        </ds:X509Data>
    </ds:KeyInfo>
</KeyDescriptor>

<!-- Add the following to add the encryption key. Note the public key is the same as the one used in signing -->
<KeyDescriptor use="encryption">
    <ds:KeyInfo>
        <ds:X509Data>
            <ds:X509Certificate>
                MIIDRzCCAi…Bt0qxFS
            </ds:X509Certificate>
        </ds:X509Data>
    </ds:KeyInfo>
</KeyDescriptor>

Now, this samlMetadata.xml is ready to be installed to the IDP.

SAML using RSA-OAEP example

Note: All valid SAML Web SSO configurations in Liberty prior to 25.0.0.12 used RSA keys as signing and encryption keys. When RSA keys are used as encryption keys, RSA-OAEP is used as the key agreement algorithm (when FIPS 140-3 is disabled).

If your SAML configuration uses RSA keys, and you have added the public key as your encryption key to your samlMetadata.xml file - you can try and add the following to the FIPS140-3-Liberty-Application.properties custom profile file created when FIPS 140-3 is configured:

RestrictedSecurity.OpenJCEPlusFIPS.FIPS140-3-Liberty-Application.jce.provider.2 = sun.security.provider.Sun [+ \
    {MessageDigest, SHA-1, *, FullClassName:org.apache.xml.security.encryption.XMLCipher}]
RestrictedSecurity.OpenJCEPlusFIPS.FIPS140-3-Liberty-Application.jce.provider.4 = com.sun.crypto.provider.SunJCE [+ \
    {Cipher, RSA, *, FullClassName:org.apache.xml.security.encryption.XMLCipher}, \
    {Cipher, AES, *, FullClassName:org.apache.xml.security.encryption.XMLCipher}]

Note: this is just one example, and you may need different constraints based on your application.

This will add the constraints to the already registered Sun and SunJCE providers to allow for RSA-OAEP key agreement algorithm. As mentioned above, the constraints to be added will be discovered through the testing process.

Supported Signature Method algorithm options When FIPS 140-3 Mode Is Enabled

Supported:
SHA256
25.0.0.12+ SHA384
25.0.0.12+ SHA512
25.0.0.12+ ECDSAwithSHA256
25.0.0.12+ ECDSAwithSHA384
25.0.0.12+ ECDSAwithSHA512

Not Supported:
SHA1

Example Usage

<samlWebSso20 id="defaultSP" signatureMethodAlgorithm="SHA256" />

Supported Encryption algorithms When FIPS 140-3 Mode Is Enabled

Supported:
ECDH-ES

Not Supported:
RSA-OAEP encryption key transport when SAML encryption is enabled.
Note: The FIPS module in use by the IBM Semeru runtime is planning to certify RSA-OAEP operations in a future release.

[Zech-Hein]

Closing this issue as it will be delivered under the websphere docs repo since we decided to update an ibm doc page instead of the openliberty doc page.

New issue: https://github.ibm.com/websphere/liberty-docs/issues/4600

[Zech-Hein]

The initially desired update we were planning to make was the folowing

File to be updated: https://github.com/OpenLiberty/docs/blob/28ba7cdf01f5e7b64c9bdc37f0cf35799d586ebe/modules/reference/pages/feature/samlWeb/examples.adoc
which will get added to https://openliberty.io/docs/latest/reference/feature/samlWeb-2.0.html
We want to add an "example" sub-section called "Configure SAML when FIPS 140-3 is enabled"