Single sign-on public key update

Public

Public Key Expiring on 20 February 2024

On 20 February 2024 AEDT, the PageUp Public Key for SAML Single Sign On (SSO) will expire. As your organisation logs in to PageUp using SAML SSO, you may need to upload an additional key to your SSO infrastructure.

This page is intended for system Superusers & Technical Contacts who manage SAML SSO Identity Providers.

What is the PageUp Public Key?

PageUp's Public Key for SAML SSO is a key that is uploaded to some SAML SSO Identity Providers listing PageUp as an authorised SSO service. This is used by identity providers such as ADFS and Shibboleth for authenticating connections via SAML SSO.

What is changing?

According to standard security practices, Public Keys have a limited usage period and must then be rotated. The PageUp Public Key will be expiring on 20 February 2024, and a replacement Public Key is in place.
The new Public Key is now active and will be required on 20 February 2024. Please use the PageUp Metadata URL to upload the additional certificate to your IDP in preparation for this activation.

PageUp will remove the expired key after 20 February 2024.

The PageUp Metadata URL has been updated to include the new certificate. This Metadata is compatible with SAML ADFS & Shibboleth automatic Metadata retrieval.

What action do I need to take?

A member of the team responsible for managing your SSO systems will be familiar with this process. Please ensure they are aware of this notification and have actioned if required, especially if using ADFS or Shibboleth as the IDP.

Details for the SSO technical team

The Public Key expiry is relevant to all clients using ADFS & Shibboleth Identity Providers.

OKTA & Entra ID (formerly Azure AD) will also require the public key if the requests are encrypted. Where the requests are not encrypted, OKTA & Entra ID (formerly Azure AD) do not require the Public Key, so you may consider this an FYI notification only, with no action required.

The PageUp Metadata URL is not changing, only the content within it.

If you have previously configured one of the below URLs, then running the automated process to refresh the content will be all that's required.

For those SAML Identity Providers which accept Metadata, the PageUp metadata for your region may be accessed below.

To download the below files, right click the below link and click Save link as option.

LIVE/Production
AU - https://metadata-sso.pageuppeople.com/dc2/live/metadata.xml
EMEA - https://metadata-sso.pageuppeople.com/dc3/live/metadata.xml
USA - https://metadata-sso.pageuppeople.com/dc4/live/metadata.xml
APAC - https://metadata-sso.pageuppeople.com/dc5/live/metadata.xml

UAT/Test
AU - https://metadata-sso.pageuppeople.com/dc2/uat/metadata.xml
EMEA - https://metadata-sso.pageuppeople.com/dc3/uat/metadata.xml
USA - https://metadata-sso.pageuppeople.com/dc4/uat/metadata.xml
APAC - https://metadata-sso.pageuppeople.com/dc5/uat/metadata.xml

The Metadata file will include the following

  • X509Certificate (certificate details)
  • validUntil (expiry date)
  • protocolSupportEnumeration (protocol)
  • entityID
  • AssertionConsumerService (assertion endpoints)

Where the Identity Provider does not accept metadata, you may retrieve the new Public Key and create a certificate for manual upload to your Identity Provider.
Note: PageUp recommends the use of the above Metadata where possible.

New PageUp public key

Here is a Base64 version of the PageUp public key, please download this version.
You will need to rename the extension of the downloaded file from *.TXT to *.CER.

Extract the Public Key from PageUp Metadata file

Access the PageUp metadata from the relevant link above.

  • x509Certificate (There are 2 signing certificates, with a x509Certificate “tag” each, please generate both certificates, and update your IDP to include the one that is not currently installed.)

Steps to create a .cer file from the Metadata file (follow exactly without removing):

  1. Open the Metadata URL in browser or download and save as XML and open in a text editor
  2. Copy the details within the <x509 certificate> tag of the metadata file until the end of tag </x509 certificate> (see below screenshot “Figure 1” in step #8)
  3. Open notepad (on Windows)
  4. Type in -----BEGIN CERTIFICATE----- (Copy and paste the bold parts on the left. Do not omit any of the dashes)
  5. Press Enter
  6. Paste in the details you copied earlier (step #2 above)
  7. Press Enter
  8. Type in -----END CERTIFICATE----- (Copy and paste the bold parts on the left. Do not omit any of the dashes)

It needs to look like this (see below)

Figure 1:
certtext.png

  1. Click File and then click Save As
  2. Choose your folder location by selecting it (tip: save it to your DESKTOP folder)
  3. Change the “Save as type:” to “All Files”
  4. Add “.cer” (don’t include the quotes) in the File name. E.g. examplefile.cer
  5. Click Save

This .cer file may then be manually uploaded in to your ADFS or other Identity Provider

Changeover process

Where SAML Identity Provider (IDP) can hold concurrent certificates and the new certificate is uploaded (ADFS & standard Shibboleth):

  1. Client consumes PageUp Metadata
  2. Old and new certificates installed on IDP
  3. 20 February 2024 AEDT PageUp will update to sign using the new (expiry 2024) SAML Public Key

It is also possible for PageUp can configure your PageUp Account to sign with the New Public Key ahead of 20 February 2024 on request. Please see below

Where custom SAML IDP can hold only 1 Public Key:

Where the SAML IDP can hold only 1 certificate, the configuration of both systems will need to be updated at the same time. To minimise disruption, PageUp recommends organising a Teleconference session during normal business hours including:

Recommended attendees:

  • IDP Administrator - To make the change in real time
  • PageUp - To make the PageUp changes detailed below in real time and provide monitoring.
  • PageUp Superuser - to test the SSO before, and after the changeover (Not required if IDP Admin can SSO into PageUp)

The process where only a single certificate may be held in the IDP.

  1. Begin teleconferencing session
  2. Update IDP to the new public key
  3. While this update is underway PageUp to update the configuration to use sign with the new Public Key.
  4. Test & monitor logging (troubleshooting if required)

This process would typically take between 5-10 minutes.

NOTE: Users attempting to access PageUp during the changeover period will likely encounter authentication issues.

Please email support@pageuppeople.com to request a changeover be scheduled.

Update configuration in PageUp

Once both certificates are present in the SAML IDP, the final (optional) step is to update your PageUp system to sign requests with the new PageUp Public Key

NOTE: This step is optional, and should only be undertaken after the new PageUp Public Key has been uploaded in addition to the current (expiring) one. We strongly recommend that the superuser making the change be in contact with your SSO team, and have another SSO enabled user to complete testing.
Will require a PageUp user with Superuser permissions.

To update the setting in PageUp, please follow the below steps.

  1. Login to PageUp (or PageUp UAT if relevant)
  2. Open System settings
  3. Search for and view SAML certificate signing thumbprint
  4. Click Edit icon (Pencil)
  5. Update value from existing value to be:

    5AB45D17D61591A8BCDBB0CE07D79F919692ED55 (note: Do not include additional spaces at the start of end of the value)

  6. Click Save
  7. Click Save changes button at the bottom of the screen

Have another user with SSO access to the system attempt to SSO into PageUp. This is so that you may revert the change should they be unable to login.
Retest again after an additional 3 minutes.

If the user receives an 'Authentication failed' message while testing, please input the original thumbprint value (1D404FB9F0039C6DF3717423305C8D3B6039C1AA) to roll back the change.

If testing is completed successfully, it will now be possible for the SSO team to remove the expiring certificate from the IDP if desired.

Testing

Q: Will we be able to test the new certificate in a testing environment or UAT?
A: As this is a routine change, Dev/UAT testing is not expected to be required. Testing in Dev or UAT will likely require an implementation of SSO in either your Dev IDP or PageUp UAT. As such, testing can be made available on an exception basis if required.

FAQ

Q: Can PageUp confirm if we're using the latest SAML SSO Public Key?
A:
No, we cannot, the team responsible for your SAML Identity Provider will be able to determine this. There is an action which PageUp can perform, requiring the new certificate prior to expiry. Should SSO break following the configuration change, that is a indication that your IT team will be required to take action. This is a highly disruptive way to validate if action is required, and not recommended.

Q: We use Entra ID (formerly Azure AD) or Okta as our IDP, do we need to update the certificate?
A: 
Entra ID (formerly Azure AD) and Okta do require the public key if requests are encrypted. If requests are not encrypted then it is not required to install a copy of the PageUp SAML token signing certificate within the IDP.

Q: We don't upload a Public Key in our SAML SSO Identity Provider, is action required?
A: PageUp recommends that you continue to use Metadata URL even if your IDP does not require you to upload a SAML Public Key.

Q: What is the Metadata URL?
A: Please see the list of Metadata URLs above.

Q: Which of the Metadata URLs is relevant to my organisation?
A: The original notification received regarding this update will include the Metadata URL for your region. PageUp offers different Metadata URLs per region. The regions are denoted by the 'DC' (e.g. DC2 for AUS, DC3 for EU etc) in the URL of the metadata link. When users are logged in to PageUp they will have a DC' in the URL that they are logged in.

Q: When does the current Public Key expire?
A: 20 February 2024

Q: What will happen if we don't update to the new Public Key?
A: Where your SAML Identity Provider requires the Public Key to connect to PageUp servers, Users will receive an 'Authentication Failed' message when attempting to access PageUp via SSO after 20 February 2024.

Q: Is PageUp currently signing with the new or old certificate?
A: PageUp is currently signing SAML responses with the Old public key (expiry 20 February 2024) We will be activating the New public key on 20 February 2024.

Q: What time of day will PageUp be activating the New public key?
A: PageUp will be activating (signing) the New Public Key between 8 AM and 5 PM AEDT.

Q: Is it possible to update PageUp to sign with the New public key only?
A: For clients using IDPs that cannot hold both the old and new public keys concurrently, PageUp can configure your PageUp Account to sign with the New Public Key instead.

Q: Do we need to update the certificate for UAT?
A: For clients using IDPs that hold the PageUp token signing certificate (e.g. ADFS & Shibboleth) if you have a specific and separate SSO infrastructure connected to your UAT, and use it frequently then yes, it's recommended to update the certificate. Otherwise, you can not update it/remove the UAT configuration.

Q: Do you have guides on how to manually update the certificate in ADFS?
A: For clients using the ADFS IDP and do not wish to use the recommended metadata URL, the manual instructions that we have is available here (refer to section 4. Signature).

Troubleshooting

Viewing complete metadata:

Some clients have reported that when viewing the metadata in Mozilla Firefox, there is no binding on the Entity Descriptor. To workaround, please access it in Google Chrome.

Metadata URL - Expiry date (validUntil)

To enable the regular automatic retrieval of PageUp Metadata for SSO, there is a metadata expiry date (validUntil) included. Once expired your IDP is expected to poll our servers for the latest version. If you are downloading then installing the metadata manually, and not activating automated retrieval, you will need to manually update this date prior to importing it to your IDP. This may be done by downloading and then manually updating the XML <SPSSODescriptor><validUntil> value to meet your purposes.

ADFS Error Messages:

Some clients have reported that their ADFS is unable to process metadata when updating existing configurations:

Error message: MSIS7508 The metadata contains unexpected data. Conflicting encryption certificates were found in the RoleDescriptors needed to represent a service provider role.

OR

MSIS0038: SAML Message has wrong signature.

If your ADFS is unable to process the Metadata URL, please extract and manually upload BOTH the old and new certificates from the Metadata URL.

Alternatively, you may download the certificates below then rename to a .cer extension and upload.

NEW - PageUpSSOCertBASE64Exp2025.txt
OLD - PageUpSSOCertBASE64Exp2024.txt

These Certificates will work for Live/Production and UAT/Dev.

When both certificates are uploaded it should look similar to the below from previous years.

2certs.png

Comments

0 comments

Article is closed for comments.