Migration to Federated Sign-In Module v6.5

Upgrading to the latest version of PAM provides you with enhanced security, improved performance, and access to all the newest features and enhancements we offer. To fully benefit from these improvements and ensure optimal compatibility, we encourage you to update your Java environment to at least the minimum supported version.

The third-party vendor we rely on for federated sign-in, has discontinued support for version 5.2. As a result, any future enhancements to the PAM authentication module will be compatible only with Federated Sign-in v6.5. This is a crucial change that needs to be addressed to maintain the security and functionality of your federated sign-in process.

There are no risks in migrating PAM functionality as all features will be available. However, while updating, the federated plugin in v6.5 can impact your SAML integration, specifically regarding keystores and metadata files. Tokens generated with older versions will not work after the migration, so you must generate new ones as instructed in the guide.

Pre-requisites

Before you begin your migration, be sure you meet the following pre-requisites:

  • A working PAM deployment with the Federated Sign-In experience.

  • In order to check the version of Federated Sign-In module you are on, login to PAM and navigate to Management> About and check value under "Authentication" . If you are on version 5x, the value will be version 5.2x.

  • An operational PAM deployment with the latest version. Please update to the latest available version before proceeding.

  • WEB Container on version 9.0.x.

  • An operational PAM deployment with framework version 11, 12,13, 14, 15 or 17. If you are using 1.8_x, please use this guide to update.

For PAM deployments integrated with SSO providers,  it is necessary to reconnect SSO integration after upgrading from Federated Sign-In module version 5.2 to version 6.5. This is required because version 6.5 uses different key generation algorithms that are not compatible with the old version. The new keystore .jks and .xml metadata files should appear in $PAM_HOME/content/keys or another location that was defined in your configuration.

Optionally, rather than deleting these files, move the version 5.2 files to a backup location outside of $PAM_HOME.

Considerations

  • The user performing the migration will be required to update files and configurations on the PAM host server. Administrative privileges are required.

  • We highly recommend deploying a test instance of PAM that mirrors your production instance as closely as possible to test the migration (DB type, Federated Sign-In, certificates, MFA/SSO, AD Integration, etc).

  • Once the migration is successful with the test instance you can reproduce the procedure on your production instance.

Please read the entire procedure outlined in the article before beginning. If you have any questions, please contact our Support team: https://support.imprivata.com/.

Migration from version 5.2x to version 6.5

For migration from Federated Sign-In module version 5.2x to Federated Sign-in module version 6.5 follow the next steps:

  1. Configure PAM with the Federated Sign-In module and ensure that it is working properly.

  2. Login to PAM host server.

  3. Execute the following command from $PAM_HOME:

    4. For Windows deployments:

    Copy 
    bin\PamDirectory.cmd SwitchCASVersion web 65

    For Unix or Linux deployments:

    Copy 
    bin/PamDirectory.sh SwitchCASVersion web 65

  4. Stop the PamManagement (Windows) or the pammanager (Linux) service. PAM will be offline until this procedure is completed.

  5. Open a prompt and navigate to the $PAM_HOME directory and delete the old version of CAS:

    1. Delete (or move) the file $PAM_HOME/web/webapps/cas.war (move this file outside of $PAM_HOME folder, please do not rename it in the same folder).

    2. Delete (or move) the folder $PAM_HOME/web/webapps/cas (move this file outside of $PAM_HOME folder, please do not rename ti in the same folder).

  6. Download a new CAS version 6.5 file https://bin.xtontech.com/product/pam-cas.65.zip and extract the cas.war to $PAM_HOME/web/webapps.

  7. Open the file $PAM_HOME/web/conf/catalina.properties in a text editor. In this file, locate the section that begins with #CAS add the following new parameters:

    1. for AzureAD and ADFS integrations add the following line (with the right index):

      Copy 
      cas.authn.pac4j.saml[0].useNameQualifier=false

    2. for ADFS integrations add the following line (with the right index):

      Copy 
      cas.authn.pac4j.saml[0].sign-service-provider-logout-request=true

    If you are unsure if you are using an Azure AD or ADFS SAML integration, please review the following:

    • If your SSO login redirects to a microsoftonline domain, it is likely Azure AD SSO.

    • If your SSO login redirects to your domain, it is likely ADFS.

    • You can also review the respective integration guides, Azure AD SSO and ADFS, to check your current configuration to determine which integration is currently enabled.

  8. Save and close the catalina.properties file when you are finished.

  9. for ADFS Relaying party add configuration in ADFS Relaying Party Trusts in the tab Endpoints add SAML:

    10. Copy 
    Endpoint Type: SAML Logout
    Binding: Redirect
    Trusted URL: {managed path}/cas/logout
    Response URL: {managed path}/cas/logout

  10. If there are existing SSO integrations with PAM, you will need to generate new keystore .jks and .xml metadata files for all SSO integrations. This is required to the fact that the new CAS version 6.5 uses different key generation algorithms that are not compatible with the old version. To generate these metadata files, navigate to the $PAM_HOME/content/keys directory and delete all SSO related keystore .jks and .xml metadata files.

    We recommended, rather than deleting these files, move them to a backup location outside of $PAM_HOME. These new metadata files will be regenerated during the service restart in the next step.

    Note that you may need to upload the new .xml file to your SSO provider to complete the integration process. Please review the specific integration documentation for your SSO provider to determine if a reupload is required. Here are links to some of our SSO integration articles: OneSign, Azure SSO, Okta SSO.

  11. Start the PamManagement (Windows) or the pammanager (Linux) service and try your updated authentication login.

  12. Verify cas.service-registry.core.init-from-json in catalina.properties file:

    • if value set to true, change it to false:

      Copy 
      cas.service-registry.core.init-from-json=false

    • restart the PamManagement (Windows) or the pammanager (Linux) service and try your updated authentication login.

  13. Clear your browser cache.

  14. Tokens generated with older version of Federated Sign in will not work post migration. New tokens will need to be generated by navigating to Administration > Tokens > Generate Token.

Testing

The steps for testing Federated Sign-in module version 6.5:

  1. When the service is fully restarted, open your browser, and navigate to the PAM login page.

  2. Login to PAM.

Rollback from version 6.5 to version 5.2

To rollback from Federated Sign-in module version 6.5 to Federated Sign-in module version 5.2:

  1. Stop the PamManagement (Windows) or the pammanager (Linux) service. PAM will be offline until this procedure is completed.

  2. Open a prompt and navigate to the $PAM_HOME directory and delete the old version of CAS.

    1. Delete (or move) the file $PAM_HOME/web/webapps/cas.war (move this file outside of $PAM_HOME folder, please do not rename it in the same folder).

    2. Delete (or move) the folder $PAM_HOME/web/webapps/cas (move this file outside of $PAM_HOME folder, please do not rename it in the same folder).

  3. Restore the file cas.war for CAS version 5.2 to $PAM_HOME/web/webapps from the backup location or download the latest from:

    4. https://bin.xtontech.com/product/pam-cas.zip.

  4. (Optionally, for SSO integrations) restore the keystore .jks and .xml metadata files for CAS version 5.2 to $PAM_HOME/content/keys/ from the backup location or regenerate them.

  5. Execute the following command to switch PAM configuration to version CAS 5.2:

    6. For Windows deployments:

    Copy 
    bin\PamDirectory.cmd SwitchCASVersion web 52

    For Unix or Linux deployments:

    Copy 
    bin/PamDirectory.sh SwitchCASVersion web 52

  6. Start the PamManagement (Windows) or the pammanager (Linux) service.

Troubleshooting

Federated Sign-in module version 6.5 Troubleshooting.

Application not Authorized error message

Aplication-Not-Authorized-Message.png

  1. Open the file $PAM_HOME/web/conf/catalina.properties in a text editor. In this file, locate the section that begins with #CAS and change the following parameter set it to true:

    2. Copy 
    cas.serviceRegistry.initFromJson=true

  2. Restart the PamManagement (Windows) or the pammanager (Linux) service.

  3. Once PAM is working and you can see the usual CAS login page, back to the file $PAM_HOME/web/conf/catalina.properties in a text editor. Find the section that begins with #CAS and change cas.serviceRegistry.initFromJson parameter back to false:

    Copy 
    cas.serviceRegistry.initFromJson=false

  4. Restart the PamManagement (Windows) or the pammanager (Linux) service.

FAQs

We understand that upcoming changes to our PAM solution may raise questions, and we want to ensure you have all the information you need. This section is designed to help you better understand the enhancements we're making, how they benefit you, and what steps you might need to take. By providing clear answers to common questions, we aim to make the transition as smooth as possible and have representation about ‘Why These Changes Are Better for Our Customers’. We encourage you to read through these FAQs, and as always, feel free to reach out to us if you have any further inquiries. If questions remain or issues arise while using PAM, please contact the Support team: https://support.imprivata.com/.

 

Question: What are the high-level benefits we will gain from the upgrade?

Answer: Upgrading to the latest version of PAM provides you with enhanced security, improved performance, and access to all the newest features and enhancements we offer. To fully benefit from these improvements and ensure optimal compatibility, we encourage you to update your Java environment to at least the minimum supported version.

 

Question: Why is future support for federated sign-in in PAM limited to Federated Sign-in version 6.5?

Answer: The third-party vendor we rely on for federated sign-in, has discontinued support for version 5.2. As a result, any future enhancements to the PAM authentication module will be compatible only with Federated Sign-in v6.5. This is a crucial change that needs to be addressed to maintain the security and functionality of your federated sign-in process.

 

Question: Are there any risks in migrating to version 6.5 that should be mitigated?

Answer: There are no risks in migrating PAM functionalities as all features will be available. However, while updating, the federated plugin in v6.5 can impact your SAML integration, specifically regarding keystores and metadata files. Tokens generated with older versions will not work after the migration, so you must generate new ones as instructed in the guide.