Troubleshooting: SecureStorageApi Errors During an Upgrade or Migration

Version Affected: 19.07+
 
 

Overview

The SecureStorageApi — the service that stores and migrates encrypted credentials such as datastore and service-account passwords — can throw errors during an upgrade or migration. These causes are not related to each other, but each produces a SecureStorageApi error during an upgrade or migration:

• See Cause 1 - a non-Primary FileSync server was upgraded before the Primary server.
• See Cause 2 - the SecureStore's data was corrupted during the migration and needs to be viewed or recreated.
• See Cause 3 - creating a new SecureStore returns a 500 error.

In this article

• Cause 1: Wrong Upgrade Order in a FileSync Cluster
• Cause 2: SecureStore Data Corrupted During Migration
• Cause 3: Creating a New SecureStore Returns a 500 Error

Cause 1: Wrong Upgrade Order in a FileSync Cluster

The Primary FileSync server is the authoritative source for the SecureStore. If a Secondary server is upgraded before the Primary, the SecureStore isn't in the same location on the Secondary as it is on the Primary, and SecureStorageApi errors follow. 

Resolution 1:

Always upgrade the Primary FileSync server first in a FileSync cluster.

Cause 2: SecureStore Data Corrupted During Migration

The SecureStore migrates during any upgrade or migration, and that migration can occasionally leave the SecureStore's data corrupted. 

Resolution 2:

To view the current SecureStore data, browse to the following URL (substituting the actual SecureStore DB ID):

https://localhost/SecureStorageApi/keychain/v1/secure_stores/<STORE_ID>/credentials

The <STORE_ID> is the SecureStore DB ID, found in D:\SecureAuth\SecureStorageApi\SecureAuth Corporation\SecureStore\Data.

This URL shows every username and password in clear text — treat the output as sensitive.

To create a new SecureStore database instead, run the following as an Administrator:

Invoke-RestMethod -Method 'Post' -Uri 'https://localhost/SecureStorageApi/keychain/v1/secure_stores' -ContentType 'application/json'

Once the new SecureStore is created, update GlobalSettings.json with its new SecureStore ID.

Cause 3: Creating a New SecureStore Returns a 500 Error

Creating a new SecureStore (as described under Cause 2) can fail with a 500 error for either of two certificate-related reasons:

• The certificate bound in IIS doesn't have localhost as a Subject Alternative Name (SAN) — most issued certificates don't, since the create request above always targets localhost.
• The certificate referenced in GlobalSettings.json has expired.

Resolution 3:

For a missing localhost SAN, add a line to the server's hosts file pointing the certificate's actual name at 127.0.0.1 (loopback) — this is the easiest fix and shouldn't cause any other issues.

For an expired certificate, open GlobalSettings.json to find the configured certificate thumbprint, locate that certificate in the Certificates console, and confirm whether it has expired. If it has, find a valid SecureAuth certificate and replace the thumbprint in GlobalSettings.json with its thumbprint, then try again.


 

SecureAuth Knowledge Base Articles provide information based on specific use cases and may not apply to all appliances or configurations. Be advised that these instructions could cause harm to the environment if not followed correctly or if they do not apply to the current use case.

Customers are responsible for their own due diligence prior to utilizing this information and agree that SecureAuth is not liable for any issues caused by misconfiguration directly or indirectly related to SecureAuth products.