Exporting Your Data Out of Stormpath

Introduction

As part of the Stormpath team joining Okta, the Stormpath API will be shutting down 2017-08-17 at noon PST. To help customers transition, Stormpath has created an export tool that will allow you to safely move your data out of Stormpath. While we hope that all Stormpath users decide to become happy Okta users, this document contains instructions both for those who have decided to transition to Okta and those who have not.

What is the Stormpath Export Process?

The Stormpath export tool is launched from within the Stormpath Admin Console by a Tenant Administrator. This kicks off an asynchronous export process of your Stormpath Tenant. The end result is an encrypted ZIP file containing all of your user data (including hashed passwords) in JSON format.

Once your data is exported, you can use the Okta import tool (available late April) to import your data into Okta. Otherwise, you can import the data into your identity solution of choice.

Minimizing Production Downtime

To minimize production downtime, we recommend you follow a three step process:

  • Perform an export as described below and import your data into your new identity management platform.
  • Update your application to use the new platform (for example the updated, Okta-linked integrations).
  • Perform another export out of Stormpath, and import that data into your new platform again.

These two migrations should catch all the data that changed during the original migration process.

What happens during export?

The export process starts with a message passed via the Amazon SQS queue. The body of this message contains your confidential export data (such as the password you choose for the ZIP file) and it is encrypted via AES256-CBC. The export process runs on an isolated EC2 instance that is solely dedicated to processing data exports and is not accessible to any Stormpath employees. Once the export process has finished, the folder containing the exported information is compressed into an encrypted zip file, using the password you supplied. It will then be uploaded to an Amazon S3 bucket, and a link will be privately emailed to you. The upshot of all this is that none of your sensitive data is ever transmitted in an unencrypted format, even in our backend.

Any exported data will be available for export until the service is shut down on 8/17/2017 at noon PST.

How to export your data out of Stormpath

To export your data, please perform the following steps:

  • Log into the Stormpath Admin Console with a Tenant Administrator account.
  • Click the “Begin Tenant Data Export” button located on the right side of the Stormpath Admin Console homepage.
  • Enter an email address and password in the dialog that appears. Stormpath will send the download link to this email address and use the password to encrypt the zip file. You will need to supply the same password to open the zip file. Make sure to choose a strong (one that is long and cannot be easily guessed by a person or a computer) password here.

Once the export process is finished, Stormpath will email you a link to your ZIP file. This link will remain valid for 24 hours.

What is inside the export ZIP file?

Inside the export ZIP file, you will find directories organized by Stormpath resource type for this particular Tenant. If you have multiple Tenants, you will need to export the data from each one separately.

Inside each directory there is one JSON file per resource, using the naming convention $RESOURCE_ID.json.Each of these files contains information about that resource in JSON format. The information is similar to what you would receive if you sent a GET request to the Stormpath API. For example, if you opened 10ECOvzCA1izBilzDtgh6g.json, you would find the following:

This data is an exact copy of what the Stormpath API outputs, with a few exceptions:
– Certain built-in linked resources (like CustomData, for instance), have been automatically expanded.
– An id attribute has been added to each unique resource so that you can easily find the linked resource’s JSON file in the export data.

With this structure, it is possible to fully replicate all Stormpath data relationships, and traverse the entire Stormpath tenant’s data in a simple manner.

How to use the hashed passwords

If you are not planning on migrating to Okta, your application will need some way of evaluating the password that a user input and comparing it to the stored password hash. Depending on when the accounts were last accessed, the password hashes will either be in bcrypt or Stormpath HMAC format. Since Stormpath deprecated the HMAC hash some time ago, you will most likely not see any passwords hashed with it. If your export does contain passwords hashed with Stormpath HMAC, they will begin with $stormpath. Those in bcrypt format will start with $2.

Below we have included examples in multiple languages of how you can valiate the bcrypt hashes. In the unlikely event that your passwords are hashed with Stormpath HMAC, we have also included examples of how you can validate the those hashes at the bottom of this page. If you have any questions, please contact support.

Java (Bcrypt Hash Validation)

Include Maven/Gradle dependency:

Verify a hash:

Javascript (Bcrypt Hash Validation)

.NET (Bcrypt Hash Validation)

Install BCrypt package:

Verify a hash:

Online fiddle example: https://dotnetfiddle.net/P3werk

.NET (HMAC Hash Validation)

Online fiddle example: https://dotnetfiddle.net/l0TFlD

Python (Bcrypt Hash Validation)

PHP (Bcrypt Hash Validation)

Ruby (Bcrypt Hash Validation)

Java (HMAC Hash Validation)