Search

We have renewed our SAML certificate and need to implement the new certificate. How do we accomplish this?

Environment:

• Oracle B2C Service Single Sign-On - all releases

Issue:

Our SAML signing certificate is expiring, so we need to replace it.

Resolution:

Refer to the appropriate steps below, based on whether the authentication flow is initiated by the identity provider (all Customer Portal SSO implementations and some agent SSO implementations) or by Oracle B2C Service as the service provider (agent authentication that managed in Single Sign-On Configurations).

Customer Portal or IdP-initiated agent login

Before certificate cutover has happened on the identity provider (IdP) side:

1. Obtain the signing certificate in .PEM format from your IdP team. If it is in the right format, you can open it in a text editor and it looks something like this:
   -----BEGIN CERTIFICATE-----
MIICJTCCAc+gAwIBAgIUJ1h8+I7IdtJ09o3ToSp6t6UUMtYwDQYJKoZIhvcNAQEL
BQAwZzELMAkGA1UEBhMCVVMxEDAOBgNVBAgMB01vbnRhbmExEDAOBgNVBAcMB0Jv
emVtYW4xGTAXBgNVBAoMEFNhbSdzIEhhbmR3aWNoZXMxGTAXBgNVBAMMEFNhbSdz
IEhhbmR3aWNoZXMwHhcNMjIxMjIxMTgzNDE2WhcNMjMxMjIxMTgzNDE2WjBnMQsw
CQYDVQQGEwJVUzEQMA4GA1UECAwHTW9udGFuYTEQMA4GA1UEBwwHQm96ZW1hbjEZ
MBcGA1UECgwQU2FtJ3MgSGFuZHdpY2hlczEZMBcGA1UEAwwQU2FtJ3MgSGFuZHdp
Y2hlczBcMA0GCSqGSIb3DQEBAQUAA0sAMEgCQQC9lCDgu5bAy7i/pt3f0G8N/1lQ
lP1GaQlH9tTu1gH9zdhK3CI9+m7y7a80+JDOQJEg2NEXUWB7AA93nvTvgAe9AgMB
AAGjUzBRMB0GA1UdDgQWBBR7Pmy8ZGBIvsPExp6zLkQ9SqxcNTAfBgNVHSMEGDAW
gBR7Pmy8ZGBIvsPExp6zLkQ9SqxcNTAPBgNVHRMBAf8EBTADAQH/MA0GCSqGSIb3
DQEBCwUAA0EAnD8VDucCTMGth/v89HfP+M56Z7ShwKONBHnOE76J9oRYD7uvvGv7
Vg/e3bS6N5MRdECJhX0mUJ7Yml/US6Yz/Q==
-----END CERTIFICATE-----
2. Get the certificate fingerprint. See Validating and reviewing the properties of the signing certificate for SSO for more information. Or, if you have access to openssl in a command line, this will give all the information referenced later:
   $ openssl x509 -issuer -subject -pubkey -dates -fingerprint -noout -in example.pem
3. Check that the issuer and subject are the same. If they are not, ensure that the certificate validates with the same chain as the existing certificate, or add the rest of the chain.
4. Copy the SHA-1 fingerprint into a text editor and remove all colons and any whitespace. Here, 05:2B:8C:2F:FF:36:25:61:7D:98:FA:6D:24:F3:84:08:00:FF:EE:15 becomes 052B8C2FFF3625617D98FA6D24F3840800FFEE15.
5. Add the new fingerprint to the configuration setting SAML_20_SIGN_CERTS on the appropriate interface(s) by appending a comma, then the fingerprint without colons. If the old certificate is already expired or is no longer in use, you should just replace the value.
   For example, if the entry currently reads:
   0C2357E5AF8A067C48CA8A2C03F142A3CF9145F4
   then it would be updated to:
   0C2357E5AF8A067C48CA8A2C03F142A3CF9145F4,052B8C2FFF3625617D98FA6D24F3840800FFEE15
6. If you are using Azure AD or AD FS as an identity provider, and the certificate cutover has not yet occurred, add the following to the very beginning of the SAML_20_SIGN_CERTS configuration setting:
   CERT_VALIDATION:IGNORE_TRUST,
   Refer to the documentation and Answer 11049: Using multiple certificates for Customer Portal SSO for further discussion of this setting.
7. Upload the certificate to the "Additional Root Certificates" directory in File Manager. See Answer 9991: Mandatory requirements for all SSO implementations.

Later, once the IdP has started using the new certificate:

1. Remove the expired certificate from the File Manager.
2. Remove the old fingerprint from SAML_20_SIGN_CERTS, as well as CERT_VALIDATION:IGNORE_TRUST if it is no longer needed.

SP-initiated agent login

1. Obtain the new signing certificate in .PEM format from your identity provider, or updated IdP metadata.
2. In Agent Desktop, open Single Sign-On Configurations component.
3. Add the new certificate as an alternate certificate to the appropriate IDP configuration, or reimport the metadata.
4. After certificate cutover, reimport updated metadata again or set the new certificate to primary instead of alternate.
5. Upload the signing certificate and any intermediate certificates into the File Manager (this does not apply if you have selected 'Do not verify trust chain for certificates' on the Identity Provider in the Single Sign-On Configurations component).

Cause:

Certificates expire and must be renewed. Please note that while Oracle B2C Service can have many certificates in its trust store, only the one certificate matching the fingerprint in the assertion will be used for validation. The trust store distrusts any two or more certificates with identical issuer and different public key, regardless of validity dates, etc.

Notes:

The "Do not verify trust chain for certificates" checkbox in Single Sign-On Configurations component and the special prefix "CERT_VALIDATION:IGNORE_TRUST," in SAML_20_SIGN_CERTS only apply to the SAML login flows.

If the signing certificate in the assertion contains a chain of certificates, and you did not check the "Do not verify trust chain for certificates" option or prepend CERT_VALIDATION:IGNORE_TRUST, those other certificates must be uploaded into File Manager as well. A way to determine if your signing certificate contains a chain is to save the certificate as a .cer file and open the certificate file on your desktop. If the "Issued to:" and "Issued by:" do not match on the "General" tab, you will need to upload the intermediate certificates into the File Manager. The full certificate chain should be available on the "Certification Path" tab on the certificate file. If the full chain is not shown on the "Certification Path," you will need to contact your identity provider to get the intermediate certificates. The intermediate certificates can be uploaded under "Additional root certificates" or "Intermediate certificates." Also please be aware that all uploaded certificates must be valid. If any invalid (such as expired) certificates are encountered during the SSO authentication process the authentication will fail.

If you are unsure how to obtain the signing certificate to begin with, consult the documentation for your identity provider. For example: in Oracle Identity Cloud Service, it can be obtained through that product's REST API. Alternatively, your organization may choose to use a certificate purchased from a certificate authority. Consult your IT or security team to understand the impact of the choice of using a self-signed certificate versus a traditional purchased certificate. Since the end-user's browser does not have to trust the certificate, it is common (but not universal) to use a self-signed certificate for SAML authorization.

To access Oracle B2C Service manuals and documentation online, refer to the Documentation for Oracle B2C Service Products.

Documentation: Overview of SAML 2.0 Open Login Single Sign-On