Migration to Federated Sign-In Module v6.5

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:

Configure PAM with the Federated Sign-In module and ensure that it is working properly.
Login to PAM host server.
Execute the following command from $PAM_HOME:

For Windows deployments:

Copy

1
bin\PamDirectory.cmd SwitchCASVersion web 65

For Unix or Linux deployments:

Copy

1
bin/PamDirectory.sh SwitchCASVersion web 65

Stop the PamManagement (Windows) or the pammanager (Linux) service. PAM will be offline until this procedure is completed.
Open a prompt and navigate to the $PAM_HOME directory and delete the old version of CAS:

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).
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).

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.
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:

for AzureAD and ADFS integrations add the following line (with the right index):
Copy
```
1
cas.authn.pac4j.saml[0].useNameQualifier=false
```
for ADFS integrations add the following line (with the right index):
Copy
```
1
cas.authn.pac4j.saml[0].sign-service-provider-logout-request=true
```
for ADFS Relaying party add configuration in ADFS Relaying Party Trusts in the tab Endponts add SAML:

Copy

1
2
3
4
Endpoint Type: SAML Logout
Binding: Redirect
Trusted URL: {managed path}/cas/logout
Response URL: {managed path}/cas/logout

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.

Save and close the catalina.properties file when you are finished.
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.
Start the PamManagement (Windows) or the pammanager (Linux) service and try your updated authentication login.
Verify cas.service-registry.core.init-from-json in catalina.property file:

if value set to true, change it to false:

Copy

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

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

Testing

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

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

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:

Stop the PamManagement (Windows) or the pammanager (Linux) service. PAM will be offline until this procedure is completed.
Open a prompt and navigate to the $PAM_HOME directory and delete the old version of CAS.

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).
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).

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

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

(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.
Execute the following command to switch PAM configuration to version CAS 5.2:

For Windows deployments:

Copy

1
bin\PamDirectory.cmd SwitchCASVersion web 52

For Unix or Linux deployments:

Copy

1
bin/PamDirectory.sh SwitchCASVersion web 52

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

Troubleshooting

Federated Sign-in module version 6.5 Troubleshooting.

Application not Authorized error message

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:

Copy

1
cas.serviceRegistry.initFromJson=true

Restart the PamManagement (Windows) or the pammanager (Linux) service.
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
```
1
cas.serviceRegistry.initFromJson=false
```
Restart the PamManagement (Windows) or the pammanager (Linux) service.